@udibo/oauth2 0.1.0

package/esm/testing/services.js

@@ -0,0 +1,703 @@
+/**
+ * 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 { snapshotAuthenticationContext } from "../utils/authentication-context.js";
+import { PasswordIdentityService, } from "../identity/password.js";
+import { sha256Hash } from "../server/utils/hash.js";
+const FIXTURE_PBKDF2_ITERATIONS = 1_000;
+/**
+ * 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 class MemoryUserService {
+    #usersById = new Map();
+    #usersByUsername = new Map();
+    #credentialsByUserId = new Map();
+    #passwords;
+    /** Applies the password-hasher default; construct with no arguments for it. */
+    constructor(options = {}) {
+        this.#passwords = options.passwords ??
+            new PasswordIdentityService({ iterations: FIXTURE_PBKDF2_ITERATIONS });
+    }
+    /** Adds a user with the given password. Throws on duplicate id or username. */
+    async add(user, password) {
+        if (this.#usersById.has(user.id)) {
+            throw new Error(`User with id "${user.id}" already exists`);
+        }
+        if (this.#usersByUsername.has(user.username)) {
+            throw new Error(`User with username "${user.username}" already exists`);
+        }
+        this.#usersById.set(user.id, user);
+        this.#usersByUsername.set(user.username, user);
+        this.#credentialsByUserId.set(user.id, await this.#passwords.hash(password));
+    }
+    /** Looks up a user by id, or resolves `undefined` when none is stored. */
+    get(id) {
+        return Promise.resolve(this.#usersById.get(id));
+    }
+    /**
+     * 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.
+     */
+    async getAuthenticated(username, password) {
+        const user = this.#usersByUsername.get(username);
+        if (!user)
+            return undefined;
+        const credential = this.#credentialsByUserId.get(user.id);
+        if (!credential)
+            return undefined;
+        return await this.#passwords.verify(password, credential)
+            ? user
+            : undefined;
+    }
+    /** Looks up a user by username without a password check, or `undefined`. */
+    findByUsername(username) {
+        return Promise.resolve(this.#usersByUsername.get(username));
+    }
+    /**
+     * 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) {
+        return Promise.resolve(this.#credentialsByUserId.get(userId));
+    }
+    /**
+     * 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, credential) {
+        if (!this.#usersById.has(userId)) {
+            throw new Error(`User with id "${userId}" does not exist`);
+        }
+        this.#credentialsByUserId.set(userId, credential);
+        return Promise.resolve();
+    }
+}
+/**
+ * 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 class MemoryClientService {
+    #clientsById = new Map();
+    #secretHashByClientId = new Map();
+    #ownerUserIdByClientId = new Map();
+    #userService;
+    /**
+     * 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) {
+        this.#userService = userService;
+    }
+    /**
+     * 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.
+     */
+    async add(client, secret, ownerUserId) {
+        if (this.#clientsById.has(client.id)) {
+            throw new Error(`Client with id "${client.id}" already exists`);
+        }
+        this.#clientsById.set(client.id, client);
+        if (secret) {
+            this.#secretHashByClientId.set(client.id, await sha256Hash(secret));
+        }
+        if (ownerUserId) {
+            this.#ownerUserIdByClientId.set(client.id, ownerUserId);
+        }
+    }
+    /** Looks up a client by id, or resolves `undefined` when none is stored. */
+    get(id) {
+        return Promise.resolve(this.#clientsById.get(id));
+    }
+    /**
+     * 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.
+     */
+    async getAuthenticated(id, secret) {
+        const client = this.#clientsById.get(id);
+        if (!client)
+            return undefined;
+        const storedHash = this.#secretHashByClientId.get(id);
+        if (storedHash) {
+            if (!secret)
+                return undefined;
+            if (await sha256Hash(secret) !== storedHash)
+                return undefined;
+        }
+        return client;
+    }
+    /**
+     * 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) {
+        const id = typeof client === "string" ? client : client.id;
+        const userId = this.#ownerUserIdByClientId.get(id);
+        if (!userId)
+            return Promise.resolve(undefined);
+        return this.#userService.get(userId);
+    }
+}
+/**
+ * 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 class MemoryTokenService {
+    /** Service-wide access-token lifetime in seconds when a client sets none. */
+    accessTokenLifetime;
+    /** Service-wide refresh-token lifetime in seconds when a client sets none. */
+    refreshTokenLifetime;
+    /**
+     * Service-wide absolute refresh-token family lifetime in seconds when a
+     * client sets none. Undefined leaves families uncapped.
+     */
+    refreshTokenMaxLifetime;
+    #clientService;
+    #userService;
+    #tokensByAccessHash = new Map();
+    #tokensByRefreshHash = new Map();
+    #tokensByCodeHash = new Map();
+    #revokedByRefreshHash = new Map();
+    /**
+     * Creates an empty token store.
+     *
+     * @param options Backing client/user services and optional default token
+     * lifetimes.
+     */
+    constructor(options) {
+        this.#clientService = options.clientService;
+        this.#userService = options.userService;
+        this.accessTokenLifetime = options.accessTokenLifetime ?? 60 * 60;
+        this.refreshTokenLifetime = options.refreshTokenLifetime ??
+            14 * 24 * 60 * 60;
+        this.refreshTokenMaxLifetime = options.refreshTokenMaxLifetime;
+    }
+    /**
+     * Accepts the requested scope verbatim; the stub performs no scope
+     * narrowing. Return `false` from a subclass to reject a request.
+     */
+    acceptedScope(_client, _user, scope) {
+        return Promise.resolve(scope);
+    }
+    /** Mints a random opaque access token. */
+    generateAccessToken(_client, _user, _scope) {
+        return Promise.resolve(crypto.randomUUID());
+    }
+    /** Mints a random opaque refresh token. */
+    generateRefreshToken(_client, _user, _scope) {
+        return Promise.resolve(crypto.randomUUID());
+    }
+    /**
+     * Returns now plus the client's `accessTokenLifetime` override, falling back
+     * to {@linkcode accessTokenLifetime}.
+     */
+    accessTokenExpiresAt(client, _user, _scope) {
+        const lifetime = client.accessTokenLifetime ??
+            this.accessTokenLifetime;
+        return Promise.resolve(new Date(Date.now() + lifetime * 1000));
+    }
+    /**
+     * Returns now plus the client's `refreshTokenLifetime` override, falling
+     * back to {@linkcode refreshTokenLifetime}.
+     */
+    refreshTokenExpiresAt(client, _user, _scope) {
+        const lifetime = client.refreshTokenLifetime ??
+            this.refreshTokenLifetime;
+        return Promise.resolve(new Date(Date.now() + lifetime * 1000));
+    }
+    /**
+     * Returns the family anchor plus the client's `refreshTokenMaxLifetime`
+     * override, falling back to {@linkcode refreshTokenMaxLifetime}, or
+     * `undefined` when neither caps the family.
+     */
+    refreshTokenFamilyExpiresAt(client, _user, familyCreatedAt, _scope) {
+        const maxLifetime = client
+            .refreshTokenMaxLifetime ??
+            this.refreshTokenMaxLifetime;
+        return Promise.resolve(maxLifetime == null
+            ? undefined
+            : new Date(familyCreatedAt.getTime() + maxLifetime * 1000));
+    }
+    async #hydrate(stored, accessToken, refreshToken) {
+        const client = await this.#clientService.get(stored.clientId);
+        if (!client)
+            return undefined;
+        const user = stored.userId
+            ? await this.#userService.get(stored.userId)
+            : undefined;
+        if (stored.userId && !user)
+            return undefined;
+        const token = {
+            accessToken,
+            accessTokenExpiresAt: stored.accessTokenExpiresAt,
+            client,
+            user,
+            scope: stored.scope,
+            authenticationContext: snapshotAuthenticationContext(stored.authenticationContext),
+        };
+        if (stored.refreshTokenHash) {
+            return {
+                ...token,
+                refreshToken: refreshToken ?? "",
+                refreshTokenExpiresAt: stored.refreshTokenExpiresAt,
+                familyId: stored.familyId,
+                familyCreatedAt: stored.familyCreatedAt,
+            };
+        }
+        return token;
+    }
+    /**
+     * Resolves the token whose access token hashes to the given value, with its
+     * client and user rehydrated, or `undefined` when not found.
+     */
+    async getToken(accessToken) {
+        const stored = this.#tokensByAccessHash.get(await sha256Hash(accessToken));
+        if (!stored)
+            return undefined;
+        return this.#hydrate(stored, accessToken);
+    }
+    /**
+     * Resolves the refresh token whose value hashes to the given input, with its
+     * client and user rehydrated, or `undefined` when not found.
+     */
+    async getRefreshToken(refreshToken) {
+        const stored = this.#tokensByRefreshHash.get(await sha256Hash(refreshToken));
+        if (!stored)
+            return undefined;
+        return this.#hydrate(stored, "", refreshToken);
+    }
+    async save(token) {
+        const accessTokenHash = await sha256Hash(token.accessToken);
+        const stored = {
+            accessTokenHash,
+            accessTokenExpiresAt: token.accessTokenExpiresAt,
+            clientId: token.client.id,
+            userId: token.user?.id,
+            scope: token.scope,
+            authenticationContext: snapshotAuthenticationContext(token.authenticationContext),
+        };
+        if (token.code) {
+            stored.codeHash = await sha256Hash(token.code);
+            let bucket = this.#tokensByCodeHash.get(stored.codeHash);
+            if (!bucket) {
+                bucket = new Set();
+                this.#tokensByCodeHash.set(stored.codeHash, bucket);
+            }
+            bucket.add(accessTokenHash);
+        }
+        if ("refreshToken" in token) {
+            const rt = token;
+            stored.refreshTokenHash = await sha256Hash(rt.refreshToken);
+            stored.refreshTokenExpiresAt = rt.refreshTokenExpiresAt;
+            stored.familyId = rt.familyId;
+            stored.familyCreatedAt = rt.familyCreatedAt;
+            this.#tokensByRefreshHash.set(stored.refreshTokenHash, stored);
+        }
+        this.#tokensByAccessHash.set(accessTokenHash, stored);
+        return token;
+    }
+    async revoke(token, hint) {
+        if (typeof token !== "string") {
+            if ("refreshToken" in token && token.refreshToken) {
+                hint = "refresh_token";
+                token = token.refreshToken;
+            }
+            else {
+                token = token.accessToken;
+            }
+        }
+        const hashed = await sha256Hash(token);
+        const stored = hint === "refresh_token"
+            ? this.#tokensByRefreshHash.get(hashed)
+            : this.#tokensByAccessHash.get(hashed);
+        if (!stored)
+            return false;
+        this.#tokensByAccessHash.delete(stored.accessTokenHash);
+        if (stored.refreshTokenHash) {
+            this.#tombstone(stored.refreshTokenHash, stored);
+            this.#tokensByRefreshHash.delete(stored.refreshTokenHash);
+        }
+        return true;
+    }
+    #tombstone(refreshTokenHash, stored) {
+        this.#revokedByRefreshHash.set(refreshTokenHash, stored);
+    }
+    /**
+     * 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.
+     */
+    async getRevokedRefreshToken(refreshToken) {
+        const stored = this.#revokedByRefreshHash.get(await sha256Hash(refreshToken));
+        if (!stored)
+            return undefined;
+        return this.#hydrate(stored, "", refreshToken);
+    }
+    /**
+     * Revokes every live token in a rotation family (reuse detection response).
+     * Resolves `true` when at least one live token was removed.
+     */
+    revokeFamily(familyId) {
+        let revoked = false;
+        for (const [hash, stored] of this.#tokensByRefreshHash) {
+            if (stored.familyId === familyId) {
+                this.#tombstone(hash, stored);
+                this.#tokensByRefreshHash.delete(hash);
+                this.#tokensByAccessHash.delete(stored.accessTokenHash);
+                revoked = true;
+            }
+        }
+        for (const [hash, stored] of this.#tokensByAccessHash) {
+            if (stored.familyId === familyId) {
+                this.#tokensByAccessHash.delete(hash);
+                revoked = true;
+            }
+        }
+        return Promise.resolve(revoked);
+    }
+    /**
+     * Removes every token issued from the given authorization code, used when a
+     * code is replayed. Resolves `true` when at least one token was removed.
+     */
+    async revokeCode(code) {
+        const codeHash = await sha256Hash(code);
+        const tokenHashes = this.#tokensByCodeHash.get(codeHash);
+        if (!tokenHashes || tokenHashes.size === 0)
+            return false;
+        for (const accessTokenHash of tokenHashes) {
+            const stored = this.#tokensByAccessHash.get(accessTokenHash);
+            if (stored) {
+                this.#tokensByAccessHash.delete(accessTokenHash);
+                if (stored.refreshTokenHash) {
+                    this.#tokensByRefreshHash.delete(stored.refreshTokenHash);
+                }
+            }
+        }
+        this.#tokensByCodeHash.delete(codeHash);
+        return true;
+    }
+}
+/** In-memory `AuthorizationCodeServiceInterface` implementation. */
+export class MemoryAuthorizationCodeService {
+    /** Authorization-code lifetime in seconds applied by {@linkcode expiresAt}. */
+    lifetime;
+    #clientService;
+    #userService;
+    #codes = new Map();
+    /**
+     * Creates an empty authorization-code store.
+     *
+     * @param options Backing client/user services and optional code lifetime.
+     */
+    constructor(options) {
+        this.#clientService = options.clientService;
+        this.#userService = options.userService;
+        this.lifetime = options.lifetime ?? 600;
+    }
+    /** Mints a random opaque authorization code. */
+    generateCode(_client, _user, _scope) {
+        return Promise.resolve(crypto.randomUUID());
+    }
+    /** Returns now plus {@linkcode lifetime}. */
+    expiresAt(_client, _user, _scope) {
+        return Promise.resolve(new Date(Date.now() + this.lifetime * 1000));
+    }
+    /**
+     * 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.
+     */
+    async get(code) {
+        const stored = this.#codes.get(await sha256Hash(code));
+        if (!stored)
+            return undefined;
+        const client = await this.#clientService.get(stored.clientId);
+        const user = await this.#userService.get(stored.userId);
+        if (!client || !user)
+            return undefined;
+        return {
+            code,
+            expiresAt: stored.expiresAt,
+            client,
+            user,
+            scope: stored.scope,
+            redirectUri: stored.redirectUri,
+            challenge: stored.challenge,
+            challengeMethod: stored.challengeMethod,
+            nonce: stored.nonce,
+            authenticationContext: snapshotAuthenticationContext(stored.authenticationContext),
+        };
+    }
+    /**
+     * Persists an authorization code indexed by its hash, including the PKCE
+     * challenge and redirect URI. Returns the input unchanged.
+     */
+    async save(authorizationCode) {
+        const hashed = await sha256Hash(authorizationCode.code);
+        this.#codes.set(hashed, {
+            codeHash: hashed,
+            expiresAt: authorizationCode.expiresAt,
+            clientId: authorizationCode.client.id,
+            userId: authorizationCode.user.id,
+            scope: authorizationCode.scope,
+            redirectUri: authorizationCode.redirectUri,
+            challenge: authorizationCode.challenge,
+            challengeMethod: authorizationCode.challengeMethod,
+            nonce: authorizationCode.nonce,
+            authenticationContext: snapshotAuthenticationContext(authorizationCode.authenticationContext),
+        });
+        return authorizationCode;
+    }
+    /**
+     * Removes a code, accepting the record or its raw string. Resolves `true`
+     * when a code was removed, `false` otherwise.
+     */
+    async revoke(authorizationCode) {
+        const code = typeof authorizationCode === "string"
+            ? authorizationCode
+            : authorizationCode.code;
+        return this.#codes.delete(await sha256Hash(code));
+    }
+}
+/** In-memory `DeviceAuthorizationServiceInterface` implementation. */
+export class MemoryDeviceAuthorizationService {
+    /** Device-authorization lifetime in seconds applied by {@linkcode expiresAt}. */
+    lifetime;
+    /** Minimum seconds clients must wait between token-endpoint polls. */
+    interval;
+    #clientService;
+    #userService;
+    #byDeviceCode = new Map();
+    #byUserCode = new Map();
+    /**
+     * Creates an empty device-authorization store.
+     *
+     * @param options Backing client/user services and optional lifetime and
+     * polling interval.
+     */
+    constructor(options) {
+        this.#clientService = options.clientService;
+        this.#userService = options.userService;
+        this.lifetime = options.lifetime ?? 1800;
+        this.interval = options.interval ?? 5;
+    }
+    /** Mints a random opaque device code (polled by the device). */
+    generateDeviceCode(_client, _scope) {
+        return Promise.resolve(crypto.randomUUID());
+    }
+    /**
+     * Mints a short, human-enterable user code in `XXXX-XXXX` form drawn from an
+     * unambiguous alphabet (no vowels or look-alike digits).
+     */
+    generateUserCode(_client, _scope) {
+        const chars = "BCDFGHJKLMNPQRSTVWXYZ23456789";
+        let code = "";
+        const array = new Uint8Array(8);
+        crypto.getRandomValues(array);
+        for (let i = 0; i < 8; i++) {
+            code += chars[array[i] % chars.length];
+            if (i === 3)
+                code += "-";
+        }
+        return Promise.resolve(code);
+    }
+    /** Returns now plus {@linkcode lifetime}. */
+    expiresAt(_client, _scope) {
+        return Promise.resolve(new Date(Date.now() + this.lifetime * 1000));
+    }
+    async #hydrate(stored, deviceCode, userCode) {
+        const client = await this.#clientService.get(stored.clientId);
+        if (!client)
+            return undefined;
+        const user = stored.userId
+            ? await this.#userService.get(stored.userId)
+            : undefined;
+        if (stored.userId && !user)
+            return undefined;
+        return {
+            deviceCode,
+            userCode,
+            expiresAt: stored.expiresAt,
+            client,
+            scope: stored.scope,
+            interval: stored.interval,
+            authorized: stored.authorized,
+            user,
+            denied: stored.denied,
+            lastPolled: stored.lastPolled,
+        };
+    }
+    /**
+     * Persists a device authorization indexed by both its hashed device code and
+     * hashed user code. Returns the input unchanged.
+     */
+    async save(authorization) {
+        const deviceCodeHash = await sha256Hash(authorization.deviceCode);
+        const userCodeHash = await sha256Hash(authorization.userCode);
+        const stored = {
+            deviceCodeHash,
+            userCodeHash,
+            expiresAt: authorization.expiresAt,
+            clientId: authorization.client.id,
+            scope: authorization.scope,
+            interval: authorization.interval,
+            authorized: authorization.authorized,
+            userId: authorization.user?.id,
+            denied: authorization.denied,
+            lastPolled: authorization.lastPolled,
+        };
+        this.#byDeviceCode.set(deviceCodeHash, stored);
+        this.#byUserCode.set(userCodeHash, stored);
+        return authorization;
+    }
+    /**
+     * Resolves the authorization for a device code (the value the device polls
+     * with), client and user rehydrated, or `undefined` when not found.
+     */
+    async getByDeviceCode(deviceCode) {
+        const stored = this.#byDeviceCode.get(await sha256Hash(deviceCode));
+        if (!stored)
+            return undefined;
+        return this.#hydrate(stored, deviceCode, "");
+    }
+    /**
+     * Resolves the authorization for a user code (the value the user enters in a
+     * browser), client and user rehydrated, or `undefined` when not found.
+     */
+    async getByUserCode(userCode) {
+        const stored = this.#byUserCode.get(await sha256Hash(userCode));
+        if (!stored)
+            return undefined;
+        return this.#hydrate(stored, "", userCode);
+    }
+    async #findStored(authorization) {
+        if (authorization.deviceCode) {
+            const stored = this.#byDeviceCode.get(await sha256Hash(authorization.deviceCode));
+            if (stored)
+                return stored;
+        }
+        if (authorization.userCode) {
+            const stored = this.#byUserCode.get(await sha256Hash(authorization.userCode));
+            if (stored)
+                return stored;
+        }
+        return 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.
+     */
+    async approve(authorization, user, scope) {
+        const stored = await this.#findStored(authorization);
+        if (!stored) {
+            throw new Error("approve: device authorization not found");
+        }
+        stored.authorized = true;
+        stored.userId = user.id;
+        if (scope !== undefined)
+            stored.scope = scope;
+        return {
+            ...authorization,
+            authorized: true,
+            user,
+            scope: stored.scope,
+        };
+    }
+    /**
+     * Marks the authorization denied so a subsequent poll is rejected. Returns
+     * the updated record. Throws when the authorization is not stored.
+     */
+    async deny(authorization) {
+        const stored = await this.#findStored(authorization);
+        if (!stored) {
+            throw new Error("deny: device authorization not found");
+        }
+        stored.denied = true;
+        return { ...authorization, denied: true };
+    }
+    /**
+     * 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.
+     */
+    async updateLastPolled(authorization) {
+        const stored = await this.#findStored(authorization);
+        if (!stored) {
+            throw new Error("updateLastPolled: device authorization not found");
+        }
+        stored.lastPolled = new Date();
+        stored.interval = authorization.interval;
+        return { ...authorization, lastPolled: stored.lastPolled };
+    }
+    /**
+     * 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.
+     */
+    async revoke(authorization) {
+        if (typeof authorization === "string") {
+            const hashed = await sha256Hash(authorization);
+            const stored = this.#byDeviceCode.get(hashed);
+            if (!stored)
+                return false;
+            this.#byDeviceCode.delete(hashed);
+            this.#byUserCode.delete(stored.userCodeHash);
+            return true;
+        }
+        const stored = await this.#findStored(authorization);
+        if (!stored)
+            return false;
+        const deleted = this.#byDeviceCode.delete(stored.deviceCodeHash);
+        this.#byUserCode.delete(stored.userCodeHash);
+        return deleted;
+    }
+}