authhttp

type ActionAvailability struct {
	Action            string     `json:"action"`
	Allowed           bool       `json:"allowed"`
	Reason            string     `json:"reason,omitempty"`
	RetryAfterSeconds int64      `json:"retry_after_seconds,omitempty"`
	NextAllowedAt     *time.Time `json:"next_allowed_at,omitempty"`
	Limit             *int       `json:"limit,omitempty"`
	Remaining         *int       `json:"remaining,omitempty"`
	WindowSeconds     *int64     `json:"window_seconds,omitempty"`
	CooldownSeconds   *int64     `json:"cooldown_seconds,omitempty"`
}

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
	// GlobalRoles are the user's GLOBAL (platform-wide) roles, carried in the
	// `global_roles` claim in both single and multi-tenant mode. Use these for
	// global-admin authorization decisions.
	GlobalRoles []string
	// TenantRoles are the roles scoped to the tenant named in Tenant, carried in the
	// `tenant_roles` claim on tenant-scoped tokens. Use these for tenant-scoped authz.
	TenantRoles  []string
	Entitlements []string
	Issuer       string
	UserTier     string
	JTI          string

	// Delegated/tenant fields. A delegated service token carries the external
	// actor in DelegatedSubject (claim `delegated_sub`) and the target resource
	// account in TenantID (claim `tenant_id`, immutable uuid — the canonical
	// key) and Tenant (claim `tenant`, mutable slug — presentation/logging
	// only). It never carries `sub` (UserID stays empty), so the local-user
	// gate does not apply. TenantID is empty on tokens minted before the
	// tenant_id claim existed; fall back to resolving Tenant.
	Tenant           string
	TenantID         string
	DelegatedSubject string

	// Attributes is the `attributes` claim of a delegated service token: an
	// object of issuer-provided policy metadata (e.g. {"tier":"cozy_free"}).
	// Values are kept as raw JSON so the receiving service can decode each into
	// its own typed schema. Nil when the claim is absent.
	Attributes map[string]json.RawMessage

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

	// TokenType marks the credential class. Empty for ordinary user JWTs;
	// "service" for an Service Token (service token) acting AS THE TENANT. A
	// service principal carries Tenant + 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
	// (service token) carries directly — the PBAC grant. Empty for user principals, whose
	// authority is expressed as TenantRoles that the resource server expands to
	// permissions at request time. authkit treats permission strings as opaque.
	Permissions []string

	// Resources are opaque host-defined resource scopes carried by an
	// Service Token. Empty means the service token has no AuthKit-stored
	// resource constraints; resource-aware hosts decide whether to require them.
	Resources []core.ServiceTokenResource
}

type ClientIPFunc func(r *http.Request) string

type DelegatedAccessParams struct {
	// Issuer becomes the `iss` claim: the AuthKit issuer that signed the token.
	// signs the token. Must match a tenant issuer registered with the
	// validating resource server. Required.
	Issuer string
	// Audiences becomes the `aud` claim: the target resource API(s), e.g.
	// "openrails", "tensorhub", or "gen-orchestrator".
	Audiences []string
	// Tenant becomes the `tenant` claim: the target resource-service account's
	// mutable slug, e.g. "doujins" for OpenRails. Presentation/logging only —
	// receiving services must key on TenantID.
	Tenant string
	// TenantID becomes the `tenant_id` claim: the immutable uuid of the target
	// resource-service account. This is the canonical identifier receiving
	// services persist and authorize against. Required.
	TenantID string
	// DelegatedSubject becomes `delegated_sub`: the issuer-side user/actor id.
	// Required. No local account is implied in the receiving service.
	DelegatedSubject string
	// Permissions becomes the `permissions` claim: an array of resource-defined
	// permission strings (NOT OAuth's space-delimited `scope`). Receiving
	// services validate these against their own permission catalog.
	Permissions []string
	// Attributes becomes the `attributes` claim: an object of issuer-provided
	// policy metadata such as {"tier":"cozy_free"}, plan labels, budget classes,
	// or risk buckets. Values are arbitrary JSON.
	Attributes map[string]any
	// TTL is the token lifetime. Defaults to 15m when zero.
	TTL time.Duration
	// JTI, when set, becomes the `jti` claim (token identifier). Optional.
	JTI string
	// NotBefore, when set, becomes the `nbf` claim. Optional.
	NotBefore time.Time
}

type DelegatedPrincipal struct {
	Issuer string
	// Tenant is the mutable resource-account slug (claim `tenant`);
	// TenantID is the immutable uuid (claim `tenant_id`) and is the
	// identifier to persist. TenantID is empty on legacy tokens.
	Tenant           string
	TenantID         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 issuer-provided policy metadata (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
}

type InternalErrorEvent struct {
	Route  string
	Stage  string
	Code   string
	Method string
	Path   string
	Err    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 core.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

	// TrustedResourceAccount optionally binds delegated service tokens from this
	// issuer to one resource-service account slug. Tenant issuers loaded from
	// the tenant_issuers store set this to that row's tenant slug, so a
	// trusted issuer cannot mint a delegated token for another resource account.
	TrustedResourceAccount string
}

type LanguageConfig struct {
	Supported  []string
	Default    string
	QueryParam string
	CookieName string
}

type Limit struct {
	Limit    int
	Window   time.Duration
	Cooldown time.Duration
}

type PermissionValidator func(permissions []string) error

type RateLimitResult struct {
	Allowed      bool
	RetryAfter   time.Duration
	Availability *ActionAvailability
}

type RateLimiter interface {
	AllowNamed(bucket string, key string) (bool, error)
}

type RateLimiterWithResult interface {
	AllowNamedResult(bucket string, key string) (ratelimit.Result, error)
}

type RateLimiterWithRetryAfter interface {
	AllowNamedWithRetryAfter(bucket string, key string) (bool, time.Duration, error)
}

type RouteGroup string

type RouteSpec struct {
	Method  string
	Path    string
	Group   RouteGroup
	Handler http.Handler
}

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

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

type ServiceJWTPrincipal struct {
	Issuer      string
	Subject     string
	Tenant      string
	Audiences   []string
	Permissions []string
	Resources   []core.ServiceTokenResource
	JTI         string
	ExpiresAt   time.Time
}

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

type ServiceJWTVerifyOption func(*serviceJWTVerifyConfig)

type TenantIssuerSource interface {
	ListTenantIssuers(ctx context.Context, enabledOnly bool) ([]core.TenantIssuer, error)
	// GetTenantIssuer fetches a SINGLE tenant-tenant issuer by its
	// issuer, used by the lazy-load-on-miss path in keyForToken. *core.Service
	// already implements this.
	GetTenantIssuer(ctx context.Context, issuerID string) (*core.TenantIssuer, error)
}

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

type TenantIssuersClientOption func(*TenantIssuersClient)

type TenantIssuersRegistration struct {
	// Tenant is this issuer's resource account slug on the receiving service.
	Tenant string
	// Issuer is THIS platform's issuer URL (the `iss` of delegated tokens).
	Issuer string
	// JWKSURI is where the resource server fetches THIS platform's public keys
	// (jwks mode — preferred). Mutually exclusive with PublicKeys.
	JWKSURI string
	// PublicKeys is the static-mode key list for platforms without a JWKS
	// endpoint (#465). Mutually exclusive with JWKSURI.
	PublicKeys []core.TenantIssuerKey
}

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

type VerifierOption func(*Verifier)