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-org mode. Use these for
	// global-admin authorization decisions.
	GlobalRoles []string
	Org         string
	// OrgRoles are the roles scoped to the org named in Org, carried in the
	// `org_roles` claim on org-scoped tokens. Use these for org-scoped authz.
	OrgRoles     []string
	Entitlements []string
	Issuer       string
	UserTier     string
	JTI          string

	// Delegated/federated fields. A delegated access token carries the external
	// actor in DelegatedSubject (claim `delegated_sub`) and the canonical target
	// tenant in Tenant (claim `tenant`, falling back to `org`). It never carries
	// `sub` (UserID stays empty), so the local-user gate does not apply.
	Tenant           string
	DelegatedSubject string

	// Attributes is the `attributes` claim of a delegated access 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. "at+jwt" identifies a delegated
	// access token. Empty when the header is absent (e.g. legacy tokens).
	TokenTyp string

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

type ClientIPFunc func(r *http.Request) string

type DelegatedAccessParams struct {
	// Issuer becomes the `iss` claim: the tenant/platform AuthKit issuer that
	// signs the token. Must match a federated 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 canonical `tenant` claim: the target resource tenant/
	// platform slug or identifier. Canonical for this token class.
	Tenant 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

	// CompatOrg, when true, also writes a legacy `org` claim equal to Tenant for
	// resource servers that still read `org`. The canonical `tenant` claim is
	// always written; `org` is compatibility only and MUST equal `tenant`.
	CompatOrg bool
}

type DelegatedPrincipal struct {
	Issuer           string
	Tenant           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` and falling
	// back to the legacy top-level `user_tier` claim during migration.
	UserTier string
	// Roles is NON-AUTHORITATIVE compatibility metadata describing the issuer's
	// local role system. Receiving services MUST NOT use it as authority.
	Roles []string
}

type FederatedIssuerSource interface {
	ListFederatedOrgIssuers(ctx context.Context, activeOnly bool) ([]core.FederatedOrgIssuer, error)
	// GetFederatedOrgIssuer fetches a SINGLE federated-org issuer by its
	// issuer_id, used by the lazy-load-on-miss path in keyForToken. *core.Service
	// already implements this.
	GetFederatedOrgIssuer(ctx context.Context, issuerID string) (*core.FederatedOrgIssuer, error)
}

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

type FederationClientOption func(*FederationClient)

type FederationRegistration struct {
	// Org is THIS org's slug (becomes the `org`/tenant claim of delegated tokens).
	Org string
	// IssuerID is THIS platform's issuer URL (the `iss` of delegated tokens).
	IssuerID string
	// JWKSURL is where the resource server fetches THIS platform's public keys.
	JWKSURL 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 {
	// JWKSURL is the URL to fetch JWKS from. If set, keys are fetched
	// automatically and refreshed when they expire or an unknown kid appears.
	JWKSURL 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. Useful when the caller already
	// has parsed *rsa.PublicKey values (e.g., from a co-located core.Service).
	RawKeys map[string]*rsa.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
}

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 Verifier struct {
	// contains filtered or unexported fields
}

type VerifierOption func(*Verifier)