c11bf1d fix(auth): add token cache and fix scope validation · gordon

M docs/getting-started.md +55 -7


@@ -7,6 +7,7 @@ Deploy your first app with Gordon in under 5 minutes.
7	7		- A Linux VPS with Docker or Podman installed
8	8		- A domain pointing to your VPS (DNS A record)
9	9		- Cloudflare account (free tier) for HTTPS termination
	10	+	- [pass](https://www.passwordstore.org/) (password manager) with GPG key initialized
10	11
11	12		## 1. Install Gordon
12	13

@@ -16,7 +17,7 @@ curl -fsSL https://gordon.bnema.dev/install \| bash
16	17
17	18		This script automatically detects your OS and architecture, downloads the appropriate binary, and installs it to `/usr/local/bin`.
18	19
19		-	## 2. Start Gordon
	20	+	## 2. Initialize Configuration
20	21
21	22		```bash
22	23		# First run creates the default config

@@ -26,7 +27,41 @@ gordon serve
26	27
27	28		Config is created at `~/.config/gordon/gordon.toml`.
28	29
29		-	## 3. Configure Your Registry Domain
	30	+	## 3. Set Up Authentication
	31	+
	32	+	Gordon requires a `token_secret` for JWT authentication. We recommend using `pass` to store secrets securely.
	33	+
	34	+	> Local development? If you just want to try Gordon locally, you can disable auth temporarily:
	35	+	> ```toml
	36	+	> [auth]
	37	+	> enabled = false
	38	+	> ```
	39	+	> Skip to [Step 4](#4-configure-your-registry-domain). For production, continue below.
	40	+
	41	+	Initialize pass (if not already done):
	42	+	```bash
	43	+	# Generate a GPG key if you don't have one
	44	+	gpg --gen-key
	45	+
	46	+	# Initialize pass with your GPG key ID
	47	+	pass init <your-gpg-key-id>
	48	+	```
	49	+
	50	+	Create the JWT token secret:
	51	+	```bash
	52	+	# Generate and store a random 32-character secret
	53	+	openssl rand -base64 32 \| pass insert -m gordon/auth/token_secret
	54	+	```
	55	+
	56	+	Update your config (`~/.config/gordon/gordon.toml`):
	57	+	```toml
	58	+	[auth]
	59	+	enabled = true
	60	+	secrets_backend = "pass"
	61	+	token_secret = "gordon/auth/token_secret"
	62	+	```
	63	+
	64	+	## 4. Configure Your Registry Domain
30	65
31	66		Edit `~/.config/gordon/gordon.toml`:
32	67

@@ -34,13 +69,13 @@ Edit `~/.config/gordon/gordon.toml`:
34	69		[server]
35	70		port = 8080 # Proxy port (use with Cloudflare)
36	71		registry_port = 5000 # Registry port
37		-	gordon_domain = "gordon.mydomain.com" # Your Gordon domain
	72	+	gordon_domain = "gordon.mydomain.com" # Your Gordon domain
38	73
39	74		[routes]
40	75		"app.mydomain.com" = "myapp:latest" # Domain → Image mapping
41	76		```
42	77
43		-	## 4. Set Up DNS
	78	+	## 5. Set Up DNS
44	79
45	80		In Cloudflare (or your DNS provider):
46	81

@@ -51,7 +86,7 @@ In Cloudflare (or your DNS provider):
51	86
52	87		Enable Cloudflare proxy (orange cloud) for HTTPS.
53	88
54		-	## 5. Start Gordon as a Service
	89	+	## 6. Start Gordon as a Service
55	90
56	91		```bash
57	92		# Create systemd user service

@@ -75,11 +110,24 @@ systemctl --user enable --now gordon
75	110		sudo loginctl enable-linger $USER
76	111		```
77	112
78		-	## 6. Deploy Your First App
	113	+	## 7. Generate a Deploy Token
	114	+
	115	+	Create a token for pushing images to your registry (skip if auth is disabled):
	116	+
	117	+	```bash
	118	+	gordon auth token generate --subject deploy --scopes push,pull --expiry 0
	119	+	```
	120	+
	121	+	Save this token securely - you'll need it for Docker login.
	122	+
	123	+	## 8. Deploy Your First App
79	124
80	125		On your local machine:
81	126
82	127		```bash
	128	+	# Log in to your Gordon registry (skip if auth is disabled)
	129	+	docker login -u deploy -p <your-token> registry.mydomain.com
	130	+
83	131		# Build your app
84	132		docker build -t myapp .
85	133

@@ -92,7 +140,7 @@ docker push registry.mydomain.com/myapp:latest
92	140
93	141		Your app is now live at `https://app.mydomain.com`!
94	142
95		-	## 7. Update Your App
	143	+	## 9. Update Your App
96	144
97	145		Push a new image to deploy with zero downtime:
98	146

 - A Linux VPS with Docker or Podman installed
 - A domain pointing to your VPS (DNS A record)
 - Cloudflare account (free tier) for HTTPS termination
+- [pass](https://www.passwordstore.org/) (password manager) with GPG key initialized
 ## 1. Install Gordon
 This script automatically detects your OS and architecture, downloads the appropriate binary, and installs it to `/usr/local/bin`.
-## 2. Start Gordon
+## 2. Initialize Configuration
 ```bash
 # First run creates the default config
 Config is created at `~/.config/gordon/gordon.toml`.
-## 3. Configure Your Registry Domain
+## 3. Set Up Authentication
+Gordon requires a `token_secret` for JWT authentication. We recommend using `pass` to store secrets securely.
+> **Local development?** If you just want to try Gordon locally, you can disable auth temporarily:
+> ```toml
+> [auth]
+> enabled = false
+> ```
+> Skip to [Step 4](#4-configure-your-registry-domain). For production, continue below.
+**Initialize pass (if not already done):**
+```bash
+# Generate a GPG key if you don't have one
+gpg --gen-key
+# Initialize pass with your GPG key ID
+pass init <your-gpg-key-id>
+```
+**Create the JWT token secret:**
+```bash
+# Generate and store a random 32-character secret
+openssl rand -base64 32 | pass insert -m gordon/auth/token_secret
+```
+**Update your config** (`~/.config/gordon/gordon.toml`):
+```toml
+[auth]
+enabled = true
+secrets_backend = "pass"
+token_secret = "gordon/auth/token_secret"
+```
+## 4. Configure Your Registry Domain
 Edit `~/.config/gordon/gordon.toml`:
 [server]
 port = 8080                              # Proxy port (use with Cloudflare)
 registry_port = 5000                     # Registry port
-gordon_domain = "gordon.mydomain.com"      # Your Gordon domain
+gordon_domain = "gordon.mydomain.com"    # Your Gordon domain
 [routes]
 "app.mydomain.com" = "myapp:latest"      # Domain → Image mapping
 ```
-## 4. Set Up DNS
+## 5. Set Up DNS
 In Cloudflare (or your DNS provider):
 Enable Cloudflare proxy (orange cloud) for HTTPS.
-## 5. Start Gordon as a Service
+## 6. Start Gordon as a Service
 ```bash
 # Create systemd user service
 sudo loginctl enable-linger $USER
 ```
-## 6. Deploy Your First App
+## 7. Generate a Deploy Token
+Create a token for pushing images to your registry (skip if auth is disabled):
+```bash
+gordon auth token generate --subject deploy --scopes push,pull --expiry 0
+```
+Save this token securely - you'll need it for Docker login.
+## 8. Deploy Your First App
 On your local machine:
 ```bash
+# Log in to your Gordon registry (skip if auth is disabled)
+docker login -u deploy -p <your-token> registry.mydomain.com
 # Build your app
 docker build -t myapp .
 Your app is now live at `https://app.mydomain.com`!
-## 7. Update Your App
+## 9. Update Your App
 Push a new image to deploy with zero downtime:

M internal/adapters/in/cli/auth.go +37 -33


@@ -352,31 +352,15 @@ The hash can be stored in your secrets backend and referenced in the config:
352	352		}
353	353
354	354		// runTokenGenerate generates a new authentication token.
355		-	func runTokenGenerate(subject, scopesStr, expiryStr, configPath string) error {
356		-	cfg, err := loadAuthConfig(configPath)
357		-	if err != nil {
358		-	return err
359		-	}
360		-
361		-	// Parse expiry (supports human-friendly units: d, w, M, y)
362		-	var expiry time.Duration
363		-	if expiryStr != "0" {
364		-	expiry, err = duration.Parse(expiryStr)
365		-	if err != nil {
366		-	return fmt.Errorf("invalid expiry duration: %w", err)
367		-	}
368		-	}
369		-
370		-	// Parse scopes and convert simple scopes to Docker v2 format
371		-	// Simple scopes like "push,pull" become "repository:*:push,pull"
	355	+	// parseAndConvertScopes parses a comma-separated scope string and converts
	356	+	// simple scopes (push, pull, ) to Docker v2 format (repository::action).
	357	+	func parseAndConvertScopes(scopesStr string) []string {
372	358		rawScopes := strings.Split(scopesStr, ",")
373	359		for i := range rawScopes {
374	360		rawScopes[i] = strings.TrimSpace(rawScopes[i])
375	361		}
376	362
377	363		// Check if scopes are already in v2 format (contain colons)
378		-	// or if they're simple scopes that need conversion
379		-	var scopes []string
380	364		hasSimpleScope := false
381	365		for _, s := range rawScopes {
382	366		if !strings.Contains(s, ":") && (s == "push" \|\| s == "pull" \|\| s == "*") {

@@ -385,24 +369,44 @@ func runTokenGenerate(subject, scopesStr, expiryStr, configPath string) error {
385	369		}
386	370		}
387	371
388		-	if hasSimpleScope {
389		-	// Convert simple scopes to v2 format: repository:*:push,pull
390		-	var actions []string
391		-	for _, s := range rawScopes {
392		-	if s == "push" \|\| s == "pull" \|\| s == "*" {
393		-	actions = append(actions, s)
394		-	} else {
395		-	// Keep non-simple scopes as-is (e.g., admin scopes)
396		-	scopes = append(scopes, s)
397		-	}
	372	+	if !hasSimpleScope {
	373	+	return rawScopes
	374	+	}
	375	+
	376	+	// Convert simple scopes to v2 format: repository:*:push,pull
	377	+	var scopes []string
	378	+	var actions []string
	379	+	for _, s := range rawScopes {
	380	+	if s == "push" \|\| s == "pull" \|\| s == "*" {
	381	+	actions = append(actions, s)
	382	+	} else {
	383	+	// Keep non-simple scopes as-is (e.g., admin scopes)
	384	+	scopes = append(scopes, s)
398	385		}
399		-	if len(actions) > 0 {
400		-	scopes = append(scopes, "repository:*:"+strings.Join(actions, ","))
	386	+	}
	387	+	if len(actions) > 0 {
	388	+	scopes = append(scopes, "repository:*:"+strings.Join(actions, ","))
	389	+	}
	390	+	return scopes
	391	+	}
	392	+
	393	+	func runTokenGenerate(subject, scopesStr, expiryStr, configPath string) error {
	394	+	cfg, err := loadAuthConfig(configPath)
	395	+	if err != nil {
	396	+	return err
	397	+	}
	398	+
	399	+	// Parse expiry (supports human-friendly units: d, w, M, y)
	400	+	var expiry time.Duration
	401	+	if expiryStr != "0" {
	402	+	expiry, err = duration.Parse(expiryStr)
	403	+	if err != nil {
	404	+	return fmt.Errorf("invalid expiry duration: %w", err)
401	405		}
402		-	} else {
403		-	scopes = rawScopes
404	406		}
405	407
	408	+	scopes := parseAndConvertScopes(scopesStr)
	409	+
406	410		// Create auth service
407	411		log := zerowrap.New(zerowrap.Config{Level: "warn"})
408	412		authSvc, err := createAuthServiceForCLI(cfg, log)


@@ -352,31 +352,15 @@ The hash can be stored in your secrets backend and referenced in the config:
352		}	352		}
353			353
354		// runTokenGenerate generates a new authentication token.	354		// runTokenGenerate generates a new authentication token.
355	-	func runTokenGenerate(subject, scopesStr, expiryStr, configPath string) error {	355	+	// parseAndConvertScopes parses a comma-separated scope string and converts
356	-	cfg, err := loadAuthConfig(configPath)	356	+	// simple scopes (push, pull, ) to Docker v2 format (repository::action).
357	-	if err != nil {	357	+	func parseAndConvertScopes(scopesStr string) []string {
358	-	return err
359	-	}
360	-
361	-	// Parse expiry (supports human-friendly units: d, w, M, y)
362	-	var expiry time.Duration
363	-	if expiryStr != "0" {
364	-	expiry, err = duration.Parse(expiryStr)
365	-	if err != nil {
366	-	return fmt.Errorf("invalid expiry duration: %w", err)
367	-	}
368	-	}
369	-
370	-	// Parse scopes and convert simple scopes to Docker v2 format
371	-	// Simple scopes like "push,pull" become "repository:*:push,pull"
372		rawScopes := strings.Split(scopesStr, ",")	358		rawScopes := strings.Split(scopesStr, ",")
373		for i := range rawScopes {	359		for i := range rawScopes {
374		rawScopes[i] = strings.TrimSpace(rawScopes[i])	360		rawScopes[i] = strings.TrimSpace(rawScopes[i])
375		}	361		}
376			362
377		// Check if scopes are already in v2 format (contain colons)	363		// Check if scopes are already in v2 format (contain colons)
378	-	// or if they're simple scopes that need conversion
379	-	var scopes []string
380		hasSimpleScope := false	364		hasSimpleScope := false
381		for _, s := range rawScopes {	365		for _, s := range rawScopes {
382		if !strings.Contains(s, ":") && (s == "push" \|\| s == "pull" \|\| s == "*") {	366		if !strings.Contains(s, ":") && (s == "push" \|\| s == "pull" \|\| s == "*") {

@@ -385,24 +369,44 @@ func runTokenGenerate(subject, scopesStr, expiryStr, configPath string) error {
385		}	369		}
386		}	370		}
387			371
388	-	if hasSimpleScope {	372	+	if !hasSimpleScope {
389	-	// Convert simple scopes to v2 format: repository:*:push,pull	373	+	return rawScopes
390	-	var actions []string	374	+	}
391	-	for _, s := range rawScopes {	375	+
392	-	if s == "push" \|\| s == "pull" \|\| s == "*" {	376	+	// Convert simple scopes to v2 format: repository:*:push,pull
393	-	actions = append(actions, s)	377	+	var scopes []string
394	-	} else {	378	+	var actions []string
395	-	// Keep non-simple scopes as-is (e.g., admin scopes)	379	+	for _, s := range rawScopes {
396	-	scopes = append(scopes, s)	380	+	if s == "push" \|\| s == "pull" \|\| s == "*" {
397	-	}	381	+	actions = append(actions, s)
			382	+	} else {
			383	+	// Keep non-simple scopes as-is (e.g., admin scopes)
			384	+	scopes = append(scopes, s)
398		}	385		}
399	-	if len(actions) > 0 {	386	+	}
400	-	scopes = append(scopes, "repository:*:"+strings.Join(actions, ","))	387	+	if len(actions) > 0 {
			388	+	scopes = append(scopes, "repository:*:"+strings.Join(actions, ","))
			389	+	}
			390	+	return scopes
			391	+	}
			392	+
			393	+	func runTokenGenerate(subject, scopesStr, expiryStr, configPath string) error {
			394	+	cfg, err := loadAuthConfig(configPath)
			395	+	if err != nil {
			396	+	return err
			397	+	}
			398	+
			399	+	// Parse expiry (supports human-friendly units: d, w, M, y)
			400	+	var expiry time.Duration
			401	+	if expiryStr != "0" {
			402	+	expiry, err = duration.Parse(expiryStr)
			403	+	if err != nil {
			404	+	return fmt.Errorf("invalid expiry duration: %w", err)
401		}	405		}
402	-	} else {
403	-	scopes = rawScopes
404		}	406		}
405			407
			408	+	scopes := parseAndConvertScopes(scopesStr)
			409	+
406		// Create auth service	410		// Create auth service
407		log := zerowrap.New(zerowrap.Config{Level: "warn"})	411		log := zerowrap.New(zerowrap.Config{Level: "warn"})
408		authSvc, err := createAuthServiceForCLI(cfg, log)	412		authSvc, err := createAuthServiceForCLI(cfg, log)

M internal/adapters/in/http/middleware/auth.go +25 -22


@@ -312,33 +312,28 @@ func isInternalRegistryAuth(r *http.Request, internalAuth InternalRegistryAuth)
312	312		return usernameMatch && passwordMatch
313	313		}
314	314
315		-	// checkScopeAccess verifies the token has permission for the requested operation.
316		-	// Maps HTTP method to registry action and checks if any token scope grants access.
317		-	func checkScopeAccess(r http.Request, claims domain.TokenClaims, log zerowrap.Logger) bool {
318		-	// Determine required action from HTTP method
319		-	var action string
320		-	switch r.Method {
	315	+	// actionFromMethod returns the registry action for an HTTP method.
	316	+	func actionFromMethod(method string) string {
	317	+	switch method {
321	318		case http.MethodGet, http.MethodHead:
322		-	action = domain.ScopeActionPull
	319	+	return domain.ScopeActionPull
323	320		case http.MethodPut, http.MethodPost, http.MethodPatch, http.MethodDelete:
324		-	action = domain.ScopeActionPush
	321	+	return domain.ScopeActionPush
325	322		default:
326		-	action = domain.ScopeActionPull // Default to pull for unknown methods
	323	+	return domain.ScopeActionPull
327	324		}
	325	+	}
328	326
329		-	// Extract repository name from URL path
330		-	// Paths are like /v2/{name}/manifests/{reference} or /v2/{name}/blobs/{digest}
331		-	path := r.URL.Path
	327	+	// extractRepoName extracts the repository name from a registry path.
	328	+	// Returns empty string if the path is not a valid registry path or should be allowed.
	329	+	func extractRepoName(path string) (repoName string, shouldAllow bool) {
332	330		if !strings.HasPrefix(path, "/v2/") {
333		-	// Not a registry path, allow
334		-	return true
	331	+	return "", true // Not a registry path, allow
335	332		}
336	333
337		-	// Remove /v2/ prefix and find repository name
338	334		pathParts := strings.Split(strings.TrimPrefix(path, "/v2/"), "/")
339	335		if len(pathParts) < 2 {
340		-	// Malformed path or /v2/ root, allow
341		-	return true
	336	+	return "", true // Malformed path or /v2/ root, allow
342	337		}
343	338
344	339		// Find the boundary between repo name and route (manifests, blobs, tags)

@@ -350,16 +345,25 @@ func checkScopeAccess(r http.Request, claims domain.TokenClaims, log zerowrap.
350	345		}
351	346		}
352	347		if len(repoNameParts) == 0 {
353		-	// Could be a special route like /v2/token, allow
354		-	return true
	348	+	return "", true // Special route like /v2/token, allow
355	349		}
356	350
357		-	repoName := strings.Join(repoNameParts, "/")
	351	+	return strings.Join(repoNameParts, "/"), false
	352	+	}
	353	+
	354	+	// checkScopeAccess verifies the token has permission for the requested operation.
	355	+	// Maps HTTP method to registry action and checks if any token scope grants access.
	356	+	func checkScopeAccess(r http.Request, claims domain.TokenClaims, log zerowrap.Logger) bool {
	357	+	action := actionFromMethod(r.Method)
	358	+
	359	+	repoName, shouldAllow := extractRepoName(r.URL.Path)
	360	+	if shouldAllow {
	361	+	return true
	362	+	}
358	363
359	364		// Check if any token scope grants access
360	365		for _, scopeStr := range claims.Scopes {
361	366		// Handle simple scopes (e.g., "push", "pull") for backwards compatibility
362		-	// with tokens generated before v2 scope format was enforced
363	367		if scopeStr == action \|\| scopeStr == "*" {
364	368		log.Debug().
365	369		Str("repo", repoName).

@@ -372,7 +376,6 @@ func checkScopeAccess(r http.Request, claims domain.TokenClaims, log zerowrap.
372	376		// Handle Docker v2 format scopes (e.g., "repository:myrepo:push,pull")
373	377		scope, err := domain.ParseScope(scopeStr)
374	378		if err != nil {
375		-	log.Debug().Err(err).Str("scope", scopeStr).Msg("scope not in v2 format, skipping")
376	379		continue
377	380		}
378	381

 	return usernameMatch && passwordMatch
 }
-// checkScopeAccess verifies the token has permission for the requested operation.
+// actionFromMethod returns the registry action for an HTTP method.
-// Maps HTTP method to registry action and checks if any token scope grants access.
+func actionFromMethod(method string) string {
-func checkScopeAccess(r *http.Request, claims *domain.TokenClaims, log zerowrap.Logger) bool {
+	switch method {
-	// Determine required action from HTTP method
-	var action string
-	switch r.Method {
 	case http.MethodGet, http.MethodHead:
-		action = domain.ScopeActionPull
+		return domain.ScopeActionPull
 	case http.MethodPut, http.MethodPost, http.MethodPatch, http.MethodDelete:
-		action = domain.ScopeActionPush
+		return domain.ScopeActionPush
 	default:
-		action = domain.ScopeActionPull // Default to pull for unknown methods
+		return domain.ScopeActionPull
 	}
+}
-	// Extract repository name from URL path
+// extractRepoName extracts the repository name from a registry path.
-	// Paths are like /v2/{name}/manifests/{reference} or /v2/{name}/blobs/{digest}
+// Returns empty string if the path is not a valid registry path or should be allowed.
-	path := r.URL.Path
+func extractRepoName(path string) (repoName string, shouldAllow bool) {
 	if !strings.HasPrefix(path, "/v2/") {
-		// Not a registry path, allow
+		return "", true // Not a registry path, allow
-		return true
 	}
-	// Remove /v2/ prefix and find repository name
 	pathParts := strings.Split(strings.TrimPrefix(path, "/v2/"), "/")
 	if len(pathParts) < 2 {
-		// Malformed path or /v2/ root, allow
+		return "", true // Malformed path or /v2/ root, allow
-		return true
 	}
 	// Find the boundary between repo name and route (manifests, blobs, tags)
 		}
 	}
 	if len(repoNameParts) == 0 {
-		// Could be a special route like /v2/token, allow
+		return "", true // Special route like /v2/token, allow
-		return true
 	}
-	repoName := strings.Join(repoNameParts, "/")
+	return strings.Join(repoNameParts, "/"), false
+}
+// checkScopeAccess verifies the token has permission for the requested operation.
+// Maps HTTP method to registry action and checks if any token scope grants access.
+func checkScopeAccess(r *http.Request, claims *domain.TokenClaims, log zerowrap.Logger) bool {
+	action := actionFromMethod(r.Method)
+	repoName, shouldAllow := extractRepoName(r.URL.Path)
+	if shouldAllow {
+		return true
+	}
 	// Check if any token scope grants access
 	for _, scopeStr := range claims.Scopes {
 		// Handle simple scopes (e.g., "push", "pull") for backwards compatibility
-		// with tokens generated before v2 scope format was enforced
 		if scopeStr == action || scopeStr == "*" {
 			log.Debug().
 				Str("repo", repoName).
 		// Handle Docker v2 format scopes (e.g., "repository:myrepo:push,pull")
 		scope, err := domain.ParseScope(scopeStr)
 		if err != nil {
-			log.Debug().Err(err).Str("scope", scopeStr).Msg("scope not in v2 format, skipping")
 			continue
 		}