auth

type AssemblyRef ¶

type AssemblyRef interface {
	// ID returns the assembly's unique identifier.
	ID() string
	// CellIDs returns the ordered list of registered cell identifiers.
	CellIDs() []string
	// Cell returns the registered Cell with the given ID, or nil if no
	// cell with that ID is registered. Callers are responsible for type-
	// asserting the returned Cell to the role-specific interface they
	// require (e.g. AuthProvider).
	Cell(id string) cell.Cell
}

AssemblyRef is the contract kernel needs from an assembly: identity (ID), the registered cell list (CellIDs), and by-ID cell lookup (Cell). Using a named interface preserves type safety at composition boundaries and lets callers in runtime/bootstrap iterate authProvider discovery without an implicit type assertion to a private sub-interface.

Bootstrap passes the concrete *assembly.CoreAssembly which satisfies this interface structurally; identity checks (same pointer) are done in runtime/bootstrap, not in kernel.

ASSEMBLYREF-METHOD-SET-01 (tools/archtest/assemblyref_method_set_test.go) locks this method set against accidental drift.

type AuthJWT ¶

type AuthJWT struct {
	// Verifier is the IntentTokenVerifier used to validate JWTs. Required; nil
	// (bare or typed) is rejected by NewAuthJWT with an error (B2-K-02 dropped
	// the MustNewAuthJWT panic variant in PR #553 — composition roots
	// propagate the error to bootstrap). Do not set this field directly after
	// construction; use NewAuthJWT(v) which enforces the non-nil invariant.
	Verifier IntentTokenVerifier
}

AuthJWT is the JWT-authenticated listener plan. The verifier is supplied at construction time via NewAuthJWT. Bootstrap extracts it during phase5 and installs the router-aware AuthMiddleware so that Public/PasswordResetExempt routes declared via auth.Mount are honored.

func NewAuthJWT(v IntentTokenVerifier) (AuthJWT, error)

func (AuthJWT) Describe() string

type AuthJWTFromAssembly ¶

type AuthJWTFromAssembly struct {
	// Assembly must be the same *assembly.CoreAssembly instance later
	// supplied to bootstrap.WithAssembly. Constructors only reject
	// nil/typed-nil; wrong-instance values pass construction and are
	// caught at bootstrap phase0.
	Assembly AssemblyRef
	// contains filtered or unexported fields
}

AuthJWTFromAssembly is a lazy JWT plan that resolves its verifier from an AuthProvider cell in the assembly during bootstrap phase4. Use it when the verifier is owned by a cell (typical for accesscore-style designs).

The resolved verifier is stored in an atomic.Pointer so that concurrent reads from the router are safe without locking.

AuthJWTFromAssembly implements only ListenerAuth (same rationale as AuthJWT).

Lifecycle constraint: the Assembly value must be the same instance later passed to bootstrap.WithAssembly. Bootstrap phase0 (validateAuthJWTFromAssemblyPlans in runtime/bootstrap/auth_plan_validate.go) rejects direct struct literals, nil assemblies, wrappers, copies, or fakes even when they share the same ID. Construct AuthJWTFromAssembly from the canonical *assembly.CoreAssembly.

func NewAuthJWTFromAssembly(asm AssemblyRef) (AuthJWTFromAssembly, error)

func (AuthJWTFromAssembly) Describe() string

func (p AuthJWTFromAssembly) IsConstructed() bool

func (p AuthJWTFromAssembly) ResolvedVerifier() IntentTokenVerifier

func (p AuthJWTFromAssembly) SetResolved(v IntentTokenVerifier)

type AuthKind ¶

type AuthKind uint8

AuthKind is the discriminant for an AuthPlan variant. Declared as uint8 to keep the type small; the iota values are stable.

const (
	AuthKindNone            AuthKind = iota // AuthNone
	AuthKindJWT                             // AuthJWT
	AuthKindJWTFromAssembly                 // AuthJWTFromAssembly
	AuthKindMTLS                            // AuthMTLS
	AuthKindServiceToken                    // AuthServiceToken
	AuthKindOperator                        // AuthOperator (see operator.go)
)

type AuthMTLS ¶

type AuthMTLS struct{}

AuthMTLS is the mutual-TLS listener plan. The middleware asserts that the request arrived over a TLS connection with at least one peer certificate. Chain verification MUST be delegated to tls.Config.ClientAuth; see the runtime/bootstrap phase0 validation (validateAuthPlanMTLSBindings).

