@hyper.authio/server 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,439 @@
+import { AuthioResourceAccess, AuthioResourceAccessSource, AuthioError, AuthioConnection, AuthioDiscoveryClient, AuthioClient, AuthioConnectionOptions, AuthioClientOptions, AuthioWebhookEvent, AuthioClock, AuthioWebhookDataByType, AuthioTypedWebhookEvent, AuthioClientCredentialsToken } from '@hyper.authio/client';
+
+/**
+ * The party acting for the subject, from the `act` claim (RFC 8693): who exchanged the token, nested when the chain
+ * is longer.
+ */
+interface AuthioActor {
+    readonly clientId: string | undefined;
+    readonly subject: string | undefined;
+    readonly actor: AuthioActor | undefined;
+}
+/**
+ * Where the user reads flat (non-`*_resource_access`) roles and groups from.
+ */
+interface AuthioUserClaimSettings {
+    /**
+     * Claims holding role names directly, such as one written by a claim mapper with the Role source. They count for
+     * `hasRole` without a source filter. Defaults to `["role"]`.
+     */
+    roleClaims?: readonly string[];
+    /**
+     * Claims holding group names, such as one written by a claim mapper with the Group source. Defaults to
+     * `["groups"]`.
+     */
+    groupClaims?: readonly string[];
+}
+/**
+ * The caller of an API, read from a validated access token or an introspection answer: identity, every form of
+ * permission Authio issues, and the raw claims for anything else.
+ */
+declare class AuthioUser {
+    /** `sub`: the person's id, or the credential's for a machine caller. */
+    readonly subject: string;
+    /** The client the token was issued to (`azp`, else `client_id`). */
+    readonly clientId: string | undefined;
+    /** `sid`. */
+    readonly sessionId: string | undefined;
+    /** `jti`. */
+    readonly tokenId: string | undefined;
+    /** `aud`. */
+    readonly audiences: readonly string[];
+    /** The granted scopes. */
+    readonly scopes: readonly string[];
+    /** The roles of the seven `*_resource_access` claims, with their source and permissions. */
+    readonly resourceAccess: AuthioResourceAccess;
+    /** Every role name: the `*_resource_access` roles, then the flat role claims. */
+    readonly roles: readonly string[];
+    /** Resource → every method any role allows on it. */
+    readonly permissions: Readonly<Record<string, readonly string[]>>;
+    /** The group names of the group claims. */
+    readonly groups: readonly string[];
+    /** `org_id`. */
+    readonly organizationId: string | undefined;
+    /** `org_alias`. */
+    readonly organizationAlias: string | undefined;
+    /** `account_id`. */
+    readonly accountId: string | undefined;
+    /** `acr`. */
+    readonly acr: string | undefined;
+    /** `acr` as a number: 1 one factor, 2 several, 3 one of them phishing-resistant. */
+    readonly authenticationLevel: number | undefined;
+    /** `amr`. */
+    readonly authenticationMethods: readonly string[];
+    /** `idp`. */
+    readonly identityProvider: string | undefined;
+    /** `auth_time`. */
+    readonly authenticatedAt: Date | undefined;
+    /** `act`. */
+    readonly actor: AuthioActor | undefined;
+    /** `delegation_id`. */
+    readonly delegationId: string | undefined;
+    readonly email: string | undefined;
+    readonly emailVerified: boolean | undefined;
+    readonly name: string | undefined;
+    readonly preferredUsername: string | undefined;
+    /** `credential_type`, on a token issued to an account credential or a consumer. */
+    readonly credentialType: string | undefined;
+    /** `credential_id`. */
+    readonly credentialId: string | undefined;
+    /** Every claim, as the token or the introspection answer carried it. */
+    readonly claims: Readonly<Record<string, unknown>>;
+    /** The access token the user was read from. Not enumerable, so it stays out of logs and JSON. */
+    readonly token: string | undefined;
+    private readonly flatRoles;
+    /**
+     * @param claims The token's payload, or the introspection answer's members.
+     * @param settings Where flat roles and groups are read from.
+     * @param token The access token, kept for forwarding and on-behalf-of.
+     */
+    constructor(claims: Readonly<Record<string, unknown>>, settings?: AuthioUserClaimSettings, token?: string);
+    /** Whether an actor exchanged the token on the subject's behalf. */
+    get isDelegated(): boolean;
+    /** Whether the scope was granted. */
+    hasScope(scope: string): boolean;
+    /**
+     * Whether the user holds the role. Without sources, from any `*_resource_access` claim or a flat role claim; with
+     * sources, only from those `*_resource_access` claims.
+     */
+    hasRole(role: string, options?: {
+        sources?: readonly AuthioResourceAccessSource[];
+    }): boolean;
+    /**
+     * Authio's grant rule: whether a role (from any source, or only from the given ones) allows `method` on
+     * `resource`. Case-insensitive.
+     */
+    hasPermission(resource: string, method: string, options?: {
+        sources?: readonly AuthioResourceAccessSource[];
+    }): boolean;
+    /** Whether the user is in the group (exact match). */
+    hasGroup(group: string): boolean;
+    /**
+     * Whether the claim is present (not `null`), and, given values, whether it holds one of them (exact match; an
+     * array claim matches when any item does).
+     */
+    hasClaim(type: string, ...values: string[]): boolean;
+    /**
+     * The claim's values as text: one for a scalar, one per item for an array, JSON text for an object.
+     */
+    claimValues(type: string): string[];
+    /** Every member but the raw token. */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * How several required values combine.
+ */
+type AuthioMatch = "any" | "all";
+/**
+ * Why a rule refused the caller.
+ */
+interface AuthioRuleFailure {
+    /** What is missing, in words. */
+    readonly message: string;
+    /**
+     * The RFC 6750 / RFC 9470 error to put in `WWW-Authenticate`: `insufficient_scope` for scopes,
+     * `insufficient_user_authentication` for `acr`/`amr`, none otherwise.
+     */
+    readonly error?: "insufficient_scope" | "insufficient_user_authentication";
+    /** The required scopes, for `insufficient_scope`. */
+    readonly scope?: string;
+}
+/**
+ * A condition on the caller.
+ */
+interface AuthioRule {
+    /** What the rule requires, for logs. */
+    readonly description: string;
+    /** `undefined` when the caller satisfies the rule, else why not. */
+    check(user: AuthioUser): AuthioRuleFailure | undefined;
+}
+/**
+ * Checks every rule. On refusal the message joins every rule's, and the error is the one asking for a stronger
+ * sign-in, else the first one that has an error.
+ */
+declare function authorize(user: AuthioUser, ...rules: AuthioRule[]): AuthioRuleFailure | undefined;
+/**
+ * Requires granted scopes.
+ */
+declare function requireScope(scopes: string | readonly string[], match?: AuthioMatch): AuthioRule;
+/**
+ * Requires roles, from any source or only from the given `*_resource_access` claims.
+ */
+declare function requireRole(roles: string | readonly string[], options?: {
+    match?: AuthioMatch;
+    sources?: readonly AuthioResourceAccessSource[];
+}): AuthioRule;
+/**
+ * Requires a permission (`method` on `resource`), granted by a role from any source or only from the given ones.
+ */
+declare function requirePermission(resource: string, method: string, options?: {
+    sources?: readonly AuthioResourceAccessSource[];
+}): AuthioRule;
+/**
+ * Requires groups, read from the group claims (a claim mapper with the Group source).
+ */
+declare function requireGroup(groups: string | readonly string[], match?: AuthioMatch): AuthioRule;
+/**
+ * Requires a claim: present, or holding one of the given values. Fits claim-mapper claims, the user's own claims and
+ * any other claim Authio issues.
+ */
+declare function requireClaim(type: string, ...values: string[]): AuthioRule;
+/**
+ * Requires an organization context, or a given organization (alias or id, case-insensitive).
+ */
+declare function requireOrganization(organization?: string): AuthioRule;
+/**
+ * Requires a minimum authentication level (`acr`): 1 one factor, 2 several, 3 one of them phishing-resistant.
+ */
+declare function requireAuthenticationLevel(minimumLevel: number): AuthioRule;
+/**
+ * Requires authentication methods (`amr`, case-insensitive), such as `otp`, `swk` or `fed`.
+ */
+declare function requireAuthenticationMethod(methods: string | readonly string[], match?: AuthioMatch): AuthioRule;
+/**
+ * Requires the token to have been issued to one of the clients (`azp`, else `client_id`).
+ */
+declare function requireClient(clientIds: string | readonly string[]): AuthioRule;
+/**
+ * Requires every rule.
+ */
+declare function allOf(...rules: AuthioRule[]): AuthioRule;
+/**
+ * Requires at least one rule; the refusal is the first rule's.
+ */
+declare function anyOf(...rules: AuthioRule[]): AuthioRule;
+
+/**
+ * The request carries no valid access token: answer `401` with `wwwAuthenticate`.
+ */
+declare class AuthioBearerError extends AuthioError {
+    readonly status = 401;
+    /** `invalid_token`, or `undefined` when the request had no token at all (RFC 6750 §3.1). */
+    readonly error: "invalid_token" | undefined;
+    /** Why the token was refused, safe to send to the caller. */
+    readonly description: string | undefined;
+    constructor(description: string | undefined, options?: {
+        error?: "invalid_token" | undefined;
+        cause?: unknown;
+    });
+    /** The `WWW-Authenticate` value. */
+    get wwwAuthenticate(): string;
+}
+/**
+ * The caller is known but not allowed: answer `403`, with `wwwAuthenticate` when the refusal has a bearer error.
+ */
+declare class AuthioForbiddenError extends AuthioError {
+    readonly status = 403;
+    readonly failure: AuthioRuleFailure;
+    constructor(failure: AuthioRuleFailure);
+    /** The `WWW-Authenticate` value, or `undefined` when the refusal is not about scopes or the sign-in. */
+    get wwwAuthenticate(): string | undefined;
+}
+/**
+ * The `WWW-Authenticate` value of a refusal: `insufficient_scope` (with `scope`) or
+ * `insufficient_user_authentication`.
+ */
+declare function toForbiddenChallenge(failure: AuthioRuleFailure): string | undefined;
+/**
+ * Problem details (RFC 9457) for a `401` or `403`.
+ */
+declare function toProblemDetails(error: AuthioBearerError | AuthioForbiddenError): Record<string, unknown>;
+
+/**
+ * Whether and how Authio's introspection endpoint takes part in validating a token.
+ *
+ * - `none`: the JWT is validated locally (signature, issuer, audience, lifetime). Fastest; a revoked token stays
+ *   valid until it expires.
+ * - `activeCheck`: validated locally, then confirmed active by introspection (cached per `jti`).
+ * - `introspectionOnly`: introspection alone, for opaque (reference) or encrypted tokens.
+ */
+type AuthioIntrospectionMode = "none" | "activeCheck" | "introspectionOnly";
+/**
+ * How an API validates Authio access tokens.
+ */
+interface AuthioVerifierOptions extends AuthioConnectionOptions, AuthioUserClaimSettings {
+    /** The audiences this API accepts: its resource identifier (RFC 8707) or client id. Required. */
+    audiences: string | readonly string[];
+    /** Defaults to `none`. */
+    introspection?: AuthioIntrospectionMode;
+    /**
+     * The API's confidential client, for introspection: a client already created, or its options (issuer settings are
+     * taken from these options when absent). It must be the client the resource server names as its introspection
+     * client, since Authio answers introspection according to who asks.
+     */
+    client?: AuthioClient | Omit<AuthioClientOptions, keyof AuthioConnectionOptions>;
+    /** Seconds an active introspection answer is kept (never past the token's expiry). Defaults to 30. */
+    introspectionCacheDuration?: number;
+    /** Seconds of clock skew tolerated on `exp` and `nbf`. Defaults to 30. */
+    clockSkew?: number;
+    /** Accepted signing algorithms. Defaults to the asymmetric ones (RS*, PS*, ES*). */
+    validAlgorithms?: readonly string[];
+    /** Refuses a token whose `typ` claim is present and not `Bearer` (an ID token, for one). Defaults to `true`. */
+    rejectNonAccessTokens?: boolean;
+}
+/**
+ * Validates Authio access tokens and reads the caller.
+ */
+interface AuthioVerifier {
+    /** The connection settings. */
+    readonly connection: AuthioConnection;
+    /** The discovery document. */
+    readonly discovery: AuthioDiscoveryClient;
+    /** The accepted audiences. */
+    readonly audiences: readonly string[];
+    /** The introspection mode. */
+    readonly introspection: AuthioIntrospectionMode;
+    /** The client used for introspection, when there is one. */
+    readonly client: AuthioClient | undefined;
+    /**
+     * Validates a token and reads the caller.
+     *
+     * @throws AuthioBearerError when the token is not valid for this API.
+     */
+    verify(token: string, signal?: AbortSignal): Promise<AuthioUser>;
+    /**
+     * Validates the token of an `Authorization: Bearer` header.
+     *
+     * @throws AuthioBearerError without an error code when there is no bearer token, with `invalid_token` when it is
+     * not valid.
+     */
+    verifyAuthorizationHeader(header: string | null | undefined, signal?: AbortSignal): Promise<AuthioUser>;
+}
+/**
+ * Error descriptions of the refusals the SDK makes itself.
+ */
+declare const AuthioBearerErrorDescriptions: {
+    readonly Inactive: "Authio reports the token as not active to this API's client. It was revoked or has expired or its session ended; or this API's client is not the introspection client of the resource server the token is for.";
+    readonly Unconfirmed: "Authio could not be reached to confirm that the token is active.";
+    readonly Empty: "The token is empty.";
+    readonly Encrypted: "The token is encrypted; validate it with introspection ('introspectionOnly').";
+    readonly SigningKeysUnavailable: "Authio could not be reached to read its signing keys.";
+};
+/**
+ * Creates a token verifier.
+ *
+ * @throws AuthioConfigurationError when no audience is given, or introspection is asked for without a client.
+ */
+declare function createAuthioVerifier(options: AuthioVerifierOptions): AuthioVerifier;
+/**
+ * The token of an `Authorization: Bearer` header, or `undefined` when the header is absent or of another scheme.
+ */
+declare function readBearerToken(header: string | null | undefined): string | undefined;
+
+/**
+ * Remembers delivered event ids, so a redelivery is acknowledged without running the handlers twice.
+ */
+interface AuthioWebhookDeduplicationStore {
+    /** Records the id; `false` when it was already recorded within the window. */
+    tryBegin(eventId: string, windowMs: number): boolean | Promise<boolean>;
+    /** Forgets the id, after a handler failed, so the redelivery runs again. */
+    release(eventId: string): void | Promise<void>;
+}
+/**
+ * How webhook deliveries are received.
+ */
+interface AuthioWebhookOptions {
+    /** The webhook's secret. */
+    secret?: string;
+    /** Several secrets, while one is being rotated; a delivery signed with any of them is accepted. */
+    secrets?: readonly string[];
+    /** Seconds a signature's timestamp may differ from now. Defaults to 300. */
+    tolerance?: number;
+    /** `memory` (default), `none`, or a store shared between instances. */
+    deduplication?: "memory" | "none" | AuthioWebhookDeduplicationStore;
+    /** Seconds a delivered id is remembered. Defaults to 86400. */
+    deduplicationWindow?: number;
+    /** The largest body accepted, in bytes. Defaults to 1 MiB. */
+    maxBodySize?: number;
+    /** The clock. */
+    clock?: AuthioClock;
+    /** Called when a delivery is refused or a handler fails. */
+    onError?: (error: unknown, context: {
+        reason: string;
+        eventId?: string;
+        eventType?: string;
+    }) => void;
+}
+/**
+ * A handler of one event type, or of every type.
+ */
+type AuthioWebhookHandler<E extends AuthioWebhookEvent = AuthioWebhookEvent> = (event: E) => void | Promise<void>;
+/**
+ * What to answer a delivery with.
+ */
+interface AuthioWebhookOutcome {
+    /** `200` handled, duplicate or ping; `400` unreadable; `401` bad or stale signature; `413` too large; `500` a handler failed. */
+    readonly status: 200 | 400 | 401 | 413 | 500;
+    /** Why, for logs. */
+    readonly reason: "handled" | "duplicate" | "unreadable" | "unsigned" | "too_large" | "handler_failed";
+    readonly event?: AuthioWebhookEvent;
+}
+/**
+ * Receives Authio webhook deliveries: verifies, deduplicates and dispatches them.
+ */
+interface AuthioWebhooks {
+    /** Handles one event type, typed. */
+    on<T extends keyof AuthioWebhookDataByType>(type: T, handler: AuthioWebhookHandler<AuthioTypedWebhookEvent<T>>): AuthioWebhooks;
+    /** Handles another event type, or `*` for every type. */
+    on(type: string, handler: AuthioWebhookHandler): AuthioWebhooks;
+    /**
+     * Handles a delivery: the body exactly as received and the request headers.
+     */
+    handle(delivery: {
+        body: string | Uint8Array;
+        headers: Headers | Record<string, string | string[] | undefined>;
+    }): Promise<AuthioWebhookOutcome>;
+    /** The largest body accepted, in bytes. */
+    readonly maxBodySize: number;
+}
+/**
+ * Creates a webhook receiver. Handlers run in registration order; a `*` handler sees every event.
+ *
+ * @throws AuthioConfigurationError when no secret is configured.
+ */
+declare function createAuthioWebhooks(options: AuthioWebhookOptions): AuthioWebhooks;
+/**
+ * A deduplication store kept in this process's memory.
+ */
+declare function createMemoryDeduplicationStore(clock?: AuthioClock): AuthioWebhookDeduplicationStore;
+
+/**
+ * Who a downstream call is made for: a caller read by the verifier, or the incoming access token itself.
+ */
+type AuthioDownstreamSubject = AuthioUser | string;
+/**
+ * A `fetch` that forwards the caller's own access token, unchanged, to a downstream API that accepts the same
+ * audience. Sends no `Authorization` when there is no token.
+ */
+declare function createForwardingFetch(subject: AuthioDownstreamSubject | undefined, inner?: typeof fetch): typeof fetch;
+/**
+ * Exchanges the caller's token for one addressed to a downstream API (RFC 8693), and caches it.
+ */
+interface AuthioOnBehalfOf {
+    /**
+     * A token for the downstream API on the caller's behalf: cached per incoming `jti` (else token hash), resource and
+     * sorted scopes, renewed `tokenRefreshSkew` before expiry (at most half its lifetime); concurrent callers share
+     * one exchange.
+     *
+     * @throws AuthioError when there is no incoming token.
+     */
+    getToken(subject: AuthioDownstreamSubject | undefined, signal?: AbortSignal): Promise<AuthioClientCredentialsToken>;
+    /** Drops a cached token; with `accessToken`, only when the cache still holds that token. */
+    invalidate(subject: AuthioDownstreamSubject, accessToken?: string): Promise<void>;
+    /** A `fetch` that sends the exchanged token, and on a `401` drops it and retries once. */
+    fetch(subject: AuthioDownstreamSubject | undefined, inner?: typeof fetch): typeof fetch;
+}
+/**
+ * Creates an on-behalf-of exchanger.
+ *
+ * @param options `client` (the API's confidential client), the downstream `resource` and `scopes`.
+ */
+declare function createOnBehalfOf(options: {
+    client: AuthioClient;
+    resource?: string;
+    scopes?: Iterable<string> | string;
+    tokenRefreshSkew?: number;
+}): AuthioOnBehalfOf;
+
+export { type AuthioActor, AuthioBearerError, AuthioBearerErrorDescriptions, type AuthioDownstreamSubject, AuthioForbiddenError, type AuthioIntrospectionMode, type AuthioMatch, type AuthioOnBehalfOf, type AuthioRule, type AuthioRuleFailure, AuthioUser, type AuthioUserClaimSettings, type AuthioVerifier, type AuthioVerifierOptions, type AuthioWebhookDeduplicationStore, type AuthioWebhookHandler, type AuthioWebhookOptions, type AuthioWebhookOutcome, type AuthioWebhooks, allOf, anyOf, authorize, createAuthioVerifier, createAuthioWebhooks, createForwardingFetch, createMemoryDeduplicationStore, createOnBehalfOf, readBearerToken, requireAuthenticationLevel, requireAuthenticationMethod, requireClaim, requireClient, requireGroup, requireOrganization, requirePermission, requireRole, requireScope, toForbiddenChallenge, toProblemDetails };