at-container-registry/pkg/auth/token/claims.go

// Package token provides JWT claims and token handling for registry authentication.
package token

import (
	"slices"
	"time"

	"atcr.io/pkg/auth"
	"github.com/golang-jwt/jwt/v5"
)

// Auth method constants
const (
	AuthMethodOAuth       = "oauth"
	AuthMethodAppPassword = "app_password"
	// AuthMethodAnonymous marks a token issued without credentials for a
	// pull-only scope. Such tokens carry an empty Subject (no puller DID); the
	// destination hold decides whether anonymous reads are allowed (captain.Public).
	AuthMethodAnonymous = "anonymous"
)

// Claims represents the JWT claims for registry authentication
// This follows the Docker Registry token specification
type Claims struct {
	jwt.RegisteredClaims
	Access     []auth.AccessEntry `json:"access,omitempty"`
	AuthMethod string             `json:"auth_method,omitempty"` // "oauth" or "app_password"
}

// NewClaims creates a new Claims structure with standard fields
func NewClaims(subject, issuer, audience string, expiration time.Duration, access []auth.AccessEntry, authMethod string) *Claims {
	now := time.Now()
	return &Claims{
		RegisteredClaims: jwt.RegisteredClaims{
			Subject:   subject,                    // User's DID
			Issuer:    issuer,                     // "atcr.io"
			Audience:  jwt.ClaimStrings{audience}, // Service name
			IssuedAt:  jwt.NewNumericDate(now),
			NotBefore: jwt.NewNumericDate(now),
			ExpiresAt: jwt.NewNumericDate(now.Add(expiration)),
		},
		Access:     access,
		AuthMethod: authMethod, // "oauth" or "app_password"
	}
}

// ExtractAuthMethod parses a JWT token string and extracts the auth_method claim
// Returns the auth method or empty string if not found or token is invalid
// This does NOT validate the token - it only parses it to extract the claim
func ExtractAuthMethod(tokenString string) string {
	// Parse token without validation (we only need the claims, validation is done by distribution library)
	parser := jwt.NewParser(jwt.WithoutClaimsValidation())
	token, _, err := parser.ParseUnverified(tokenString, &Claims{})
	if err != nil {
		return "" // Invalid token format
	}

	claims, ok := token.Claims.(*Claims)
	if !ok {
		return "" // Wrong claims type
	}

	return claims.AuthMethod
}

// ExtractAccess parses a JWT token string and extracts the access entries (scopes)
// Returns nil if not found or token is invalid
// This does NOT validate the token - it only parses it to extract the claim
func ExtractAccess(tokenString string) []auth.AccessEntry {
	parser := jwt.NewParser(jwt.WithoutClaimsValidation())
	token, _, err := parser.ParseUnverified(tokenString, &Claims{})
	if err != nil {
		return nil
	}

	claims, ok := token.Claims.(*Claims)
	if !ok {
		return nil
	}

	return claims.Access
}

// HasPushScope checks if any access entry contains a "push" action
func HasPushScope(access []auth.AccessEntry) bool {
	for _, entry := range access {
		if slices.Contains(entry.Actions, "push") {
			return true
		}
	}
	return false
}

// IsPullOnlyScope reports whether the requested access is safe to grant without
// credentials. This is the gate for anonymous token issuance, so it allowlists:
// every requested action must be exactly "pull". Empty access (the /v2/ ping)
// and an entry with no actions are both fine.
//
// It must not be written as a denylist of "push"/"delete". Distribution's
// actionSet.contains returns true for ANY action when the set holds "*"
// (registry/auth/token/util.go), so a scope of `repository:victim/img:*` names
// neither string yet authorizes push and delete. Denylisting would hand an
// unauthenticated caller a token that clears the whole appview authorization
// layer — the authgate is deliberately skipped for anonymous tokens.
func IsPullOnlyScope(access []auth.AccessEntry) bool {
	for _, entry := range access {
		for _, action := range entry.Actions {
			if action != "pull" {
				return false
			}
		}
	}
	return true
}

// NarrowToPullOnly returns a copy of access holding only the "pull" action, and
// reports whether the result is worth issuing a token for.
//
// Clients routinely request more than they need for the operation in hand —
// `repository:x:pull,push` for a plain pull is common, and some request
// pull,push,delete up front — so an all-or-nothing IsPullOnlyScope test rejects
// the request, challenges, and leaves a credential-less client with no way
// forward even for a public image. Granting a subset is the behavior the
// distribution token spec expects: the server issues what it is willing to
// authorize and the client proceeds with that.
//
// The allowlist property from IsPullOnlyScope is preserved exactly: "pull" is
// the only action that survives, so nothing here can emit a token carrying
// push, delete, or "*". An entry left with no actions is dropped rather than
// emitted empty, since distribution treats an empty action set as granting
// nothing and it only adds noise to the token.
//
// "*" is deliberately NOT expanded into "pull". Rewriting it would be safe in
// the narrow sense (the issued token would name only "pull"), but a wildcard
// request is not evidence the caller wants a read, and refusing it keeps the
// anonymous path free of any case where a wildcard turns into a grant.
func NarrowToPullOnly(access []auth.AccessEntry) ([]auth.AccessEntry, bool) {
	narrowed := make([]auth.AccessEntry, 0, len(access))
	grantable := false

	for _, entry := range access {
		if len(entry.Actions) == 0 {
			// No actions requested (the /v2/ ping shape). Preserve it as-is:
			// it grants nothing and callers rely on the entry surviving.
			narrowed = append(narrowed, entry)
			continue
		}
		if !slices.Contains(entry.Actions, "pull") {
			continue
		}
		pullOnly := entry
		pullOnly.Actions = []string{"pull"}
		narrowed = append(narrowed, pullOnly)
		grantable = true
	}

	return narrowed, grantable || len(access) == 0
}

// ExtractSubject parses a JWT token string and extracts the Subject claim (the user's DID)
// Returns the subject or empty string if not found or token is invalid
// This does NOT validate the token - it only parses it to extract the claim
func ExtractSubject(tokenString string) string {
	// Parse token without validation (we only need the claims, validation is done by distribution library)
	parser := jwt.NewParser(jwt.WithoutClaimsValidation())
	token, _, err := parser.ParseUnverified(tokenString, &Claims{})
	if err != nil {
		return "" // Invalid token format
	}

	claims, ok := token.Claims.(*Claims)
	if !ok {
		return "" // Wrong claims type
	}

	return claims.Subject
}