@udibo/oauth2 0.32.1 → 0.34.0

package/dist/adapters/hono/bff/_cookie-keys.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The AES-256-GCM keys the BFF's encrypted-cookie stores seal under.
+ *
+ * @module
+ */
+/** HKDF `info` label for `EncryptedCookieSessionStore`'s key. */
+export declare const SESSION_COOKIE_KEY_INFO = "udibo:oauth2:bff:session-cookie:v1";
+/** HKDF `info` label for `EncryptedCookieAuthRequestStorage`'s key. */
+export declare const AUTH_REQUEST_COOKIE_KEY_INFO = "udibo:oauth2:bff:auth-request-cookie:v1";
+/**
+ * Derives a cookie store's key from its configured secret with HKDF-SHA-256
+ * under the store's own `info` label, so one secret given to two stores yields
+ * independent keys.
+ *
+ * @throws {Error} When the secret is shorter than 16 bytes.
+ */
+export declare function deriveCookieKey(secret: string | Uint8Array, info: string): Promise<CryptoKey>;

package/dist/adapters/hono/bff/_cookie-keys.js

@@ -0,0 +1,25 @@
+/**
+ * The AES-256-GCM keys the BFF's encrypted-cookie stores seal under.
+ *
+ * @module
+ */
+import { deriveSealKey } from "../../../utils/crypto.js";
+/** HKDF `info` label for `EncryptedCookieSessionStore`'s key. */
+export const SESSION_COOKIE_KEY_INFO = "udibo:oauth2:bff:session-cookie:v1";
+/** HKDF `info` label for `EncryptedCookieAuthRequestStorage`'s key. */
+export const AUTH_REQUEST_COOKIE_KEY_INFO = "udibo:oauth2:bff:auth-request-cookie:v1";
+const MIN_SECRET_BYTES = 16;
+/**
+ * Derives a cookie store's key from its configured secret with HKDF-SHA-256
+ * under the store's own `info` label, so one secret given to two stores yields
+ * independent keys.
+ *
+ * @throws {Error} When the secret is shorter than 16 bytes.
+ */
+export async function deriveCookieKey(secret, info) {
+    const bytes = typeof secret === "string" ? new TextEncoder().encode(secret) : secret;
+    if (bytes.byteLength < MIN_SECRET_BYTES) {
+        throw new Error("secret must be at least 16 bytes; 32+ bytes of entropy is recommended.");
+    }
+    return await deriveSealKey(bytes, info);
+}

package/dist/adapters/hono/bff/auth-request-store.d.ts

@@ -11,10 +11,10 @@
  * caller chooses.
  *
  * {@link EncryptedCookieAuthRequestStorage} carries the record in an encrypted
- * cookie instead (AES-GCM under a server-held secret, the same construction
- * {@link EncryptedCookieSessionStore} uses), so no server-side storage is
- * involved and any instance can complete the flow. Apps that already have a
- * database can implement {@link AuthRequestStorage} against it instead.
+ * cookie instead (AES-GCM under a key derived from a server-held secret), so no
+ * server-side storage is involved and any instance can complete the flow. Apps
+ * that already have a database can implement {@link AuthRequestStorage} against
+ * it instead.
  *
  * **Which storage you pick is a reliability decision, not a security one.**
  * Server-side storage on its own says a `state` is pending somewhere — never