func (AuthMTLS) Describe() string

type AuthNone ¶

type AuthNone struct{}

AuthNone is the no-op auth plan. Use it for listeners that are network-isolated and require no authentication gate (e.g. the HealthListener behind a Kubernetes probe path).

func (AuthNone) Describe() string

type AuthOperator ¶

type AuthOperator struct {
	// Username and Password are the env operator credentials, compared in
	// constant time against the HTTP Basic Auth header. Required; empty values
	// are rejected by NewAuthOperator. Held as raw bytes (not a struct mirroring
	// runtime/auth.BootstrapCredentials) so the apply-switch maps them into the
	// runtime type at construction with no parallel struct.
	Username []byte
	Password []byte
	// Limiter is the per-IP rate limiter applied before credential parsing.
	// Required; nil (bare or typed) is rejected by NewAuthOperator.
	Limiter OperatorRateLimiter
	// OnAuthFail is an optional observer invoked after a 401/429 is written
	// (reason ∈ {"missing_header","wrong_credentials","rate_limited"}); nil
	// disables it. Routes operator auth failures to an audit log without
	// kernel/auth importing cells/.
	OnAuthFail func(ctx context.Context, reason string)
}

AuthOperator is the operator-credential listener plan for the admin control-plane (cell.AdminListener). Bootstrap installs runtime/auth.NewBootstrapMiddleware with these credentials, rate limiter, and optional auth-fail observer: per-IP rate limit → HTTP Basic Auth → constant-time credential comparison → uniform 401. operator→system actions (e.g. projection rebuild) are authenticated by the env operator credentials, NOT by a caller-cell allowlist.

func NewAuthOperator(
	username, password []byte,
	limiter OperatorRateLimiter,
	onAuthFail func(ctx context.Context, reason string),
) (AuthOperator, error)

func (AuthOperator) Describe() string

type AuthPlan ¶

type AuthPlan interface {

	// Describe returns a human-readable fingerprint for startup logging.
	// Used by runtime/bootstrap/auth_plan_describe.go (the only allowed location
	// for the "jwt"/"mtls"/"service-token" string literals).
	Describe() string
	// contains filtered or unexported methods
}

AuthPlan is the sealed base interface for all authentication plans. The unexported marker method authPlanKind prevents implementations outside this package, giving us a closed enumeration without code generation.

type AuthProvider ¶

type AuthProvider interface {
	TokenVerifier() IntentTokenVerifier
}

AuthProvider is an optional cell-level interface that exposes an IntentTokenVerifier for runtime authentication. AuthJWTFromAssembly walks the assembly's CellIDs in deterministic order during bootstrap phase4 and promotes the unique implementer's verifier; zero, multiple, or nil verifiers are rejected with a startup error.

type AuthServiceToken ¶

type AuthServiceToken struct {
	// Store is the NonceStore for replay prevention. Required.
	Store NonceStore
	// Ring is the HMACKeyring supplying signing secrets. Required.
	Ring HMACKeyring
}

AuthServiceToken is the HMAC-SHA256 service token plan. Bootstrap installs auth.ServiceTokenMiddleware with the provided ring and nonce store.

func NewAuthServiceToken(store NonceStore, ring HMACKeyring) (AuthServiceToken, error)

func (AuthServiceToken) Describe() string

type Claims ¶

type Claims struct {
	// Subject is the principal identifier (user ID, service name, etc.).
	Subject string
	// Issuer identifies the token issuer.
	Issuer string
	// Audience is the intended recipient(s).
	Audience []string
	// ExpiresAt is the expiration time.
	ExpiresAt time.Time
	// IssuedAt is the token issue time.
	IssuedAt time.Time
	// Roles is the set of roles associated with the subject.
	Roles []string
	// TokenUse records the intent declared by the JWT's token_use claim.
	TokenUse TokenIntent
	// SessionID is the "sid" claim binding the token to a specific session.
	SessionID string
	// TenantID is the "tenant_id" claim identifying the tenant isolation
	// boundary the subject belongs to. Empty in single-tenant deployments (no
	// tenant claim issued). When non-empty it MUST be a valid UUID; the
	// runtime/auth JWTVerifier.VerifyIntent validates and canonicalizes it via
	// pkg/tenant.ParseTenantID before returning Claims (a malformed tenant claim
	// fails closed), so consumers may treat a non-empty value as a canonical
	// lowercase UUID. Typed string (not pkg/tenant.TenantID) to keep this kernel
	// wire type free of the tenant package's UUID dependency; the runtime
	// boundary owns validation.
	TenantID string
	// PasswordResetRequired indicates that the subject must change their password.
	PasswordResetRequired bool
	// JTI is the JWT ID claim ("jti"), a unique identifier for the token.
	// Empty string when the claim is absent.
	JTI string
	// Extra holds additional claims not covered by the standard fields.
	Extra map[string]any
}

