@hyper.authio/testing 0.0.0-stage → 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,342 @@
+import { JWK } from 'jose';
+import { AuthioClock } from '@hyper.authio/client';
+
+/**
+ * How the fake encrypts what it issues to a client, as Authio does once the client registered an encryption key.
+ */
+interface FakeAuthioClientEncryption {
+    /** The client's public encryption key (RSA). */
+    key: JWK;
+    /** Defaults to `RSA-OAEP-256`. */
+    algorithm?: "RSA-OAEP" | "RSA-OAEP-256";
+    /** Defaults to `A256CBC-HS512`. */
+    encryptionMethod?: "A128CBC-HS256" | "A192CBC-HS384" | "A256CBC-HS512";
+    /** Encrypts the client's access tokens (nested JWT). */
+    accessTokens?: boolean;
+    /** Encrypts the client's ID tokens. Defaults to `true`. */
+    idTokens?: boolean;
+    /** Encrypts UserInfo answered as a JWT. Defaults to `true`. */
+    userInfo?: boolean;
+    /** Encrypts back-channel logout tokens. */
+    logoutTokens?: boolean;
+}
+/**
+ * A client registered in the fake.
+ */
+interface FakeAuthioClient {
+    clientId: string;
+    /** For `client_secret_basic` and `client_secret_post`. */
+    clientSecret?: string;
+    /** The public JWK `private_key_jwt` assertions are verified with. */
+    publicKey?: JWK;
+    /** Scopes granted when a request names none. */
+    defaultScopes?: string[];
+    /** Extra claims put into every access token issued to the client. */
+    claims?: Record<string, unknown>;
+    /** The client this one's tokens are introspectable by, besides itself (a resource server's introspection client). */
+    introspectionClients?: string[];
+    /** The redirect URIs the authorization endpoint accepts. Any when absent. */
+    redirectUris?: string[];
+    /** The post-logout redirect URIs the end-session endpoint accepts. Any when absent. */
+    postLogoutRedirectUris?: string[];
+    /** Where back-channel logout tokens are posted when a session of the client ends. */
+    backchannelLogoutUri?: string;
+    /** Encrypts what is issued to the client. */
+    encryption?: FakeAuthioClientEncryption;
+}
+/**
+ * A person the fake knows, for the password grant, authorization codes and UserInfo.
+ */
+interface FakeAuthioUser {
+    sub: string;
+    username: string;
+    password?: string;
+    /** Claims put into the person's access tokens: `*_resource_access`, `org_id`, mapper claims… */
+    claims?: Record<string, unknown>;
+    /** What UserInfo answers besides `sub`. */
+    userInfo?: Record<string, unknown>;
+    /** The sign-in's methods. Defaults to `["pwd"]`. */
+    amr?: string[];
+    /** The sign-in's level. Defaults to `1`, or the `acr_values` asked for. */
+    acr?: string;
+}
+/**
+ * A personal access token the fake accepts with the `personal_access_token` grant.
+ */
+interface FakeAuthioPersonalAccessToken {
+    /** The `pat_…` value. */
+    token: string;
+    /** The credential's id, the token's `sub`. */
+    sub: string;
+    /** The consumer's client, for a consumer's token; the `authio` client of an account otherwise. */
+    clientId?: string;
+    /** Claims added to the access token. */
+    claims?: Record<string, unknown>;
+}
+/**
+ * An error the fake answers a request with.
+ */
+interface FakeAuthioError {
+    status: number;
+    body?: Record<string, unknown>;
+    headers?: Record<string, string>;
+}
+/**
+ * A request the fake received.
+ */
+interface FakeAuthioRecordedRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    form: Record<string, string>;
+    /** The query parameters. */
+    query: Record<string, string>;
+    /** The client the request authenticated as, when it did. */
+    clientId?: string;
+}
+/**
+ * A back-channel logout token the fake posted to a client.
+ */
+interface FakeAuthioBackchannelDelivery {
+    clientId: string;
+    uri: string;
+    logoutToken: string;
+    /** The HTTP status the client answered, or 0 when it could not be reached. */
+    status: number;
+}
+/**
+ * The parameters an authorization ended with, as the fake sent them back.
+ */
+interface FakeAuthioAuthorizationOutcome {
+    /** `code`, `state` and `iss`, or `error`, `error_description`, `state` and `iss`. */
+    parameters: Record<string, string>;
+    /** The redirect URI with the parameters, for `response_mode=query`. */
+    callbackUrl: string | undefined;
+}
+/**
+ * What the device flow answers to successive polls.
+ */
+type FakeAuthioDeviceOutcome = "pending" | "slow_down" | "approved" | "denied" | "expired";
+/**
+ * Options of the fake.
+ */
+interface FakeAuthioOptions {
+    /** The realm. Defaults to `fake`. */
+    realm?: string;
+    /** Seconds tokens live. Defaults to 300. */
+    accessTokenLifetime?: number;
+    clients?: FakeAuthioClient[];
+    users?: FakeAuthioUser[];
+    personalAccessTokens?: FakeAuthioPersonalAccessToken[];
+}
+/**
+ * Options of a token minted directly.
+ */
+interface FakeAuthioTokenOptions {
+    sub?: string;
+    /** One or several audiences. Defaults to the client id. */
+    audience?: string | string[];
+    clientId?: string;
+    scope?: string;
+    /** Seconds. Negative values mint an expired token. */
+    expiresIn?: number;
+    /** The `typ` claim. Defaults to `Bearer`. */
+    type?: string;
+    /** Claims added to the payload. */
+    claims?: Record<string, unknown>;
+    /** Signs with another issuer. */
+    issuer?: string;
+    /** Signs with another key, so the signature does not verify. */
+    untrusted?: boolean;
+    /** Encrypts the token (nested JWT) to this public key, as Authio does for a client with an encryption key. */
+    encryptTo?: {
+        key: JWK;
+        algorithm?: "RSA-OAEP" | "RSA-OAEP-256";
+        encryptionMethod?: string;
+    };
+}
+type Endpoint = "token" | "introspect" | "revoke" | "userinfo" | "device" | "discovery" | "authorize" | "logout";
+/**
+ * An in-memory Authio realm served over HTTP on loopback: discovery, JWKS, authorization (PKCE, `state`, `nonce`,
+ * `prompt`, `max_age`, `acr_values`, `response_mode=web_message`, RFC 9207 `iss`), token (client credentials,
+ * authorization code with ID tokens, refresh, token exchange, password, device code, personal access token),
+ * introspection, revocation, UserInfo, device authorization, end session and back-channel logout delivery, with JWE
+ * (RSA-OAEP, RSA-OAEP-256) for clients that registered an encryption key.
+ */
+declare class FakeAuthio {
+    /** Every request received, in order. */
+    readonly requests: FakeAuthioRecordedRequest[];
+    /** Answers the next requests to an endpoint with these errors, in order, before answering normally. */
+    readonly failures: Map<Endpoint, FakeAuthioError[]>;
+    /** Every back-channel logout token posted, in order. */
+    readonly backchannelDeliveries: FakeAuthioBackchannelDelivery[];
+    /** What successive device-code polls answer; the last value repeats. Defaults to `["approved"]`. */
+    deviceOutcomes: FakeAuthioDeviceOutcome[];
+    /** Overrides the discovery document's issuer, to test the mismatch check. */
+    discoveryIssuer: string | undefined;
+    /** Answers UserInfo as `application/jwt`, signed by the realm key (and encrypted for a client with a key). */
+    userInfoAsJwt: boolean;
+    /** Leaves `iss` out of authorization responses, to test the RFC 9207 check. */
+    omitAuthorizationIssuer: boolean;
+    /** Answers connected-account exchanges. Defaults to granting a token for the provider. */
+    connectionResponder: ((form: Record<string, string>) => FakeAuthioError | Record<string, unknown>) | undefined;
+    /** The person the authorization endpoint signs in when the request names none with `login_hint`. Defaults to the first user. */
+    signInAs: string | undefined;
+    private readonly clients;
+    private readonly users;
+    private readonly personalAccessTokens;
+    private readonly codes;
+    private readonly refreshTokens;
+    private readonly issued;
+    private readonly devicePolls;
+    private readonly lifetime;
+    private session;
+    private server;
+    private signingKey;
+    private verificationKey;
+    private untrustedKey;
+    private publicJwk;
+    private baseUrl;
+    readonly realm: string;
+    readonly keyId = "fake-key-1";
+    private constructor();
+    /**
+     * Starts the fake on a random loopback port.
+     */
+    static start(options?: FakeAuthioOptions): Promise<FakeAuthio>;
+    /** `http://127.0.0.1:{port}`. */
+    get authority(): string;
+    /** `{authority}/realms/{realm}`. */
+    get issuer(): string;
+    /** The realm's public signing key. */
+    get jwks(): {
+        keys: JWK[];
+    };
+    /** The session the authorization endpoint keeps (one browser), or `undefined` when nobody is signed in. */
+    get currentSession(): {
+        sub: string;
+        sid: string;
+        authTime: number;
+    } | undefined;
+    /** Registers a client. */
+    addClient(client: FakeAuthioClient): void;
+    /** Registers a person. */
+    addUser(user: FakeAuthioUser): void;
+    /** Registers a personal access token. */
+    addPersonalAccessToken(token: FakeAuthioPersonalAccessToken): void;
+    /** Ends the signed-in session without notifying anyone, as if it expired. */
+    endSession(): void;
+    /**
+     * Registers an authorization code for a person, as the authorization endpoint would after sign-in.
+     */
+    createAuthorizationCode(options: {
+        clientId: string;
+        username: string;
+        redirectUri: string;
+        scope?: string;
+        codeChallengeVerifier?: string;
+        resource?: string;
+        nonce?: string;
+    }): string;
+    /**
+     * Follows an authorization URL as a browser would, signing in `signInAs` (or the `login_hint`), and returns what
+     * Authio sent back: the callback URL for `response_mode=query`, the posted message's parameters for `web_message`.
+     */
+    authorize(authorizationUrl: string): Promise<FakeAuthioAuthorizationOutcome>;
+    /**
+     * Mints an access token signed by the realm key, recorded so introspection and revocation know it.
+     */
+    issueAccessToken(options?: FakeAuthioTokenOptions): Promise<string>;
+    /**
+     * Mints a back-channel logout token for a client, signed by the realm key. `overrides` replaces claims (`undefined`
+     * removes one) and `type` the header `typ`, to build invalid ones in tests.
+     */
+    createLogoutToken(options: {
+        clientId: string;
+        sub?: string;
+        sid?: string;
+        type?: string;
+        overrides?: Record<string, unknown>;
+    }): Promise<string>;
+    /**
+     * Posts a back-channel logout token to the client's `backchannelLogoutUri`, as Authio does when a session ends.
+     *
+     * @returns The HTTP status the client answered, or 0 when it could not be reached.
+     */
+    deliverBackchannelLogout(clientId: string, options?: {
+        sub?: string;
+        sid?: string;
+    }): Promise<number>;
+    /** Marks a token revoked, as Authio would after a sign-out: an access token, or a refresh token, which is then forgotten. */
+    revokeToken(token: string): void;
+    /** Revokes every refresh token of a person, or of one Authio session (`sid`), as Authio does when a session ends. */
+    revokeRefreshTokens(options: {
+        sub?: string;
+        sid?: string;
+    }): void;
+    /** Forgets the recorded requests. */
+    clearRequests(): void;
+    /** The recorded requests to one endpoint path suffix, such as `/token`. */
+    requestsTo(suffix: string): FakeAuthioRecordedRequest[];
+    /** Stops the server. */
+    close(): Promise<void>;
+    private listen;
+    private handle;
+    private discovery;
+    private authorizeEndpoint;
+    private endSessionEndpoint;
+    private authenticate;
+    private token;
+    private tokenAnswer;
+    private introspect;
+    private revoke;
+    private device;
+    private userInfo;
+    private requireUser;
+}
+
+/**
+ * A clock that moves only when told to. `sleep` returns at once and moves the clock forward by the time asked, so
+ * device polling and cache expiry run instantly and deterministically.
+ */
+declare class ManualClock implements AuthioClock {
+    /** Every `sleep` asked for, in milliseconds. */
+    readonly sleeps: number[];
+    private time;
+    /**
+     * @param start Milliseconds since the epoch. Defaults to the current time.
+     */
+    constructor(start?: number);
+    now(): number;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    /** Moves the clock forward. */
+    advance(ms: number): void;
+    /** Sets the clock. */
+    set(ms: number): void;
+}
+
+/**
+ * A webhook delivery as Authio would send it.
+ */
+interface FakeWebhookDelivery {
+    readonly body: string;
+    readonly headers: Record<string, string>;
+    readonly event: Record<string, unknown>;
+}
+/**
+ * Builds a signed webhook delivery.
+ *
+ * @param type The event type.
+ * @param data The event data.
+ * @param secret The webhook secret.
+ * @param options `id`, `timestamp` (milliseconds) and extra event members.
+ */
+declare function createWebhookDelivery(type: string, data: unknown, secret: string, options?: {
+    id?: string;
+    timestamp?: number;
+    realmId?: string;
+    clientId?: string;
+    sendEventIdHeader?: boolean;
+}): Promise<FakeWebhookDelivery>;
+
+export { FakeAuthio, type FakeAuthioAuthorizationOutcome, type FakeAuthioBackchannelDelivery, type FakeAuthioClient, type FakeAuthioClientEncryption, type FakeAuthioDeviceOutcome, type FakeAuthioError, type FakeAuthioOptions, type FakeAuthioPersonalAccessToken, type FakeAuthioRecordedRequest, type FakeAuthioTokenOptions, type FakeAuthioUser, type FakeWebhookDelivery, ManualClock, createWebhookDelivery };