@@ -84,6 +84,13 @@ export interface EncryptedCookieAuthRequestStorageOptions {
     /**
      * Secret the AES-256 key is derived from; at least 32 bytes. Reuse the
      * secret across instances so any of them can unseal a cookie another sealed.
+     *
+     * Give each store instance and each app a secret of its own. Nothing in a
+     * sealed cookie binds it to the app or store instance that sealed it, so two
+     * apps that share a secret can open each other's pending sign-ins. Sharing
+     * one with {@link EncryptedCookieSessionStore} does not let either store open
+     * the other's cookies: each derives its key with HKDF-SHA-256 under its own
+     * label.
      */
     secret: string;
     /** Cookie attribute overrides. */
@@ -138,8 +145,12 @@ export interface AuthRequestStorageFactory {
  * ```ts
  * const bff = new HonoBff({
  *   client,
- *   sessionStore: new EncryptedCookieSessionStore({ secret }),
- *   authRequestStorage: new EncryptedCookieAuthRequestStorage({ secret }),
+ *   sessionStore: new EncryptedCookieSessionStore({
+ *     secret: process.env.SESSION_SECRET!,
+ *   }),
+ *   authRequestStorage: new EncryptedCookieAuthRequestStorage({
+ *     secret: process.env.AUTH_REQUEST_SECRET!,
+ *   }),
  * });
  * ```
  */
@@ -171,7 +182,7 @@ export declare class EncryptedCookieAuthRequestStorage implements AuthRequestSto
  * import { encryptedCookieAuthRequestStorage } from "@udibo/oauth2/hono/bff";
  *
  * const authRequestStorage = encryptedCookieAuthRequestStorage({
- *   secret: process.env.SESSION_SECRET!,
+ *   secret: process.env.AUTH_REQUEST_SECRET!,
  * });
  * ```
  */

package/dist/adapters/hono/bff/auth-request-store.js

@@ -11,10 +11,10 @@
  * caller chooses.
  *
  * {@link EncryptedCookieAuthRequestStorage} carries the record in an encrypted
- * cookie instead (AES-GCM under a server-held secret, the same construction
- * {@link EncryptedCookieSessionStore} uses), so no server-side storage is
- * involved and any instance can complete the flow. Apps that already have a
- * database can implement {@link AuthRequestStorage} against it instead.
+ * cookie instead (AES-GCM under a key derived from a server-held secret), so no
+ * server-side storage is involved and any instance can complete the flow. Apps
+ * that already have a database can implement {@link AuthRequestStorage} against
+ * it instead.
  *
  * **Which storage you pick is a reliability decision, not a security one.**
  * Server-side storage on its own says a `state` is pending somewhere — never
@@ -29,13 +29,17 @@
  */
 import { deleteCookie, getCookie, setCookie } from "hono/cookie";
 import { MemoryAuthRequestStorage, } from "../../../client/mod.js";
-import { deriveAesKey, sealJson, unsealJson } from "../../../utils/crypto.js";
+import { sealJson, unsealJson } from "../../../utils/crypto.js";
+import { AUTH_REQUEST_COOKIE_KEY_INFO, deriveCookieKey, } from "./_cookie-keys.js";
 import { resolveCookieName, resolvePrefixConstrainedAttributes, } from "./cookie-prefix.js";
 const BASE_NAME = "oauth2_auth_request";
 const DEFAULT_TTL_MS = 10 * 60 * 1000;
 const DEFAULT_MAX_PENDING = 3;
 // RFC 6265 §6.1 only guarantees 4096 bytes per cookie, attributes included.
 const MAX_COOKIE_NAME_VALUE_BYTES = 3900;
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function cookieAttributes(options, maxAgeSeconds) {
     const { secure, path, domain } = resolvePrefixConstrainedAttributes(options);
     return {
@@ -65,8 +69,12 @@ function cookieAttributes(options, maxAgeSeconds) {
  * ```ts
  * const bff = new HonoBff({
  *   client,
- *   sessionStore: new EncryptedCookieSessionStore({ secret }),
- *   authRequestStorage: new EncryptedCookieAuthRequestStorage({ secret }),
+ *   sessionStore: new EncryptedCookieSessionStore({
+ *     secret: process.env.SESSION_SECRET!,
+ *   }),
+ *   authRequestStorage: new EncryptedCookieAuthRequestStorage({
+ *     secret: process.env.AUTH_REQUEST_SECRET!,
+ *   }),
  * });
  * ```
  */
@@ -107,17 +115,19 @@ export class EncryptedCookieAuthRequestStorage {
         }
     }
     #key() {
-        return (this.#keyPromise ??= deriveAesKey(this.#secret));
+        return (this.#keyPromise ??= deriveCookieKey(this.#secret, AUTH_REQUEST_COOKIE_KEY_INFO));
     }
     async #read(c) {
         const cookieValue = getCookie(c, this.#name);
         if (!cookieValue)
             return {};
         const pending = await unsealJson(await this.#key(), cookieValue);
-        if (!pending)
+        if (!isObject(pending))
             return {};
         const cutoff = Date.now() - this.#ttlMs;
-        return Object.fromEntries(Object.entries(pending).filter(([, record]) => record.createdAt > cutoff));
+        return Object.fromEntries(Object.entries(pending).filter((entry) => isObject(entry[1]) &&
+            typeof entry[1].createdAt === "number" &&
+            entry[1].createdAt > cutoff));
     }
     async #write(c, pending, keep) {
         const entries = Object.entries(pending)
@@ -143,7 +153,10 @@ export class EncryptedCookieAuthRequestStorage {
     /** Returns the storage bound to `c`, for the duration of that request. */
     forRequest(c) {
         return {
-            get: async (state) => (await this.#read(c))[state] ?? null,
+            get: async (state) => {
+                const pending = await this.#read(c);
+                return Object.hasOwn(pending, state) ? pending[state] : null;
+            },
             set: async (state, value) => {
                 const pending = await this.#read(c);
                 pending[state] = value;
@@ -168,7 +181,7 @@ export class EncryptedCookieAuthRequestStorage {
  * import { encryptedCookieAuthRequestStorage } from "@udibo/oauth2/hono/bff";
  *
  * const authRequestStorage = encryptedCookieAuthRequestStorage({
- *   secret: process.env.SESSION_SECRET!,
+ *   secret: process.env.AUTH_REQUEST_SECRET!,
  * });
  * ```
  */

package/dist/adapters/hono/bff/session-store.d.ts

@@ -109,7 +109,8 @@ export interface RefreshLockStore {
      *   longer overwrite or end the session that instance refreshed. A store
      *   that calls `refresh()` with no lease still works, but a lock that
      *   expires mid-refresh then lets the former holder's write or sign-out
-     *   land on top of the new holder's.
+     *   land on top of the new holder's. `runSessionStoreContractTests` fails
+     *   such a store unless its options declare that the lock never expires.
      * - Reject when the lock cannot be acquired within a bound you choose.
      *   `HonoBff` then answers `502` `temporarily_unavailable` and keeps the
      *   session.
@@ -282,6 +283,13 @@ export interface EncryptedCookieSessionStoreOptions {
      * Server-held secret(s) used to derive the AES-256 key(s). Each must have at
      * least 32 bytes of entropy; pass a base64 / hex string or raw bytes.
      *
+     * Give each store instance and each app a secret of its own. Nothing in a
+     * sealed cookie binds it to the app or store instance that sealed it, so two
+     * apps that share a secret can open each other's session cookies. Sharing one
+     * with `EncryptedCookieAuthRequestStorage` does not let either store open the
+     * other's cookies: each derives its key with HKDF-SHA-256 under its own
+     * label.
+     *
      * Pass an **ordered list** to rotate the secret without signing everyone out:
      * the **first** entry is current — every cookie is sealed under it — and
      * `read` tries each entry in turn, so a cookie sealed under a still-listed
@@ -307,10 +315,6 @@ export interface EncryptedCookieSessionStoreOptions {
      * `update` re-seals with a fresh stamp, so this is an **inactivity** window
      * for a session the BFF keeps refreshing. Must be a positive number of
      * milliseconds.
-     *
-     * The store stamps each cookie with a seal time at `create`/`update`; a
-     * cookie without that stamp is aged from its `updatedAt` instead, so it is
-     * bounded too.
      */
     maxAgeMs?: number;
 }
@@ -321,6 +325,11 @@ export interface EncryptedCookieSessionStoreOptions {
  * Security notes:
  * - Each secret must have at least 256 bits of entropy. A weak secret defeats
  *   the confidentiality of the cookie.
+ * - The key is derived from the secret with HKDF-SHA-256 under a label of this
+ *   store's own, so a cookie sealed by another store under the same secret
+ *   does not open here.
+ * - `read` accepts only what `create` sealed: a cookie that is malformed,
+ *   foreign, or the wrong shape reads as `null`.
  * - AES-GCM provides authenticated encryption; tampered cookies fail `read`
  *   (returns `null`).
  * - `destroy` is a no-op on the server — the cookie must be cleared in the
@@ -365,8 +374,8 @@ export declare class EncryptedCookieSessionStore implements SessionStore, Bounde
     create(data: SessionData): Promise<string>;
     /**
      * Decrypts the cookie value, trying each configured secret in turn. Returns
-     * `null` if it is tampered, malformed, sealed with an unknown secret, or
-     * sealed longer ago than
+     * `null` if it is tampered, malformed, sealed with an unknown secret or by
+     * another store, not in the shape `create` seals, or sealed longer ago than
      * {@linkcode EncryptedCookieSessionStoreOptions.maxAgeMs}.
      */
     read(cookieValue: string): Promise<SessionData | null>;

package/dist/adapters/hono/bff/session-store.js

@@ -24,7 +24,8 @@
  * @module
  */
 import { InvalidGrantError } from "../../../errors.js";
-import { deriveAesKey, sealJson, unsealJson } from "../../../utils/crypto.js";
+import { sealJson, unsealJson } from "../../../utils/crypto.js";
+import { deriveCookieKey, SESSION_COOKIE_KEY_INFO } from "./_cookie-keys.js";
 /** Whether a store implements the {@link BackchannelLogoutStore} capability. */
 export function supportsBackchannelLogout(store) {
     return (typeof store.destroyByLogout ===
@@ -233,6 +234,11 @@ function isSealedSession(value) {
  * Security notes:
  * - Each secret must have at least 256 bits of entropy. A weak secret defeats
  *   the confidentiality of the cookie.
+ * - The key is derived from the secret with HKDF-SHA-256 under a label of this
+ *   store's own, so a cookie sealed by another store under the same secret
+ *   does not open here.
+ * - `read` accepts only what `create` sealed: a cookie that is malformed,
+ *   foreign, or the wrong shape reads as `null`.
  * - AES-GCM provides authenticated encryption; tampered cookies fail `read`
  *   (returns `null`).
  * - `destroy` is a no-op on the server — the cookie must be cleared in the
@@ -294,7 +300,7 @@ export class EncryptedCookieSessionStore {
         return this.#maxAgeMs;
     }
     #key(index) {
-        return (this.#keyPromises[index] ??= deriveAesKey(this.#secrets[index]));
+        return (this.#keyPromises[index] ??= deriveCookieKey(this.#secrets[index], SESSION_COOKIE_KEY_INFO));
     }
     /** Encrypts the session into the cookie value under the current secret; there is no server-side record. */
     async create(data) {
@@ -303,8 +309,8 @@ export class EncryptedCookieSessionStore {
     }
     /**
      * Decrypts the cookie value, trying each configured secret in turn. Returns
-     * `null` if it is tampered, malformed, sealed with an unknown secret, or
-     * sealed longer ago than
+     * `null` if it is tampered, malformed, sealed with an unknown secret or by
+     * another store, not in the shape `create` seals, or sealed longer ago than
      * {@linkcode EncryptedCookieSessionStoreOptions.maxAgeMs}.
      */
     async read(cookieValue) {
@@ -312,13 +318,9 @@ export class EncryptedCookieSessionStore {
             const unsealed = await unsealJson(await this.#key(index), cookieValue);
             if (unsealed === null)
                 continue;
-            if (isSealedSession(unsealed)) {
-                return this.#isExpired(unsealed.issuedAt) ? null : unsealed.data;
-            }
-            const legacy = unsealed;
-            return this.#isExpired(legacy.updatedAt ?? legacy.createdAt)
-                ? null
-                : legacy;
+            if (!isSealedSession(unsealed))
+                return null;
+            return this.#isExpired(unsealed.issuedAt) ? null : unsealed.data;
         }
         return null;
     }

package/dist/adapters/hono/bff/testing.d.ts

@@ -165,6 +165,20 @@ export interface SessionStoreContractOptions {
      * supplying this factory.
      */
     makeBoundedStore?(maxAgeMs: number): Promise<SessionStore> | SessionStore;
+    /**
+     * Set to `true` when the store's refresh lock never expires, so a holder
+     * keeps it until its `refresh` settles, as `MemorySessionStore` does by
+     * default. The suite then skips the lease checks for a store whose
+     * `withRefreshLock` passes no {@link RefreshLease}, instead of failing it.
+     *
+     * Without a lease, nothing stops a holder that lost an expiring lock from
+     * writing or destroying the session, and the suite cannot tell a lock that
+     * never expires from one that does. Declare it only when no holder can lose
+     * the lock while its refresh runs, as when the lock lives in the one process
+     * that runs every refresh. Then a holder that hangs holds the session's
+     * refresh until it settles. Defaults to `false`.
+     */
+    refreshLockNeverExpires?: boolean;
 }
 /**
  * Contract test suite for {@link SessionStore} implementations. Registers
@@ -175,12 +189,13 @@ export interface SessionStoreContractOptions {
  *
  * A store that implements `withRefreshLock` ({@link RefreshLockStore}) also
  * runs the lock checks; they are skipped for a store without it. The lease
- * checks ({@link RefreshLease}) are skipped for a store whose
- * `withRefreshLock` passes no lease. They prove that a lease stops acting once
- * its call releases the lock or another call holds it, not that it stops
- * when the lock expires: expire a lease in a test of your own for that. They
- * use one store object, so they prove the lock's behavior, not that separate
- * instances share it: point two store objects at one backend in a test of
- * your own for that.
+ * checks ({@link RefreshLease}) fail a store whose `withRefreshLock` passes no
+ * lease, unless the options declare that its lock never expires
+ * ({@linkcode SessionStoreContractOptions.refreshLockNeverExpires}). They
+ * prove that a lease stops acting once its call releases the lock or another
+ * call holds it, not that it stops when the lock expires: expire a lease in a
+ * test of your own for that. They use one store object, so they prove the
+ * lock's behavior, not that separate instances share it: point two store
+ * objects at one backend in a test of your own for that.
  */
 export declare function runSessionStoreContractTests(options: SessionStoreContractOptions): void;

package/dist/adapters/hono/bff/testing.js

@@ -204,17 +204,19 @@ async function rejection(promise) {
  *
  * A store that implements `withRefreshLock` ({@link RefreshLockStore}) also
  * runs the lock checks; they are skipped for a store without it. The lease
- * checks ({@link RefreshLease}) are skipped for a store whose
- * `withRefreshLock` passes no lease. They prove that a lease stops acting once
- * its call releases the lock or another call holds it, not that it stops
- * when the lock expires: expire a lease in a test of your own for that. They
- * use one store object, so they prove the lock's behavior, not that separate
- * instances share it: point two store objects at one backend in a test of
- * your own for that.
+ * checks ({@link RefreshLease}) fail a store whose `withRefreshLock` passes no
+ * lease, unless the options declare that its lock never expires
+ * ({@linkcode SessionStoreContractOptions.refreshLockNeverExpires}). They
+ * prove that a lease stops acting once its call releases the lock or another
+ * call holds it, not that it stops when the lock expires: expire a lease in a
+ * test of your own for that. They use one store object, so they prove the
+ * lock's behavior, not that separate instances share it: point two store
+ * objects at one backend in a test of your own for that.
  */
 export function runSessionStoreContractTests(options) {
     const destroyClearsRead = options.destroyClearsRead ?? true;
     const makeBoundedStore = options.makeBoundedStore;
+    const refreshLockNeverExpires = options.refreshLockNeverExpires ?? false;
     describe(options.describeName ?? "SessionStore contract", () => {
         let store;
         beforeEach(async () => {
@@ -375,9 +377,13 @@ export function runSessionStoreContractTests(options) {
         });
         async function leaseOf(locking, value, skip) {
             const lease = await locking.withRefreshLock(value, (given) => Promise.resolve(given));
-            skip(lease === undefined, "withRefreshLock passes the refresh no lease, so a holder that lost " +
-                "the lock can still write and destroy the session");
-            return required(lease);
+            skip(lease === undefined && refreshLockNeverExpires, "withRefreshLock passes the refresh no lease, and the store declares " +
+                "that its lock never expires");
+            assert(lease !== undefined, "withRefreshLock passed the refresh no lease, so a holder that " +
+                "stalls past an expiring lock can still write and destroy the " +
+                "session another holder refreshed. Pass a RefreshLease, or set " +
+                "refreshLockNeverExpires: true if the lock never expires.");
+            return lease;
         }
         function refreshedSession() {
             return {

package/dist/testing/contract/token-rotation.d.ts

@@ -82,6 +82,13 @@ export interface TokenRotationContractOptions<C extends ClientInterface, U exten
      * longer to reach the lock they wait on.
      */
     blockedAfterMs?: number;
+    /**
+     * Returns a new rotation-family id the store accepts as a
+     * {@linkcode RefreshToken.familyId}, distinct on every call. Each case calls
+     * it for the two families it uses. Set it when the store keeps family ids in
+     * a format other than a UUID. Defaults to `crypto.randomUUID()`.
+     */
+    makeFamilyId?(): string;
     /** Overrides the name passed to the outer `describe` block. */
     describeName?: string;
 }

package/dist/testing/contract/token-rotation.js

@@ -55,6 +55,7 @@ export function runTokenRotationContractTests(options) {
     const makeClient = options.makeClient ?? defaultMakeClient;
     const pausable = options.rotateAwaitsBarrier ?? true;
     const blockedAfterMs = options.blockedAfterMs ?? 100;
+    const makeFamilyId = options.makeFamilyId ?? (() => crypto.randomUUID());
     describe(options.describeName ?? "TokenServiceInterface.rotate contract", () => {
         let clientService;
         let tokenService;
@@ -75,8 +76,8 @@ export function runTokenRotationContractTests(options) {
         };
         beforeEach(async () => {
             armed = undefined;
-            family = crypto.randomUUID();
-            otherFamily = crypto.randomUUID();
+            family = makeFamilyId();
+            otherFamily = makeFamilyId();
             const services = await options.makeServices(barriers);
             clientService = services.clientService;
             tokenService = services.tokenService;

package/dist/testing/contract/token.d.ts

@@ -46,6 +46,25 @@ export interface TokenServiceContractOptions<C extends ClientInterface, U extend
     makeClient?(seq: number): C;
     /** Builds a scope from its string value. Defaults to a {@linkcode BasicScope}. */
     makeScope?(value: string): S;
+    /**
+     * A scope value the service accepts for the fixture client. The
+     * `acceptedScope` case with a user requests it and expects it back
+     * unchanged; the case with no user requests it and expects it not to be
+     * refused. Set it when `acceptedScope` refuses scopes outside a fixed
+     * vocabulary, for example `"openid"`. Defaults to `"read"`.
+     */
+    supportedScope?: string;
+    /**
+     * Returns a new rotation-family id the store accepts as a
+     * {@linkcode RefreshToken.familyId}, distinct on every call. The family cases
+     * call it for each family they create and for a family that was never
+     * issued, so each case sees only its own families. Users, clients and the
+     * authorization-code and unknown-token probes keep fixed values, so a store
+     * that keeps state across cases still needs `makeServices` to isolate those.
+     * Set it when the store keeps family ids in a format other than a UUID.
+     * Defaults to `crypto.randomUUID()`.
+     */
+    makeFamilyId?(): string;
     /**
      * Set to `false` when the service deliberately omits the optional
      * reuse-detection pair, {@linkcode TokenServiceInterface.getRevokedRefreshToken}

package/dist/testing/contract/token.js

@@ -26,11 +26,14 @@ const defaultMakeClient = (seq) => ({
     grants: ["authorization_code", "refresh_token"],
 });
 const defaultMakeScope = (value) => new BasicScope(value);
+const defaultMakeFamilyId = () => crypto.randomUUID();
 /** Runs the {@link TokenServiceInterface} contract suite. */
 export function runTokenServiceContractTests(options) {
     const makeUser = options.makeUser ?? defaultMakeUser;
     const makeClient = options.makeClient ?? defaultMakeClient;
     const makeScope = options.makeScope ?? defaultMakeScope;
+    const supportedScope = options.supportedScope ?? "read";
+    const makeFamilyId = options.makeFamilyId ?? defaultMakeFamilyId;
     const expectReuseDetection = options.refreshTokenReuseDetection ?? true;
     describe(options.describeName ?? "TokenServiceInterface contract", () => {
         let userService;
@@ -66,9 +69,9 @@ export function runTokenServiceContractTests(options) {
         });
         describe("acceptedScope", () => {
             it("returns the requested scope unchanged for the simple case", async () => {
-                const requested = makeScope("read");
+                const requested = makeScope(supportedScope);
                 const result = await tokenService.acceptedScope(client, user, requested);
-                expect(result?.toString()).toStrictEqual("read");
+                expect(result?.toString()).toStrictEqual(supportedScope);
             });
         });
         describe("save + getToken", () => {
@@ -97,7 +100,7 @@ export function runTokenServiceContractTests(options) {
                 expect(typeof accessToken).toStrictEqual("string");
             });
             it("accepts scope for a client with no user", async () => {
-                const result = await tokenService.acceptedScope(client, undefined, makeScope("read"));
+                const result = await tokenService.acceptedScope(client, undefined, makeScope(supportedScope));
                 assert(result !== false, "scope must not be rejected for lack of a user");
             });
             it("dates the expiry of an access token with no user", async () => {
@@ -214,8 +217,12 @@ export function runTokenServiceContractTests(options) {
         });
         if (expectReuseDetection) {
             describe("refresh-token rotation family", () => {
-                const FAMILY = "family-1";
-                const OTHER_FAMILY = "family-2";
+                let family;
+                let otherFamily;
+                beforeEach(() => {
+                    family = makeFamilyId();
+                    otherFamily = makeFamilyId();
+                });
                 async function familyMember(familyId, refreshTokenExpiresAt = new Date(Date.now() + 600_000)) {
                     const accessToken = await tokenService.generateAccessToken(client, user);
                     const refreshToken = (await tokenService.generateRefreshToken(client, user));
@@ -244,16 +251,16 @@ export function runTokenServiceContractTests(options) {
                         "`refreshTokenReuseDetection: false` to record the gap.");
                 });
                 it("keeps a rotated-out refresh token findable, with its family", async () => {
-                    const token = await saveFamilyMember(FAMILY);
+                    const token = await saveFamilyMember(family);
                     await tokenService.revoke(token.refreshToken, "refresh_token");
                     expect(await tokenService.getRefreshToken(token.refreshToken), "a rotated-out token must no longer refresh").toBe(undefined);
                     const revoked = await tokenService.getRevokedRefreshToken(token.refreshToken);
                     assert(revoked !== undefined, "a revoked refresh token must stay findable — deleting the row " +
                         "is what turns a replay into an ordinary unknown token");
-                    expect(revoked.familyId).toBe(FAMILY);
+                    expect(revoked.familyId).toBe(family);
                 });
                 it("does not report a live refresh token as revoked", async () => {
-                    const token = await saveFamilyMember(FAMILY);
+                    const token = await saveFamilyMember(family);
                     expect(await tokenService.getRevokedRefreshToken(token.refreshToken), "reporting a live token as revoked turns every legitimate " +
                         "refresh into a detected replay").toBe(undefined);
                 });
@@ -261,28 +268,52 @@ export function runTokenServiceContractTests(options) {
                     expect(await tokenService.getRevokedRefreshToken("never-issued")).toBe(undefined);
                 });
                 it("revokes every live member of a replayed token's family", async () => {
-                    const first = await saveFamilyMember(FAMILY);
-                    const second = await saveFamilyMember(FAMILY);
-                    expect(await tokenService.revokeFamily(FAMILY)).toBe(true);
+                    const first = await saveFamilyMember(family);
+                    const second = await saveFamilyMember(family);
+                    expect(await tokenService.revokeFamily(family)).toBe(true);
                     expect(await tokenService.getRefreshToken(first.refreshToken)).toBe(undefined);
                     expect(await tokenService.getRefreshToken(second.refreshToken)).toBe(undefined);
                     expect(await tokenService.getToken(second.accessToken), "the family's access tokens die with it — leaving them live " +
                         "keeps the thief's session alive for their remaining lifetime").toBe(undefined);
                 });
                 it("leaves other families untouched", async () => {
-                    const mine = await saveFamilyMember(FAMILY);
-                    const theirs = await saveFamilyMember(OTHER_FAMILY);
-                    await tokenService.revokeFamily(FAMILY);
+                    const mine = await saveFamilyMember(family);
+                    const theirs = await saveFamilyMember(otherFamily);
+                    await tokenService.revokeFamily(family);
                     expect(await tokenService.getRefreshToken(mine.refreshToken)).toBe(undefined);
                     assert((await tokenService.getRefreshToken(theirs.refreshToken)) !==
                         undefined, "one compromised family must not sign every other session out");
                 });
                 it("returns false when the family has no live tokens", async () => {
-                    expect(await tokenService.revokeFamily("never-issued")).toBe(false);
+                    expect(await tokenService.revokeFamily(makeFamilyId())).toBe(false);
+                });
+                it("keeps a revoked family revoked: a successor saved after revokeFamily is not live", async ({ skip, }) => {
+                    skip(typeof tokenService.rotate === "function", "the service implements rotate, so the refresh grant never saves " +
+                        "a successor separately; runTokenRotationContractTests checks " +
+                        "revokeFamily against rotate");
+                    const parent = await saveFamilyMember(family);
+                    const successor = await familyMember(family);
+                    const claimed = tokenService.revokeRotated
+                        ? await tokenService.revokeRotated(parent)
+                        : await tokenService.revoke(parent);
+                    expect(claimed).toBe(true);
+                    expect(await tokenService.getRefreshToken(parent.refreshToken), "the claim spends the presented refresh token").toBe(undefined);
+                    await tokenService.revokeFamily(family);
+                    await tokenService.save(successor);
+                    expect(await tokenService.getRefreshToken(successor.refreshToken), "a successor saved after its family was revoked must be stored " +
+                        "already revoked: the refresh grant claims a token and saves " +
+                        "its successor in two calls, and a revokeFamily that lands " +
+                        "between them otherwise leaves the successor live").toBe(undefined);
+                    expect(await tokenService.getToken(successor.accessToken), "a successor saved after its family was revoked must be stored " +
+                        "already revoked, its access token included").toBe(undefined);
+                    if (tokenService.hasLiveRefreshToken) {
+                        expect(await tokenService.hasLiveRefreshToken(family), "a successor saved after its family was revoked must be stored " +
+                            "already revoked, so the family has no live member").toBe(false);
+                    }
                 });
                 it("stamps a token revokeRotated revoked with its rotation time", async ({ skip, }) => {
                     skip(typeof tokenService.revokeRotated !== "function", "the service does not implement revokeRotated");
-                    const token = await saveFamilyMember(FAMILY);
+                    const token = await saveFamilyMember(family);
                     const before = Date.now();
                     expect(await tokenService.revokeRotated(token)).toBe(true);
                     const revoked = await tokenService.getRevokedRefreshToken(token.refreshToken);
@@ -294,17 +325,17 @@ export function runTokenServiceContractTests(options) {
                 });
                 it("rotates in one call: the parent is spent and stamped, the successor live", async ({ skip, }) => {
                     skip(typeof tokenService.rotate !== "function", "the service does not implement rotate");
-                    const parent = await saveFamilyMember(FAMILY);
-                    const next = await familyMember(FAMILY);
+                    const parent = await saveFamilyMember(family);
+                    const next = await familyMember(family);
                     const before = Date.now();
                     const rotated = await tokenService.rotate(parent, next);
                     expect(rotated?.refreshToken).toBe(next.refreshToken);
-                    expect((await tokenService.getRefreshToken(next.refreshToken))?.familyId).toBe(FAMILY);
+                    expect((await tokenService.getRefreshToken(next.refreshToken))?.familyId).toBe(family);
                     expect(await tokenService.getToken(next.accessToken)).not.toBe(undefined);
                     expect(await tokenService.getRefreshToken(parent.refreshToken)).toBe(undefined);
                     expect(await tokenService.getToken(parent.accessToken), "rotation ends the parent's access token, as revokeRotated does").toBe(undefined);
                     const tombstone = await tokenService.getRevokedRefreshToken(parent.refreshToken);
-                    expect(tombstone?.familyId).toBe(FAMILY);
+                    expect(tombstone?.familyId).toBe(family);
                     assert(tombstone?.rotatedAt instanceof Date &&
                         tombstone.rotatedAt.getTime() >= before - 1000 &&
                         tombstone.rotatedAt.getTime() <= Date.now() + 1000, "rotate must stamp rotatedAt as revokeRotated does, or the " +
@@ -313,11 +344,11 @@ export function runTokenServiceContractTests(options) {
                 });
                 it("refuses to rotate a refresh token that is no longer live, persisting nothing", async ({ skip, }) => {
                     skip(typeof tokenService.rotate !== "function", "the service does not implement rotate");
-                    const parent = await saveFamilyMember(FAMILY);
-                    const first = await familyMember(FAMILY);
-                    const second = await familyMember(FAMILY);
-                    const revokedParent = await saveFamilyMember(FAMILY);
-                    const third = await familyMember(FAMILY);
+                    const parent = await saveFamilyMember(family);
+                    const first = await familyMember(family);
+                    const second = await familyMember(family);
+                    const revokedParent = await saveFamilyMember(family);
+                    const third = await familyMember(family);
                     await tokenService.revoke(revokedParent.refreshToken, "refresh_token");
                     expect(await tokenService.rotate(parent, first)).not.toBe(undefined);
                     expect(await tokenService.rotate(parent, second), "a refresh token is claimed once").toBe(undefined);
@@ -330,12 +361,12 @@ export function runTokenServiceContractTests(options) {
                 });
                 it("finds a rotated-out token's family, so revoking it ends the live successor", async ({ skip, }) => {
                     skip(typeof tokenService.revokeRotated !== "function", "the service does not implement revokeRotated");
-                    const rotatedOut = await saveFamilyMember(FAMILY);
+                    const rotatedOut = await saveFamilyMember(family);
                     expect(await tokenService.revokeRotated(rotatedOut)).toBe(true);
-                    const successor = await saveFamilyMember(FAMILY);
-                    const unrelated = await saveFamilyMember(OTHER_FAMILY);
+                    const successor = await saveFamilyMember(family);
+                    const unrelated = await saveFamilyMember(otherFamily);
                     const tombstone = await tokenService.getRevokedRefreshToken(rotatedOut.refreshToken);
-                    assert(tombstone?.familyId === FAMILY && tombstone.rotatedAt, "the revocation endpoint finds the family to end from the " +
+                    assert(tombstone?.familyId === family && tombstone.rotatedAt, "the revocation endpoint finds the family to end from the " +
                         "rotated-out token's record; without its familyId and " +
                         "rotatedAt, a sign-out racing a refresh leaves the successor live");
                     expect(tombstone.client.id.toString(), "the endpoint revokes the family only for the client the token " +
@@ -347,7 +378,7 @@ export function runTokenServiceContractTests(options) {
                         undefined);
                 });
                 it("leaves rotatedAt unset on a token revoked other than by rotation", async () => {
-                    const token = await saveFamilyMember(FAMILY);
+                    const token = await saveFamilyMember(family);
                     await tokenService.revoke(token.refreshToken, "refresh_token");
                     const revoked = await tokenService.getRevokedRefreshToken(token.refreshToken);
                     expect(revoked?.rotatedAt, "a revoked token that looks rotated gets the replay grace a " +
@@ -355,26 +386,26 @@ export function runTokenServiceContractTests(options) {
                 });
                 it("reports whether a family still has a live refresh token", async ({ skip, }) => {
                     skip(typeof tokenService.hasLiveRefreshToken !== "function", "the service does not implement hasLiveRefreshToken");
-                    const token = await saveFamilyMember(FAMILY);
-                    await saveFamilyMember(OTHER_FAMILY);
-                    expect(await tokenService.hasLiveRefreshToken(FAMILY)).toBe(true);
+                    const token = await saveFamilyMember(family);
+                    await saveFamilyMember(otherFamily);
+                    expect(await tokenService.hasLiveRefreshToken(family)).toBe(true);
                     await tokenService.revoke(token.refreshToken, "refresh_token");
-                    expect(await tokenService.hasLiveRefreshToken(FAMILY), "a family whose last token was revoked has no successor to protect").toBe(false);
-                    expect(await tokenService.hasLiveRefreshToken(OTHER_FAMILY)).toBe(true);
-                    expect(await tokenService.hasLiveRefreshToken("never-issued")).toBe(false);
+                    expect(await tokenService.hasLiveRefreshToken(family), "a family whose last token was revoked has no successor to protect").toBe(false);
+                    expect(await tokenService.hasLiveRefreshToken(otherFamily)).toBe(true);
+                    expect(await tokenService.hasLiveRefreshToken(makeFamilyId())).toBe(false);
                 });
                 it("does not count an expired refresh token as live", async ({ skip, }) => {
                     skip(typeof tokenService.hasLiveRefreshToken !== "function", "the service does not implement hasLiveRefreshToken");
-                    await saveFamilyMember(FAMILY, new Date(Date.now() - 1000));
-                    expect(await tokenService.hasLiveRefreshToken(FAMILY), "an expired successor cannot be used, so a replay of its " +
+                    await saveFamilyMember(family, new Date(Date.now() - 1000));
+                    expect(await tokenService.hasLiveRefreshToken(family), "an expired successor cannot be used, so a replay of its " +
                         "predecessor must not be excused as a straggler").toBe(false);
                 });
                 async function rotateOut(skip) {
                     skip(typeof tokenService.isWithinReplayGrace !== "function", "the service does not implement isWithinReplayGrace");
                     skip(typeof tokenService.rotate !== "function" &&
                         typeof tokenService.revokeRotated !== "function", "the service implements neither rotate nor revokeRotated");
-                    const parent = await saveFamilyMember(FAMILY);
-                    const successor = await familyMember(FAMILY);
+                    const parent = await saveFamilyMember(family);
+                    const successor = await familyMember(family);
                     if (tokenService.rotate) {
                         assert(await tokenService.rotate(parent, successor));
                     }
@@ -383,7 +414,7 @@ export function runTokenServiceContractTests(options) {
                         await tokenService.save(successor);
                     }
                     const tombstone = await tokenService.getRevokedRefreshToken(parent.refreshToken);
-                    assert(tombstone?.familyId === FAMILY && tombstone.rotatedAt, "a store that judges the replay grace must still return every " +
+                    assert(tombstone?.familyId === family && tombstone.rotatedAt, "a store that judges the replay grace must still return every " +
                         "rotated-out tombstone, with its family and rotatedAt; hiding " +
                         "one inside the window hides the family from a sign-out " +
                         "racing the refresh, which then leaves the successor live");

package/dist/utils/crypto.d.ts

@@ -2,20 +2,14 @@
  * Authenticated-encryption (AES-256-GCM) and key-derivation helpers for sealing
  * session and token data at rest or in a cookie.
  *
- * Two key-derivation paths, for two different threat models:
- *
- * - {@link deriveAesKey} hashes a single **server-held** secret (SHA-256) into
- *   an AES-256-GCM key. Use this for a stateless cookie sealed under one
- *   configured secret (see `EncryptedCookieSessionStore`), where the secret is
- *   never persisted.
- *
- * - {@link deriveSealKey} uses **HKDF** with a domain-separating `info` label so
- *   a high-entropy *per-session* secret yields an encryption key that is
- *   independent of any other value derived from the same secret. This is what
- *   makes "the cookie value is both the lookup credential **and** the decryption
- *   key" safe: a database can store `sha256(secret)` as a lookup hash while the
- *   sealing key is `HKDF(secret, info)`, and knowing the stored hash never
- *   reveals the key. Always pass a distinct `info` per purpose.
+ * {@link deriveSealKey} uses **HKDF** with a domain-separating `info` label so a
+ * high-entropy secret yields an encryption key that is independent of any other
+ * value derived from the same secret. This is what makes "the cookie value is
+ * both the lookup credential **and** the decryption key" safe: a database can
+ * store `sha256(secret)` as a lookup hash while the sealing key is
+ * `HKDF(secret, info)`, and knowing the stored hash never reveals the key. It is
+ * also what lets one secret seal two kinds of value without either opening as
+ * the other. Always pass a distinct `info` per purpose.
  *
  * {@link seal}/{@link unseal} use AES-256-GCM (an AEAD), so tampered ciphertext
  * fails to unseal (returns `null`) rather than decrypting to garbage.
@@ -61,18 +55,6 @@ export declare function base64urlDecode(value: string): Uint8Array;
  * ```
  */
 export declare function randomToken(bytes?: number): string;
-/**
- * Derive an AES-256-GCM key from a single server-held secret via SHA-256.
- *
- * Suitable when the secret is a long-lived configuration value that is never
- * stored alongside the ciphertext. Do **not** use this when a hash of the same
- * secret is persisted (e.g. as a lookup key) — use {@link deriveSealKey} so the
- * sealing key is independent of that stored hash.
- *
- * @throws {Error} if the secret is shorter than 16 bytes. Length is all that is
- * checked; supply 32+ bytes of real entropy.
- */
-export declare function deriveAesKey(secret: string | Uint8Array): Promise<CryptoKey>;
 /**
  * Derive an AES-256-GCM sealing key from a high-entropy secret via HKDF-SHA-256
  * with a domain-separating `info` label.

package/dist/utils/crypto.js

@@ -2,20 +2,14 @@
  * Authenticated-encryption (AES-256-GCM) and key-derivation helpers for sealing
  * session and token data at rest or in a cookie.
  *
- * Two key-derivation paths, for two different threat models:
- *
- * - {@link deriveAesKey} hashes a single **server-held** secret (SHA-256) into
- *   an AES-256-GCM key. Use this for a stateless cookie sealed under one
- *   configured secret (see `EncryptedCookieSessionStore`), where the secret is
- *   never persisted.
- *
- * - {@link deriveSealKey} uses **HKDF** with a domain-separating `info` label so
- *   a high-entropy *per-session* secret yields an encryption key that is
- *   independent of any other value derived from the same secret. This is what
- *   makes "the cookie value is both the lookup credential **and** the decryption
- *   key" safe: a database can store `sha256(secret)` as a lookup hash while the
- *   sealing key is `HKDF(secret, info)`, and knowing the stored hash never
- *   reveals the key. Always pass a distinct `info` per purpose.
+ * {@link deriveSealKey} uses **HKDF** with a domain-separating `info` label so a
+ * high-entropy secret yields an encryption key that is independent of any other
+ * value derived from the same secret. This is what makes "the cookie value is
+ * both the lookup credential **and** the decryption key" safe: a database can
+ * store `sha256(secret)` as a lookup hash while the sealing key is
+ * `HKDF(secret, info)`, and knowing the stored hash never reveals the key. It is
+ * also what lets one secret seal two kinds of value without either opening as
+ * the other. Always pass a distinct `info` per purpose.
  *
  * {@link seal}/{@link unseal} use AES-256-GCM (an AEAD), so tampered ciphertext
  * fails to unseal (returns `null`) rather than decrypting to garbage.
@@ -79,25 +73,6 @@ export function base64urlDecode(value) {
 export function randomToken(bytes = 32) {
     return base64urlEncode(crypto.getRandomValues(new Uint8Array(bytes)));
 }
-/**
- * Derive an AES-256-GCM key from a single server-held secret via SHA-256.
- *
- * Suitable when the secret is a long-lived configuration value that is never
- * stored alongside the ciphertext. Do **not** use this when a hash of the same
- * secret is persisted (e.g. as a lookup key) — use {@link deriveSealKey} so the
- * sealing key is independent of that stored hash.
- *
- * @throws {Error} if the secret is shorter than 16 bytes. Length is all that is
- * checked; supply 32+ bytes of real entropy.
- */
-export async function deriveAesKey(secret) {
-    const raw = toBytes(secret);
-    if (raw.byteLength < 16) {
-        throw new Error("secret must be at least 16 bytes; 32+ bytes of entropy is recommended.");
-    }
-    const digest = await crypto.subtle.digest("SHA-256", toArrayBuffer(raw));
-    return await crypto.subtle.importKey("raw", digest, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
-}
 /**
  * Derive an AES-256-GCM sealing key from a high-entropy secret via HKDF-SHA-256
  * with a domain-separating `info` label.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.32.1",
+  "version": "0.34.0",
   "description": "A flexible OAuth2 toolkit: framework-agnostic authorization & resource servers, a typed client, Hono adapters (including a backend-for-frontend), and React bindings.",
   "keywords": [
     "authorization-server",