@hyper.authio/testing 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -21,14 +21,49 @@ interface FakeAuthioClientEncryption {
     logoutTokens?: boolean;
 }
 /**
- * A client registered in the fake.
+ * How a client authenticates to the token, introspection, revocation and device endpoints, as registered in Authio.
+ */
+type FakeAuthioTokenEndpointAuthMethod = "client_secret_basic" | "client_secret_post" | "private_key_jwt" | "none";
+/**
+ * The algorithm Authio signs every token of a client with: the realm's RSA key, or the client secret (HS*).
+ */
+type FakeAuthioSigningAlgorithm = "RS256" | "HS256" | "HS384" | "HS512";
+/**
+ * A client registered in the fake, configured as a client is in Authio's console. What the client requires is
+ * enforced as Authio enforces it: a request that does not match is refused with an error naming the setting, and
+ * what the client does not require is accepted (PKCE sent voluntarily, a secret sent by a public client).
  */
 interface FakeAuthioClient {
     clientId: string;
-    /** For `client_secret_basic` and `client_secret_post`. */
+    /** For `client_secret_basic` and `client_secret_post`, and the key of HS* signatures. */
     clientSecret?: string;
     /** The public JWK `private_key_jwt` assertions are verified with. */
     publicKey?: JWK;
+    /**
+     * How the client must authenticate; another method is refused with `invalid_client`, except a secret sent by a
+     * `none` client, which is ignored. Defaults to `client_secret_basic` with a `clientSecret`, `private_key_jwt` with
+     * only a `publicKey`, and `none` with neither.
+     */
+    tokenEndpointAuthMethod?: FakeAuthioTokenEndpointAuthMethod;
+    /**
+     * Refuses an authorization request without `code_challenge` (Authio's "PKCE" switch). Defaults to `true`, as Authio
+     * creates clients; set `false` for a client with PKCE off.
+     */
+    requirePkce?: boolean;
+    /**
+     * The PKCE methods accepted, required or not: a `code_challenge` with another method is refused. Defaults to
+     * `["S256"]`, as Authio creates clients.
+     */
+    pkceMethods?: ("S256" | "plain")[];
+    /**
+     * The algorithm the client's ID tokens, signed UserInfo and logout tokens are signed with. Defaults to `RS256`. HS*
+     * needs a `clientSecret` of at least 32, 48 or 64 bytes (RFC 7518 §3.2), as Authio requires.
+     */
+    signingAlgorithm?: FakeAuthioSigningAlgorithm;
+    /** The algorithm the client's access tokens are signed with, Authio's second setting. Defaults to `RS256`. */
+    accessTokenSigningAlgorithm?: FakeAuthioSigningAlgorithm;
+    /** Issues a new ID token with every refresh. Defaults to `false`. */
+    issueIdTokenOnRefresh?: boolean;
     /** Scopes granted when a request names none. */
     defaultScopes?: string[];
     /** Extra claims put into every access token issued to the client. */
@@ -41,6 +76,10 @@ interface FakeAuthioClient {
     postLogoutRedirectUris?: string[];
     /** Where back-channel logout tokens are posted when a session of the client ends. */
     backchannelLogoutUri?: string;
+    /** The page loaded (here: fetched) when a session of the client ends (front-channel logout). */
+    frontchannelLogoutUri?: string;
+    /** Adds `iss` and `sid` to the front-channel logout URI. Defaults to `false`. */
+    frontchannelLogoutSessionRequired?: boolean;
     /** Encrypts what is issued to the client. */
     encryption?: FakeAuthioClientEncryption;
 }
@@ -104,6 +143,16 @@ interface FakeAuthioBackchannelDelivery {
     /** The HTTP status the client answered, or 0 when it could not be reached. */
     status: number;
 }
+/**
+ * A front-channel logout page the fake loaded for a client.
+ */
+interface FakeAuthioFrontchannelDelivery {
+    clientId: string;
+    /** The URL loaded, with `iss` and `sid` when the client requires the session. */
+    url: 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.
  */
@@ -128,6 +177,13 @@ interface FakeAuthioOptions {
     clients?: FakeAuthioClient[];
     users?: FakeAuthioUser[];
     personalAccessTokens?: FakeAuthioPersonalAccessToken[];
+    /**
+     * The clock tokens are issued and checked with (milliseconds since the epoch), such as the `ManualClock` the
+     * library under test uses. Defaults to the system clock.
+     */
+    clock?: {
+        now(): number;
+    };
 }
 /**
  * Options of a token minted directly.
@@ -157,11 +213,12 @@ interface FakeAuthioTokenOptions {
 }
 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.
+ * An in-memory Authio realm served over HTTP on loopback: discovery, JWKS, authorization (PKCE required or not and its
+ * allowed methods, `state`, `nonce`, `prompt`, `max_age`, `acr_values`, `response_mode` query or web_message, RFC 9207
+ * `iss`), token (client credentials, authorization code with ID tokens, refresh, token exchange, password, device code,
+ * personal access token) with the client's exact authentication method, introspection, revocation, UserInfo, device
+ * authorization, end session, back-channel and front-channel logout delivery, tokens signed RS256 or HS* with the
+ * client secret, and JWE (RSA-OAEP, RSA-OAEP-256) for clients that registered an encryption key.
  */
 declare class FakeAuthio {
     /** Every request received, in order. */
@@ -170,6 +227,8 @@ declare class FakeAuthio {
     readonly failures: Map<Endpoint, FakeAuthioError[]>;
     /** Every back-channel logout token posted, in order. */
     readonly backchannelDeliveries: FakeAuthioBackchannelDelivery[];
+    /** Every front-channel logout page loaded, in order. */
+    readonly frontchannelDeliveries: FakeAuthioFrontchannelDelivery[];
     /** 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. */
@@ -190,6 +249,7 @@ declare class FakeAuthio {
     private readonly issued;
     private readonly devicePolls;
     private readonly lifetime;
+    private readonly clock;
     private session;
     private server;
     private signingKey;
@@ -267,6 +327,20 @@ declare class FakeAuthio {
         sub?: string;
         sid?: string;
     }): Promise<number>;
+    /**
+     * The front-channel logout URL of a client for a session: its `frontchannelLogoutUri`, with `iss` and `sid` when the
+     * client requires the session.
+     */
+    frontchannelLogoutUrl(clientId: string, sid: string): string;
+    /**
+     * Loads the client's front-channel logout page, as the browser does in an iframe when Authio ends a session.
+     *
+     * @returns The HTTP status the client answered, or 0 when it could not be reached.
+     */
+    deliverFrontchannelLogout(clientId: string, options: {
+        sid: string;
+        headers?: Record<string, 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. */
@@ -292,6 +366,9 @@ declare class FakeAuthio {
     private revoke;
     private device;
     private userInfo;
+    private nowSeconds;
+    private sign;
+    private verificationKeyFor;
     private requireUser;
 }
 
@@ -339,4 +416,4 @@ declare function createWebhookDelivery(type: string, data: unknown, secret: stri
     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 };
+export { FakeAuthio, type FakeAuthioAuthorizationOutcome, type FakeAuthioBackchannelDelivery, type FakeAuthioClient, type FakeAuthioClientEncryption, type FakeAuthioDeviceOutcome, type FakeAuthioError, type FakeAuthioFrontchannelDelivery, type FakeAuthioOptions, type FakeAuthioPersonalAccessToken, type FakeAuthioRecordedRequest, type FakeAuthioSigningAlgorithm, type FakeAuthioTokenEndpointAuthMethod, type FakeAuthioTokenOptions, type FakeAuthioUser, type FakeWebhookDelivery, ManualClock, createWebhookDelivery };

package/dist/index.d.ts

@@ -21,14 +21,49 @@ interface FakeAuthioClientEncryption {
     logoutTokens?: boolean;
 }
 /**
- * A client registered in the fake.
+ * How a client authenticates to the token, introspection, revocation and device endpoints, as registered in Authio.
+ */
+type FakeAuthioTokenEndpointAuthMethod = "client_secret_basic" | "client_secret_post" | "private_key_jwt" | "none";
+/**
+ * The algorithm Authio signs every token of a client with: the realm's RSA key, or the client secret (HS*).
+ */
+type FakeAuthioSigningAlgorithm = "RS256" | "HS256" | "HS384" | "HS512";
+/**
+ * A client registered in the fake, configured as a client is in Authio's console. What the client requires is
+ * enforced as Authio enforces it: a request that does not match is refused with an error naming the setting, and
+ * what the client does not require is accepted (PKCE sent voluntarily, a secret sent by a public client).
  */
 interface FakeAuthioClient {
     clientId: string;
-    /** For `client_secret_basic` and `client_secret_post`. */
+    /** For `client_secret_basic` and `client_secret_post`, and the key of HS* signatures. */
     clientSecret?: string;
     /** The public JWK `private_key_jwt` assertions are verified with. */
     publicKey?: JWK;
+    /**
+     * How the client must authenticate; another method is refused with `invalid_client`, except a secret sent by a
+     * `none` client, which is ignored. Defaults to `client_secret_basic` with a `clientSecret`, `private_key_jwt` with
+     * only a `publicKey`, and `none` with neither.
+     */
+    tokenEndpointAuthMethod?: FakeAuthioTokenEndpointAuthMethod;
+    /**
+     * Refuses an authorization request without `code_challenge` (Authio's "PKCE" switch). Defaults to `true`, as Authio
+     * creates clients; set `false` for a client with PKCE off.
+     */
+    requirePkce?: boolean;
+    /**
+     * The PKCE methods accepted, required or not: a `code_challenge` with another method is refused. Defaults to
+     * `["S256"]`, as Authio creates clients.
+     */
+    pkceMethods?: ("S256" | "plain")[];
+    /**
+     * The algorithm the client's ID tokens, signed UserInfo and logout tokens are signed with. Defaults to `RS256`. HS*
+     * needs a `clientSecret` of at least 32, 48 or 64 bytes (RFC 7518 §3.2), as Authio requires.
+     */
+    signingAlgorithm?: FakeAuthioSigningAlgorithm;
+    /** The algorithm the client's access tokens are signed with, Authio's second setting. Defaults to `RS256`. */
+    accessTokenSigningAlgorithm?: FakeAuthioSigningAlgorithm;
+    /** Issues a new ID token with every refresh. Defaults to `false`. */
+    issueIdTokenOnRefresh?: boolean;
     /** Scopes granted when a request names none. */
     defaultScopes?: string[];
     /** Extra claims put into every access token issued to the client. */
@@ -41,6 +76,10 @@ interface FakeAuthioClient {
     postLogoutRedirectUris?: string[];
     /** Where back-channel logout tokens are posted when a session of the client ends. */
     backchannelLogoutUri?: string;
+    /** The page loaded (here: fetched) when a session of the client ends (front-channel logout). */
+    frontchannelLogoutUri?: string;
+    /** Adds `iss` and `sid` to the front-channel logout URI. Defaults to `false`. */
+    frontchannelLogoutSessionRequired?: boolean;
     /** Encrypts what is issued to the client. */
     encryption?: FakeAuthioClientEncryption;
 }
@@ -104,6 +143,16 @@ interface FakeAuthioBackchannelDelivery {
     /** The HTTP status the client answered, or 0 when it could not be reached. */
     status: number;
 }
+/**
+ * A front-channel logout page the fake loaded for a client.
+ */
+interface FakeAuthioFrontchannelDelivery {
+    clientId: string;
+    /** The URL loaded, with `iss` and `sid` when the client requires the session. */
+    url: 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.
  */
@@ -128,6 +177,13 @@ interface FakeAuthioOptions {
     clients?: FakeAuthioClient[];
     users?: FakeAuthioUser[];
     personalAccessTokens?: FakeAuthioPersonalAccessToken[];
+    /**
+     * The clock tokens are issued and checked with (milliseconds since the epoch), such as the `ManualClock` the
+     * library under test uses. Defaults to the system clock.
+     */
+    clock?: {
+        now(): number;
+    };
 }
 /**
  * Options of a token minted directly.
@@ -157,11 +213,12 @@ interface FakeAuthioTokenOptions {
 }
 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.
+ * An in-memory Authio realm served over HTTP on loopback: discovery, JWKS, authorization (PKCE required or not and its
+ * allowed methods, `state`, `nonce`, `prompt`, `max_age`, `acr_values`, `response_mode` query or web_message, RFC 9207
+ * `iss`), token (client credentials, authorization code with ID tokens, refresh, token exchange, password, device code,
+ * personal access token) with the client's exact authentication method, introspection, revocation, UserInfo, device
+ * authorization, end session, back-channel and front-channel logout delivery, tokens signed RS256 or HS* with the
+ * client secret, and JWE (RSA-OAEP, RSA-OAEP-256) for clients that registered an encryption key.
  */
 declare class FakeAuthio {
     /** Every request received, in order. */
@@ -170,6 +227,8 @@ declare class FakeAuthio {
     readonly failures: Map<Endpoint, FakeAuthioError[]>;
     /** Every back-channel logout token posted, in order. */
     readonly backchannelDeliveries: FakeAuthioBackchannelDelivery[];
+    /** Every front-channel logout page loaded, in order. */
+    readonly frontchannelDeliveries: FakeAuthioFrontchannelDelivery[];
     /** 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. */
@@ -190,6 +249,7 @@ declare class FakeAuthio {
     private readonly issued;
     private readonly devicePolls;
     private readonly lifetime;
+    private readonly clock;
     private session;
     private server;
     private signingKey;
@@ -267,6 +327,20 @@ declare class FakeAuthio {
         sub?: string;
         sid?: string;
     }): Promise<number>;
+    /**
+     * The front-channel logout URL of a client for a session: its `frontchannelLogoutUri`, with `iss` and `sid` when the
+     * client requires the session.
+     */
+    frontchannelLogoutUrl(clientId: string, sid: string): string;
+    /**
+     * Loads the client's front-channel logout page, as the browser does in an iframe when Authio ends a session.
+     *
+     * @returns The HTTP status the client answered, or 0 when it could not be reached.
+     */
+    deliverFrontchannelLogout(clientId: string, options: {
+        sid: string;
+        headers?: Record<string, 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. */
@@ -292,6 +366,9 @@ declare class FakeAuthio {
     private revoke;
     private device;
     private userInfo;
+    private nowSeconds;
+    private sign;
+    private verificationKeyFor;
     private requireUser;
 }
 
@@ -339,4 +416,4 @@ declare function createWebhookDelivery(type: string, data: unknown, secret: stri
     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 };
+export { FakeAuthio, type FakeAuthioAuthorizationOutcome, type FakeAuthioBackchannelDelivery, type FakeAuthioClient, type FakeAuthioClientEncryption, type FakeAuthioDeviceOutcome, type FakeAuthioError, type FakeAuthioFrontchannelDelivery, type FakeAuthioOptions, type FakeAuthioPersonalAccessToken, type FakeAuthioRecordedRequest, type FakeAuthioSigningAlgorithm, type FakeAuthioTokenEndpointAuthMethod, type FakeAuthioTokenOptions, type FakeAuthioUser, type FakeWebhookDelivery, ManualClock, createWebhookDelivery };