Claims represents the decoded token claims. This is the canonical definition; runtime/auth.Claims is a type alias of this type so callers share the same struct without conversion at package boundaries.

type HMACKeyring ¶

type HMACKeyring interface {
	// Current returns a copy of the active signing secret.
	Current() []byte
	// Secrets returns all secrets in try-order: current first, then previous.
	Secrets() [][]byte
}

HMACKeyring supplies HMAC secrets for service token operations. This is the kernel projection of runtime/auth.HMACKeyRing; *HMACKeyRing satisfies it structurally (Current/Secrets methods already exist).

type IntentTokenVerifier ¶

type IntentTokenVerifier interface {
	VerifyIntent(ctx context.Context, token string, expected TokenIntent) (Claims, error)
}

IntentTokenVerifier verifies a JWT token and requires its declared intent to match the expected value. This is the kernel projection of the same interface in runtime/auth; runtime/auth.JWTVerifier satisfies it structurally.

type ListenerAuth ¶

type ListenerAuth interface {
	AuthPlan
	// contains filtered or unexported methods
}

ListenerAuth is the (only) typed authentication scheme accepted by bootstrap.WithListener. RouteGroups inherit their listener's auth chain uniformly — there is no group-level override (PR269 round-3: cells that need a different scheme should declare their routes on a different listener).

type NonceStore ¶

type NonceStore interface {
	// CheckAndMark checks whether nonce has been seen within its TTL window.
	// If not, it marks the nonce and returns nil. Returns ErrNonceReused on replay.
	CheckAndMark(ctx context.Context, nonce string) error
	// Kind reports the implementation classification.
	Kind() NonceStoreKind
}

NonceStore tracks nonces for replay prevention. This is the kernel projection of runtime/auth.NonceStore; runtime/auth.InMemoryNonceStore and runtime/auth.NoopNonceStore satisfy it structurally. Note: the kernel interface uses (ctx, key, ttl) to accommodate future distributed implementations; runtime/auth.NonceStore uses (ctx, nonce) without ttl. We match the existing runtime/auth.NonceStore signature so no adapter is needed.

type NonceStoreKind ¶

type NonceStoreKind string

NonceStoreKind classifies a NonceStore implementation for startup validation. Mirrors runtime/auth.NonceStoreKind; kept as a string for extensibility.

const (
	// NonceStoreKindNoop is the explicit disable-replay-check sentinel.
	// Production deployments must reject this kind for service-token guards.
	NonceStoreKindNoop NonceStoreKind = "noop"
	// NonceStoreKindInMemory is the single-process map-backed implementation.
	NonceStoreKindInMemory NonceStoreKind = "in_memory"
	// NonceStoreKindDistributed is reserved for shared backends (Redis, etc.).
	NonceStoreKindDistributed NonceStoreKind = "distributed"
)

func (k NonceStoreKind) ReplaySafe(requireDistributed bool) bool

type OperatorRateLimiter ¶

type OperatorRateLimiter interface {
	Allow(key string) bool
}

OperatorRateLimiter decides whether a request identified by key (typically the client IP) should be allowed. It is the kernel projection of runtime/auth.BootstrapRateLimiter so that the AuthOperator plan can hold its limiter as a kernel-level interface, keeping kernel/ free of runtime/ imports (same idiom as NonceStore / HMACKeyring in auth_types.go). The composition root injects a concrete per-IP limiter (e.g. adapters/ratelimit.TokenBucket); there is deliberately no built-in allow-all implementation — operator credentials must always be rate-limited to defeat brute-force enumeration.

type TokenIntent ¶

type TokenIntent string

TokenIntent distinguishes how a JWT is meant to be used. The values here are the canonical definition; runtime/auth.TokenIntent is a type alias of this type.

const (
	// TokenIntentAccess marks a short-lived credential for calling business
	// endpoints. Verifier rejects any access token replayed at /auth/refresh.
	TokenIntentAccess TokenIntent = "access"
)

func (t TokenIntent) IsValid() bool