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 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
	// 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 NO tenant claims of
	// any kind: the VALIDATED Issuer is the tenant identity — receivers resolve
	// their internal tenant record (slug + uuid) from their issuer registry. It
	// never carries `sub` (UserID stays empty), so the local-user gate does not
	// apply.
	//
	// Tenant carries the `tenant` claim of tenant-scoped ACCESS tokens (and the
	// slug of opaque service tokens, resolved server-side); on delegated access
	// tokens the claim is forbidden and Tenant stays empty. TenantID is
	// populated ONLY for opaque service tokens via the receiver's own DB
	// resolution — never from a JWT claim.
	Tenant           string
	TenantID         string
	DelegatedSubject string

	// Attributes is the `attributes` claim of a delegated service 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 actor's role UUIDs carried by a delegated service
	// 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/TenantRoles claims,
	// which a delegated token never carries.
	DelegatedRoles []string

	// 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

	// RemoteApplicationID / RemoteApplicationSlug identify the JWKS PRINCIPAL a
	// self-token (#76) authenticated as: a remote_application acting AS ITSELF.
	// Populated ONLY for RemoteApplicationTokenType claims, resolved server-side
	// from the validated `iss` (never from a self-asserted token claim). The
	// principal's Permissions/TenantRoles carry its STORED, assigned authority.
	RemoteApplicationID   string
	RemoteApplicationSlug string
}

type ClientIPFunc func(r *http.Request) string

type DelegatedAccessParams = core.DelegatedAccessParams

type DelegatedPrincipal struct {
	// Issuer is the tenant identity: the receiving service resolves its
	// internal tenant record (slug + uuid) from the VALIDATED Issuer via its
	// issuer registry. The token carries no tenant claims.
	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 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

	// TenantSlug is the receiver-internal tenant slug this issuer is registered
	// to — issuer-registry data, the single source of tenant identity for
	// tokens signed by this issuer (tokens carry no tenant claims). It resolves
	// the principal's tenant; it is never compared against token claims.
	TenantSlug 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 RemoteApplicationAuthoritySource interface {
	ResolveRemoteApplicationAuthority(ctx context.Context, appID string) (memberships []core.TenantMembership, permissions []string, err error)
}

type RemoteApplicationSource interface {
	ListRemoteApplications(ctx context.Context, enabledOnly bool) ([]core.RemoteApplication, error)
	// GetRemoteApplication fetches a SINGLE remote_application by its issuer,
	// used by the lazy-load-on-miss path in keyForToken. *core.Service already
	// implements this.
	GetRemoteApplication(ctx context.Context, issuer string) (*core.RemoteApplication, 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 TenantIssuersClient struct {
	// contains filtered or unexported fields
}

type TenantIssuersClientOption func(*TenantIssuersClient)

type TenantIssuersRegistration struct {
	// Slug is this remote_application's slug on the receiving service.
	Slug 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 (#74). Mutually exclusive with JWKSURI.
	PublicKeys []core.RemoteAppKey
}

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

type VerifierOption func(*Verifier)