@hyper.authio/testing 0.1.1 → 0.7.0

package/dist/index.d.ts

@@ -1,6 +1,25 @@
 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.
  */
@@ -16,6 +35,14 @@ interface FakeAuthioClient {
     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.
@@ -28,6 +55,23 @@ interface FakeAuthioUser {
     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.
@@ -45,9 +89,30 @@ interface FakeAuthioRecordedRequest {
     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.
  */
@@ -62,6 +127,7 @@ interface FakeAuthioOptions {
     accessTokenLifetime?: number;
     clients?: FakeAuthioClient[];
     users?: FakeAuthioUser[];
+    personalAccessTokens?: FakeAuthioPersonalAccessToken[];
 }
 /**
  * Options of a token minted directly.
@@ -82,34 +148,52 @@ interface FakeAuthioTokenOptions {
     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, token (client credentials,
- * authorization code, refresh, token exchange, password, device code), introspection, revocation, UserInfo and
- * device authorization.
+ * 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<"token" | "introspect" | "revoke" | "userinfo" | "device" | "discovery", FakeAuthioError[]>;
+    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. */
+    /** 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;
@@ -128,10 +212,20 @@ declare class FakeAuthio {
     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.
      */
@@ -142,13 +236,44 @@ declare class FakeAuthio {
         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>;
-    /** Marks a token revoked, as Authio would after a sign-out. */
+    /**
+     * 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`. */
@@ -158,6 +283,8 @@ declare class FakeAuthio {
     private listen;
     private handle;
     private discovery;
+    private authorizeEndpoint;
+    private endSessionEndpoint;
     private authenticate;
     private token;
     private tokenAnswer;
@@ -212,4 +339,4 @@ declare function createWebhookDelivery(type: string, data: unknown, secret: stri
     sendEventIdHeader?: boolean;
 }): Promise<FakeWebhookDelivery>;
 
-export { FakeAuthio, type FakeAuthioClient, type FakeAuthioDeviceOutcome, type FakeAuthioError, type FakeAuthioOptions, type FakeAuthioRecordedRequest, type FakeAuthioTokenOptions, type FakeAuthioUser, type FakeWebhookDelivery, ManualClock, createWebhookDelivery };
+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 };