@udibo/oauth2 0.1.0

package/esm/testing/services.d.ts

@@ -0,0 +1,373 @@
+/**
+ * In-memory implementations of every OAuth2 service interface.
+ *
+ * The `Memory*Service` family is the public, generic version of the fixtures
+ * the library uses for its own tests. They satisfy the
+ * `UserServiceInterface`, `ClientServiceInterface`, `TokenServiceInterface`,
+ * `AuthorizationCodeServiceInterface`, and `DeviceAuthorizationServiceInterface`
+ * contracts using `Map`-backed storage that lives only for the process /
+ * test lifetime.
+ *
+ * They are deliberately **not** for production: tokens and codes vanish on
+ * restart, there is no concurrency control, and nothing is ever reclaimed — an
+ * expired record stays in its `Map` until something revokes it, and the
+ * revoked-refresh-token tombstones that reuse detection reads are kept for the
+ * process lifetime, so memory grows with every token issued. Port the shape to
+ * a database and it needs the expiry sweep or row TTL these fixtures skip. Use
+ * them to:
+ *
+ * - Spin up a stand-in authorization server in tests of consumer apps.
+ * - Prototype an OAuth2 integration before the database schema lands.
+ * - Drive examples that need realistic data without DB infrastructure.
+ *
+ * Pair with `createMemoryAuthorizationServer` for the one-shot factory
+ * variant, or compose directly when you need finer control.
+ *
+ * @module
+ */
+import type { ClientInterface } from "../models/client.js";
+import type { AuthorizationCode } from "../models/authorization-code.js";
+import type { RefreshToken, Token } from "../models/token.js";
+import type { DeviceAuthorization } from "../models/device-authorization.js";
+import type { AbstractScope, BasicScope } from "../models/scope.js";
+import type { AuthorizationCodeServiceInterface } from "../server/services/authorization-code.js";
+import type { ClientServiceInterface } from "../server/services/client.js";
+import type { DeviceAuthorizationServiceInterface } from "../server/services/device-authorization.js";
+import type { TokenServiceInterface } from "../server/services/token.js";
+import type { UserServiceInterface } from "../server/services/user.js";
+import { type PasswordCredential, type PasswordHasherLike } from "../identity/password.js";
+/** Options for {@link MemoryUserService}. */
+export interface MemoryUserServiceOptions {
+    /**
+     * Hasher used to mint and check credentials. Defaults to
+     * {@link PasswordIdentityService} at a deliberately low iteration count:
+     * these credentials live in a `Map` that dies with the process, so a
+     * production work factor defends nothing here and only slows a test suite
+     * down. Credentials still record their `params`, so one minted by a
+     * production-strength hasher and handed to {@link
+     * MemoryUserService.setCredential} verifies unchanged. Pass your own hasher
+     * to exercise the real cost.
+     */
+    passwords?: PasswordHasherLike;
+}
+/** Minimal user shape the default `MemoryUserService` knows how to index. */
+export interface MemoryUserShape {
+    /** Stable identifier the service indexes users by. */
+    id: string;
+    /** Login name used by the resource-owner password and credential lookups. */
+    username: string;
+}
+/**
+ * In-memory `UserServiceInterface` implementation.
+ *
+ * Generic over the user type — supply your real app's `User` interface
+ * (extending {@link MemoryUserShape}) so fixtures match production data.
+ */
+export declare class MemoryUserService<U extends MemoryUserShape> implements UserServiceInterface<U> {
+    #private;
+    /** Applies the password-hasher default; construct with no arguments for it. */
+    constructor(options?: MemoryUserServiceOptions);
+    /** Adds a user with the given password. Throws on duplicate id or username. */
+    add(user: U, password: string): Promise<void>;
+    /** Looks up a user by id, or resolves `undefined` when none is stored. */
+    get(id: string): Promise<U | undefined>;
+    /**
+     * Resolves the user when the username exists and the password verifies
+     * against its stored salt/hash, otherwise `undefined`. Backs the
+     * resource-owner password-credentials grant.
+     */
+    getAuthenticated(username: string, password: string): Promise<U | undefined>;
+    /** Looks up a user by username without a password check, or `undefined`. */
+    findByUsername(username: string): Promise<U | undefined>;
+    /**
+     * The user's stored password credential, or `undefined`. Shape-compatible
+     * with the identity layer's `IdentityUserStore.getCredential`, so a
+     * memory-backed store can drive the own-auth flows (sign-in, password
+     * reset) in examples and tests.
+     */
+    getCredential(userId: string): Promise<PasswordCredential | undefined>;
+    /**
+     * Replace the user's stored password credential (e.g. after a password
+     * reset). Matches `IdentityUserStore.setCredential`.
+     * @throws Error when no user with `userId` exists.
+     */
+    setCredential(userId: string, credential: PasswordCredential): Promise<void>;
+}
+/**
+ * In-memory `ClientServiceInterface` implementation.
+ *
+ * A client is treated as confidential when {@link add} is called with a
+ * secret, and public when it is not — there is no separate flag to
+ * remember. `getAuthenticated` requires the secret for confidential
+ * clients and accepts a missing secret for public clients.
+ */
+export declare class MemoryClientService<C extends ClientInterface, U> implements ClientServiceInterface<C, U> {
+    #private;
+    /**
+     * Creates an empty client store backed by the given user service.
+     *
+     * @param userService Resolves the owner returned by {@linkcode getUser}
+     * for the client-credentials grant.
+     */
+    constructor(userService: UserServiceInterface<U>);
+    /**
+     * Registers a client. Pass `secret` to make it confidential; omit for a
+     * public client. `ownerUserId` is the user returned by {@link getUser},
+     * used by the client-credentials grant.
+     * @throws Error when a client with the same id is already registered.
+     */
+    add(client: C, secret?: string, ownerUserId?: string): Promise<void>;
+    /** Looks up a client by id, or resolves `undefined` when none is stored. */
+    get(id: string): Promise<C | undefined>;
+    /**
+     * Resolves the client when authentication succeeds, otherwise `undefined`.
+     * Confidential clients (registered with a secret) require a matching
+     * `secret`; public clients (registered without one) ignore it.
+     */
+    getAuthenticated(id: string, secret?: string): Promise<C | undefined>;
+    /**
+     * Resolves the user registered as the client's owner via the `ownerUserId`
+     * passed to {@linkcode add}, or `undefined` when none was set. Accepts the
+     * client or its id.
+     */
+    getUser(client: C | string): Promise<U | undefined>;
+}
+/** Options for {@link MemoryTokenService}. */
+export interface MemoryTokenServiceOptions<C extends ClientInterface, U extends MemoryUserShape> {
+    /** Resolves clients when hydrating stored tokens back into full records. */
+    clientService: ClientServiceInterface<C, U>;
+    /** Resolves users when hydrating stored tokens back into full records. */
+    userService: UserServiceInterface<U>;
+    /** Default access-token lifetime in seconds. Defaults to 1 hour. */
+    accessTokenLifetime?: number;
+    /** Default refresh-token lifetime in seconds. Defaults to 14 days. */
+    refreshTokenLifetime?: number;
+    /**
+     * Default absolute lifetime of a refresh-token family in seconds. Omit to
+     * leave rotation uncapped.
+     */
+    refreshTokenMaxLifetime?: number;
+}
+/**
+ * In-memory `TokenServiceInterface` implementation. Tokens are hashed on
+ * write and looked up by hash, mirroring how a real database-backed token
+ * service would store them.
+ *
+ * Per-client lifetime overrides are supported via three optional fields the
+ * client may declare: `accessTokenLifetime`, `refreshTokenLifetime`, and
+ * `refreshTokenMaxLifetime`. Each takes precedence over the service-wide
+ * default when present.
+ */
+export declare class MemoryTokenService<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> implements TokenServiceInterface<C, U, S> {
+    #private;
+    /** Service-wide access-token lifetime in seconds when a client sets none. */
+    accessTokenLifetime: number;
+    /** Service-wide refresh-token lifetime in seconds when a client sets none. */
+    refreshTokenLifetime: number;
+    /**
+     * Service-wide absolute refresh-token family lifetime in seconds when a
+     * client sets none. Undefined leaves families uncapped.
+     */
+    refreshTokenMaxLifetime?: number;
+    /**
+     * Creates an empty token store.
+     *
+     * @param options Backing client/user services and optional default token
+     * lifetimes.
+     */
+    constructor(options: MemoryTokenServiceOptions<C, U>);
+    /**
+     * Accepts the requested scope verbatim; the stub performs no scope
+     * narrowing. Return `false` from a subclass to reject a request.
+     */
+    acceptedScope(_client: C, _user: U, scope?: S | null): Promise<S | null | undefined | false>;
+    /** Mints a random opaque access token. */
+    generateAccessToken(_client: C, _user: U, _scope?: S | null): Promise<string>;
+    /** Mints a random opaque refresh token. */
+    generateRefreshToken(_client: C, _user: U, _scope?: S | null): Promise<string | undefined>;
+    /**
+     * Returns now plus the client's `accessTokenLifetime` override, falling back
+     * to {@linkcode accessTokenLifetime}.
+     */
+    accessTokenExpiresAt(client: C, _user: U, _scope?: S | null): Promise<Date | undefined>;
+    /**
+     * Returns now plus the client's `refreshTokenLifetime` override, falling
+     * back to {@linkcode refreshTokenLifetime}.
+     */
+    refreshTokenExpiresAt(client: C, _user: U, _scope?: S | null): Promise<Date | undefined>;
+    /**
+     * Returns the family anchor plus the client's `refreshTokenMaxLifetime`
+     * override, falling back to {@linkcode refreshTokenMaxLifetime}, or
+     * `undefined` when neither caps the family.
+     */
+    refreshTokenFamilyExpiresAt(client: C, _user: U, familyCreatedAt: Date, _scope?: S | null): Promise<Date | undefined>;
+    /**
+     * Resolves the token whose access token hashes to the given value, with its
+     * client and user rehydrated, or `undefined` when not found.
+     */
+    getToken(accessToken: string): Promise<Token<C, U, S> | undefined>;
+    /**
+     * Resolves the refresh token whose value hashes to the given input, with its
+     * client and user rehydrated, or `undefined` when not found.
+     */
+    getRefreshToken(refreshToken: string): Promise<RefreshToken<C, U, S> | undefined>;
+    /**
+     * Persists a token, indexing it by hashed access token (and hashed refresh
+     * token, plus authorization-code hash when a `code` is present so
+     * {@linkcode revokeCode} can find it). Returns the input unchanged.
+     */
+    save(token: RefreshToken<C, U, S>): Promise<RefreshToken<C, U, S>>;
+    /**
+     * Persists a token, indexing it by hashed access token (and authorization-code
+     * hash when a `code` is present). Returns the input unchanged.
+     */
+    save(token: Token<C, U, S>): Promise<Token<C, U, S>>;
+    /**
+     * Removes the given token and its paired access/refresh entry. Resolves
+     * `true` when something was removed, `false` otherwise.
+     */
+    revoke(token: Token<C, U, S>): Promise<boolean>;
+    /**
+     * Removes the given refresh token and its paired access entry. Resolves
+     * `true` when something was removed, `false` otherwise.
+     */
+    revoke(token: RefreshToken<C, U, S>): Promise<boolean>;
+    /**
+     * Removes a token by its raw string value. Pass `hint` of `"refresh_token"`
+     * to look it up as a refresh token; any other value treats it as an access
+     * token. Resolves `true` when something was removed.
+     */
+    revoke(token: string, hint?: string | null): Promise<boolean>;
+    /**
+     * Looks up a revoked/rotated-out refresh token for the refresh grant's
+     * reuse detection: revoked refresh records are kept as tombstones instead
+     * of deleted.
+     */
+    getRevokedRefreshToken(refreshToken: string): Promise<RefreshToken<C, U, S> | undefined>;
+    /**
+     * Revokes every live token in a rotation family (reuse detection response).
+     * Resolves `true` when at least one live token was removed.
+     */
+    revokeFamily(familyId: string): Promise<boolean>;
+    /**
+     * Removes every token issued from the given authorization code, used when a
+     * code is replayed. Resolves `true` when at least one token was removed.
+     */
+    revokeCode(code: string): Promise<boolean>;
+}
+/** Options for {@link MemoryAuthorizationCodeService}. */
+export interface MemoryAuthorizationCodeServiceOptions<C extends ClientInterface, U extends MemoryUserShape> {
+    /** Resolves clients when hydrating stored codes back into full records. */
+    clientService: ClientServiceInterface<C, U>;
+    /** Resolves users when hydrating stored codes back into full records. */
+    userService: UserServiceInterface<U>;
+    /** Lifetime in seconds. Defaults to 10 minutes. */
+    lifetime?: number;
+}
+/** In-memory `AuthorizationCodeServiceInterface` implementation. */
+export declare class MemoryAuthorizationCodeService<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> implements AuthorizationCodeServiceInterface<C, U, S> {
+    #private;
+    /** Authorization-code lifetime in seconds applied by {@linkcode expiresAt}. */
+    lifetime: number;
+    /**
+     * Creates an empty authorization-code store.
+     *
+     * @param options Backing client/user services and optional code lifetime.
+     */
+    constructor(options: MemoryAuthorizationCodeServiceOptions<C, U>);
+    /** Mints a random opaque authorization code. */
+    generateCode(_client: C, _user: U, _scope?: S | null): Promise<string>;
+    /** Returns now plus {@linkcode lifetime}. */
+    expiresAt(_client: C, _user: U, _scope?: S | null): Promise<Date>;
+    /**
+     * Resolves the code whose value hashes to the given input, with its client
+     * and user rehydrated, or `undefined` when not found or either is missing.
+     */
+    get(code: string): Promise<AuthorizationCode<C, U, S> | undefined>;
+    /**
+     * Persists an authorization code indexed by its hash, including the PKCE
+     * challenge and redirect URI. Returns the input unchanged.
+     */
+    save(authorizationCode: AuthorizationCode<C, U, S>): Promise<AuthorizationCode<C, U, S>>;
+    /**
+     * Removes a code, accepting the record or its raw string. Resolves `true`
+     * when a code was removed, `false` otherwise.
+     */
+    revoke(authorizationCode: AuthorizationCode<C, U, S> | string): Promise<boolean>;
+}
+/** Options for {@link MemoryDeviceAuthorizationService}. */
+export interface MemoryDeviceAuthorizationServiceOptions<C extends ClientInterface, U extends MemoryUserShape> {
+    /** Resolves clients when hydrating stored authorizations into full records. */
+    clientService: ClientServiceInterface<C, U>;
+    /** Resolves users when hydrating stored authorizations into full records. */
+    userService: UserServiceInterface<U>;
+    /** Lifetime in seconds. Defaults to 30 minutes. */
+    lifetime?: number;
+    /** Polling interval floor in seconds. Defaults to 5. */
+    interval?: number;
+}
+/** In-memory `DeviceAuthorizationServiceInterface` implementation. */
+export declare class MemoryDeviceAuthorizationService<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> implements DeviceAuthorizationServiceInterface<C, U, S> {
+    #private;
+    /** Device-authorization lifetime in seconds applied by {@linkcode expiresAt}. */
+    lifetime: number;
+    /** Minimum seconds clients must wait between token-endpoint polls. */
+    interval: number;
+    /**
+     * Creates an empty device-authorization store.
+     *
+     * @param options Backing client/user services and optional lifetime and
+     * polling interval.
+     */
+    constructor(options: MemoryDeviceAuthorizationServiceOptions<C, U>);
+    /** Mints a random opaque device code (polled by the device). */
+    generateDeviceCode(_client: C, _scope?: S | null): Promise<string>;
+    /**
+     * Mints a short, human-enterable user code in `XXXX-XXXX` form drawn from an
+     * unambiguous alphabet (no vowels or look-alike digits).
+     */
+    generateUserCode(_client: C, _scope?: S | null): Promise<string>;
+    /** Returns now plus {@linkcode lifetime}. */
+    expiresAt(_client: C, _scope?: S | null): Promise<Date>;
+    /**
+     * Persists a device authorization indexed by both its hashed device code and
+     * hashed user code. Returns the input unchanged.
+     */
+    save(authorization: DeviceAuthorization<C, U, S>): Promise<DeviceAuthorization<C, U, S>>;
+    /**
+     * Resolves the authorization for a device code (the value the device polls
+     * with), client and user rehydrated, or `undefined` when not found.
+     */
+    getByDeviceCode(deviceCode: string): Promise<DeviceAuthorization<C, U, S> | undefined>;
+    /**
+     * Resolves the authorization for a user code (the value the user enters in a
+     * browser), client and user rehydrated, or `undefined` when not found.
+     */
+    getByUserCode(userCode: string): Promise<DeviceAuthorization<C, U, S> | undefined>;
+    /**
+     * Marks the authorization granted by `user`, optionally narrowing `scope`,
+     * so a subsequent device-code poll can exchange it for a token. Returns the
+     * updated record. Throws when the authorization is not stored.
+     */
+    approve(authorization: DeviceAuthorization<C, U, S>, user: U, scope?: S | null): Promise<DeviceAuthorization<C, U, S>>;
+    /**
+     * Marks the authorization denied so a subsequent poll is rejected. Returns
+     * the updated record. Throws when the authorization is not stored.
+     */
+    deny(authorization: DeviceAuthorization<C, U, S>): Promise<DeviceAuthorization<C, U, S>>;
+    /**
+     * Records that the device just polled (and stores its current interval) so
+     * `slow_down` rate limiting can be enforced. Returns the updated record.
+     * Throws when the authorization is not stored.
+     */
+    updateLastPolled(authorization: DeviceAuthorization<C, U, S>): Promise<DeviceAuthorization<C, U, S>>;
+    /**
+     * Removes a device authorization, accepting a raw device code or any record
+     * this store returns — including the partially hydrated ones from
+     * {@linkcode getByDeviceCode} and {@linkcode getByUserCode}, which are
+     * resolved back to the stored entry so both its device-code and user-code
+     * index entries are dropped. Resolves `true` only for the call that removed
+     * a live authorization, `false` otherwise.
+     */
+    revoke(authorization: DeviceAuthorization<C, U, S> | string): Promise<boolean>;
+}