@hyper.authio/testing 0.0.0-stage → 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,215 @@
+import { JWK } from 'jose';
+import { AuthioClock } from '@hyper.authio/client';
+
+/**
+ * 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[];
+}
+/**
+ * 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>;
+}
+/**
+ * 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 client the request authenticated as, when it did. */
+    clientId?: string;
+}
+/**
+ * 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[];
+}
+/**
+ * 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;
+}
+/**
+ * An in-memory Authio realm served over HTTP on loopback: discovery, JWKS, token (client credentials,
+ * authorization code, refresh, token exchange, password, device code), introspection, revocation, UserInfo and
+ * device authorization.
+ */
+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<"token" | "introspect" | "revoke" | "userinfo" | "device" | "discovery", FakeAuthioError[]>;
+    /** 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. */
+    userInfoAsJwt: boolean;
+    /** Answers connected-account exchanges. Defaults to granting a token for the provider. */
+    connectionResponder: ((form: Record<string, string>) => FakeAuthioError | Record<string, unknown>) | undefined;
+    private readonly clients;
+    private readonly users;
+    private readonly codes;
+    private readonly refreshTokens;
+    private readonly issued;
+    private readonly devicePolls;
+    private readonly lifetime;
+    private server;
+    private signingKey;
+    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[];
+    };
+    /** Registers a client. */
+    addClient(client: FakeAuthioClient): void;
+    /** Registers a person. */
+    addUser(user: FakeAuthioUser): 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;
+    }): string;
+    /**
+     * Mints an access token signed by the realm key, recorded so introspection and revocation know it.
+     */
+    issueAccessToken(options?: FakeAuthioTokenOptions): Promise<string>;
+    /** Marks a token revoked, as Authio would after a sign-out. */
+    revokeToken(token: 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 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 FakeAuthioClient, type FakeAuthioDeviceOutcome, type FakeAuthioError, type FakeAuthioOptions, type FakeAuthioRecordedRequest, type FakeAuthioTokenOptions, type FakeAuthioUser, type FakeWebhookDelivery, ManualClock, createWebhookDelivery };

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+import { JWK } from 'jose';
+import { AuthioClock } from '@hyper.authio/client';
+
+/**
+ * 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[];
+}
+/**
+ * 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>;
+}
+/**
+ * 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 client the request authenticated as, when it did. */
+    clientId?: string;
+}
+/**
+ * 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[];
+}
+/**
+ * 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;
+}
+/**
+ * An in-memory Authio realm served over HTTP on loopback: discovery, JWKS, token (client credentials,
+ * authorization code, refresh, token exchange, password, device code), introspection, revocation, UserInfo and
+ * device authorization.
+ */
+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<"token" | "introspect" | "revoke" | "userinfo" | "device" | "discovery", FakeAuthioError[]>;
+    /** 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. */
+    userInfoAsJwt: boolean;
+    /** Answers connected-account exchanges. Defaults to granting a token for the provider. */
+    connectionResponder: ((form: Record<string, string>) => FakeAuthioError | Record<string, unknown>) | undefined;
+    private readonly clients;
+    private readonly users;
+    private readonly codes;
+    private readonly refreshTokens;
+    private readonly issued;
+    private readonly devicePolls;
+    private readonly lifetime;
+    private server;
+    private signingKey;
+    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[];
+    };
+    /** Registers a client. */
+    addClient(client: FakeAuthioClient): void;
+    /** Registers a person. */
+    addUser(user: FakeAuthioUser): 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;
+    }): string;
+    /**
+     * Mints an access token signed by the realm key, recorded so introspection and revocation know it.
+     */
+    issueAccessToken(options?: FakeAuthioTokenOptions): Promise<string>;
+    /** Marks a token revoked, as Authio would after a sign-out. */
+    revokeToken(token: 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 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 FakeAuthioClient, type FakeAuthioDeviceOutcome, type FakeAuthioError, type FakeAuthioOptions, type FakeAuthioRecordedRequest, type FakeAuthioTokenOptions, type FakeAuthioUser, type FakeWebhookDelivery, ManualClock, createWebhookDelivery };