verify

type AttributeDefResolver func(ctx context.Context, issuer, key, ref string) (json.RawMessage, error)

type AttributesValidator func(attributes map[string]json.RawMessage) error

type Claims struct {
	UserID          string
	Email           string
	EmailVerified   bool
	Username        string
	DiscordUsername string
	SessionID       string
	Roles           []string
	Entitlements    []string
	AMR             []string
	ACR             string
	AuthTime        time.Time
	TwoFAEnrollment bool
	Issuer          string
	UserTier        string
	JTI             string

	// A delegated access token carries the external delegated subject in
	// DelegatedSubject (claim `delegated_sub`). It never carries `sub` (UserID
	// stays empty), so the local-user gate does not apply.
	DelegatedSubject string

	// Attributes is the `attributes` claim of a delegated access token: the
	// canonical app-specific ESCAPE HATCH (#75). It is an object of issuer-
	// asserted, NAMESPACED, OPAQUE key/values that AuthKit transports and
	// optionally shape-validates (WithAttributesPolicy) but NEVER interprets —
	// the semantics belong to the consuming app. Each value is in one of two
	// modes (see Attribute / AttributeIsReference):
	//   INLINE    — the value carries the full definition, e.g.
	//               {"tier":{"endpoints":[...],"caps":[...]}}.
	//   REFERENCE — the value is a short JSON string key, e.g. {"tier":"tier-1"},
	//               resolved against a definition the remote_application
	//               registered ahead of time (resolve via the attribute-def
	//               registry, or opt-in verify-time hydration).
	// Reserved well-known keys: `tier` (opaque entitlement-tier string, surfaced
	// as UserTier) and `roles` (uuid array, surfaced as DelegatedRoles).
	// Everything else is free-form per consuming app. Values are kept as raw
	// JSON so the receiver decodes each into its own typed schema; nil when the
	// claim is absent.
	Attributes map[string]json.RawMessage

	// DelegatedRoles are the delegated subject's role UUIDs carried by a
	// delegated access token under `attributes.roles` (a JSON array of UUID strings). They are
	// extracted and validated at verify (malformed entries dropped, count
	// capped) and surfaced on DelegatedPrincipal.Roles. Downstream services use
	// them as e.g. budget-scope keys; authkit treats them as opaque strings.
	// Nil when absent. Distinct from the native-user Roles claim, which a
	// delegated token never carries.
	DelegatedRoles []string

	// TokenTyp is the JOSE `typ` header value. "access+jwt" identifies an
	// AuthKit user access token; "delegated-access+jwt" identifies a delegated
	// access token; "remote-application-access+jwt" identifies a remote
	// application access token.
	TokenTyp string

	// TokenType marks the credential class. Empty for ordinary user JWTs;
	// "service" for an API-key service principal. A service principal carries
	// Permissions but no UserID, so the live-user ban/enrichment gate is skipped
	// (there is no user to look up).
	TokenType string

	// Permissions are the app-defined permission strings a service principal
	// carries directly — the PBAC grant. Empty for user principals. authkit
	// treats permission strings as opaque.
	Permissions []string

	// Resources are opaque host-defined resource scopes carried by an
	// API key. Empty means the service principal has no AuthKit-stored
	// resource constraints; resource-aware hosts decide whether to require them.
	Resources []authbase.APIKeyResource

	// RemoteApplicationID / RemoteApplicationSlug identify the remote_application
	// authenticated by a remote application access token. Populated ONLY for
	// RemoteApplicationTokenType claims, resolved server-side from the validated
	// `iss` (never from a self-asserted token claim). The principal's Permissions
	// carry its STORED, assigned authority.
	RemoteApplicationID   string
	RemoteApplicationSlug string
}

type DelegatedPrincipal struct {
	// Issuer is the validated token issuer the receiving service trusts.
	Issuer           string
	DelegatedSubject string
	// Permissions are the resource-defined permission strings the receiving
	// service authorizes against its own catalog. This is the authority source.
	Permissions []string
	// Attributes is the issuer-asserted escape-hatch bag (#75): namespaced,
	// OPAQUE, consumer-interpreted key/values, each INLINE or REFERENCE (see
	// Claims.Attributes / Claims.AttributeReference). Reserved keys: `tier`
	// (-> UserTier) and `roles` (-> Roles). Raw JSON values.
	Attributes map[string]json.RawMessage
	// JTI is the token identifier (`jti` claim), when present.
	JTI string
	// UserTier is the resolved tier, sourced from `attributes.tier`.
	UserTier string
	// Roles are the actor's role UUID strings, sourced from `attributes.roles`
	// (each validated as a well-formed UUID at verify; malformed entries are
	// dropped, count is capped). Kept as strings so consumers parse to uuid
	// without forcing a uuid dependency on the principal. Nil when absent.
	Roles []string
}

type Enricher interface {
	ResolveAPIKeyWithResources(ctx context.Context, keyID, secret string) (authbase.ResolvedAPIKey, error)
	GetRemoteApplication(ctx context.Context, issuer string) (*authbase.RemoteApplication, error)
	ListRemoteApplications(ctx context.Context, activeOnly bool) ([]authbase.RemoteApplication, error)
	ResolveRemoteApplicationAuthority(ctx context.Context, appID string) ([]string, error)
	ResolveRemoteAppAttributeDef(ctx context.Context, appID, key string, version int32) (*authbase.RemoteAppAttributeDef, error)
	GetProviderUsername(ctx context.Context, userID, provider string) (string, error)
	ListRoleSlugsByUser(ctx context.Context, userID string) []string
	GetEmailByUserID(ctx context.Context, id string) (string, error)
	IsUserAllowed(ctx context.Context, userID string) (bool, error)
}

type IssuerKey struct {
	KID          string
	PublicKeyPEM string
}

type IssuerOptions struct {
	// JWKSURI is the URL to fetch JWKS from. If set, keys are fetched
	// automatically and refreshed when they expire or an unknown kid appears.
	JWKSURI string

	// Keys are pre-provided public keys as PEM. The caller is responsible for
	// refreshing by calling AddIssuer again with updated keys.
	Keys []IssuerKey

	// RawKeys are pre-provided public keys (e.g., from a co-located authbase.Service).
	RawKeys map[string]crypto.PublicKey

	// CacheTTL controls how long fetched JWKS keys are considered fresh.
	// Default: 10 minutes.
	CacheTTL time.Duration

	// MaxStale controls how long stale keys may be used as fallback after
	// a failed JWKS refresh. Default: 1 hour.
	MaxStale time.Duration

	// RemoteApplicationSlug is the receiver-internal remote-application slug
	// registered for this issuer. Tokens do not self-assert this value; it comes
	// only from the trusted issuer registry.
	RemoteApplicationSlug string

	// IsLocal marks this issuer as the host application's own (first-party) token
	// signer, as opposed to a remote_application/federated issuer. It guards the
	// signing-key registry against a non-local registration overwriting the local
	// issuer entry (AK-AUTH-01); it does not change how claims are parsed.
	IsLocal bool
}

type PermissionValidator func(permissions []string) error

type RemoteApplicationSource interface {
	ListRemoteApplications(ctx context.Context, enabledOnly bool) ([]authbase.RemoteApplication, error)
	// GetRemoteApplication fetches a SINGLE remote_application by its issuer,
	// used by the lazy-load-on-miss path in keyForToken. *authbase.Service already
	// implements this.
	GetRemoteApplication(ctx context.Context, issuer string) (*authbase.RemoteApplication, error)
}

type SensitiveOptions struct {
	MaxAge        time.Duration
	RequireMFA    bool
	AMR           []string
	ACR           string
	ReauthMethods []string
}

type ServiceJWTPrincipal struct {
	Issuer                string
	Subject               string
	RemoteApplicationSlug string
	Audiences             []string
	Permissions           []string
	Resources             []authbase.APIKeyResource
	JTI                   string
	ExpiresAt             time.Time
}

type ServiceJWTReplayChecker func(ctx context.Context, claims authbase.ServiceJWTClaims) error

type ServiceJWTVerifyOption func(*serviceJWTVerifyConfig)

type Verifier struct {
	// contains filtered or unexported fields
}

type VerifierOption func(*Verifier)