@udibo/oauth2 0.23.0 → 0.25.0

package/dist/react/components/class-names.d.ts

@@ -32,12 +32,12 @@ import type { AuthFormClassNames } from "./types.ts";
  *
  * @example Theme a custom field to match the form around it
  * ```tsx
- * function TenantField(props: { fieldProps: AuthFieldProps }) {
+ * function InviteCodeField(props: { fieldProps: AuthFieldProps }) {
  *   const classNames = useAuthFormClassNames();
  *   return (
  *     <div className={classNames.field}>
  *       <label className={classNames.label} htmlFor={props.fieldProps.id}>
- *         Tenant
+ *         Invite code
  *       </label>
  *       <input {...props.fieldProps} className={classNames.input} />
  *     </div>

package/dist/react/components/class-names.js

@@ -49,12 +49,12 @@ function slotKey(classNames) {
  *
  * @example Theme a custom field to match the form around it
  * ```tsx
- * function TenantField(props: { fieldProps: AuthFieldProps }) {
+ * function InviteCodeField(props: { fieldProps: AuthFieldProps }) {
  *   const classNames = useAuthFormClassNames();
  *   return (
  *     <div className={classNames.field}>
  *       <label className={classNames.label} htmlFor={props.fieldProps.id}>
- *         Tenant
+ *         Invite code
  *       </label>
  *       <input {...props.fieldProps} className={classNames.input} />
  *     </div>

package/dist/server/authorization-server.d.ts

@@ -9,12 +9,13 @@
  * - Server metadata (RFC 8414)
  * - Device authorization (RFC 8628)
  *
- * **Configuration.** A single instance serves every tenant/origin. The only
- * configuration seam is `resolve(request)`, which returns the services the
- * server's own endpoints need (`{ clientService, tokenService }`) plus the
- * issuer/endpoints. Each grant resolves its own services independently. For a
- * single-tenant server, `resolve` is a constant function (create the services
- * once, outside it, and return them every time).
+ * **Configuration.** The only configuration seam is `resolve(request)`, which
+ * returns the per-request configuration: the services the server's own
+ * endpoints need (`{ clientService, tokenService }`) plus the issuer and
+ * endpoint URLs. Because it runs per request, one server can serve the origins
+ * or applications a business operates. Each grant resolves its own services
+ * independently. For a single deployment, `resolve` is a constant function
+ * (create the services once, outside it, and return them every time).
  *
  * @see https://datatracker.ietf.org/doc/html/rfc6749
  * @module
@@ -161,9 +162,11 @@ export interface AuthorizationServerContext<Client extends ClientInterface, User
  */
 export interface AuthorizationServerOptions<Client extends ClientInterface, User, S extends AbstractScope> extends Omit<ResourceServerOptions<Client, User, S>, "resolve"> {
     /**
-     * Resolves the per-request context — the server's own services plus the
-     * issuer/endpoints. This is the only services seam: for a single-tenant
-     * server it is a constant function returning the same context every time.
+     * Resolves the per-request configuration — the server's own services plus
+     * the issuer and endpoint URLs — so one server can serve the origins or
+     * applications a business operates. This is the only services seam: for a
+     * single deployment it is a constant function returning the same context
+     * every time.
      */
     resolve: (request: Request) => AuthorizationServerContext<Client, User, S> | Promise<AuthorizationServerContext<Client, User, S>>;
     /** Grants the server supports, keyed by `grant_type` (each key must equal `grant.grantType`). */
@@ -406,8 +409,8 @@ export declare const ENDPOINT_METHODS: Readonly<Record<EndpointKey, readonly str
  * Framework-agnostic: each `handle*Request` method takes a web `Request` and
  * returns a `Response`, so an adapter routes its endpoints to them. Extends
  * {@linkcode ResourceServer}, so the same instance also validates bearer
- * tokens. A single instance serves every tenant/origin via the `resolve`
- * callback in {@linkcode AuthorizationServerOptions}.
+ * tokens. Its issuer, endpoint URLs and services come per request from the
+ * `resolve` callback in {@linkcode AuthorizationServerOptions}.
  *
  * The handlers throw {@linkcode HttpError} subclasses on failure (e.g.
  * {@linkcode InvalidRequestError}, {@linkcode InvalidClientError},

package/dist/server/authorization-server.js

@@ -9,12 +9,13 @@
  * - Server metadata (RFC 8414)
  * - Device authorization (RFC 8628)
  *
- * **Configuration.** A single instance serves every tenant/origin. The only
- * configuration seam is `resolve(request)`, which returns the services the
- * server's own endpoints need (`{ clientService, tokenService }`) plus the
- * issuer/endpoints. Each grant resolves its own services independently. For a
- * single-tenant server, `resolve` is a constant function (create the services
- * once, outside it, and return them every time).
+ * **Configuration.** The only configuration seam is `resolve(request)`, which
+ * returns the per-request configuration: the services the server's own
+ * endpoints need (`{ clientService, tokenService }`) plus the issuer and
+ * endpoint URLs. Because it runs per request, one server can serve the origins
+ * or applications a business operates. Each grant resolves its own services
+ * independently. For a single deployment, `resolve` is a constant function
+ * (create the services once, outside it, and return them every time).
  *
  * @see https://datatracker.ietf.org/doc/html/rfc6749
  * @module
@@ -154,8 +155,8 @@ function isDeviceAuthorizationGrant(grant) {
  * Framework-agnostic: each `handle*Request` method takes a web `Request` and
  * returns a `Response`, so an adapter routes its endpoints to them. Extends
  * {@linkcode ResourceServer}, so the same instance also validates bearer
- * tokens. A single instance serves every tenant/origin via the `resolve`
- * callback in {@linkcode AuthorizationServerOptions}.
+ * tokens. Its issuer, endpoint URLs and services come per request from the
+ * `resolve` callback in {@linkcode AuthorizationServerOptions}.
  *
  * The handlers throw {@linkcode HttpError} subclasses on failure (e.g.
  * {@linkcode InvalidRequestError}, {@linkcode InvalidClientError},

package/dist/server/grants/refresh-token.d.ts

@@ -86,10 +86,14 @@ export declare class RefreshTokenGrant<Client extends ClientInterface, User, S e
      * token (and rotates the refresh token when the token service supports it)
      * from a valid, unexpired refresh token.
      *
-     * Rotation revokes the exchanged token through the token service's
-     * `revokeRotated` when implemented, falling back to `revoke` — so a service
-     * whose `revoke` ends the owning session can keep this bookkeeping step
-     * from signing the person out.
+     * Rotation claims the exchanged token and saves its successor in one call
+     * to the token service's `rotate` when implemented. Otherwise it takes two
+     * calls: it revokes the exchanged token through `revokeRotated` when
+     * implemented, falling back to `revoke` — so a service whose `revoke` ends
+     * the owning session can keep this bookkeeping step from signing the
+     * person out — and then saves the successor. A refresh that presents the
+     * exchanged token between those two calls is treated as reuse
+     * ({@linkcode TokenServiceInterface.rotate} describes the cost).
      *
      * Rotation renews the refresh token's sliding lifetime, bounded by the
      * family's absolute cap when the token service implements

package/dist/server/grants/refresh-token.js

@@ -32,10 +32,14 @@ export class RefreshTokenGrant extends AbstractGrant {
      * token (and rotates the refresh token when the token service supports it)
      * from a valid, unexpired refresh token.
      *
-     * Rotation revokes the exchanged token through the token service's
-     * `revokeRotated` when implemented, falling back to `revoke` — so a service
-     * whose `revoke` ends the owning session can keep this bookkeeping step
-     * from signing the person out.
+     * Rotation claims the exchanged token and saves its successor in one call
+     * to the token service's `rotate` when implemented. Otherwise it takes two
+     * calls: it revokes the exchanged token through `revokeRotated` when
+     * implemented, falling back to `revoke` — so a service whose `revoke` ends
+     * the owning session can keep this bookkeeping step from signing the
+     * person out — and then saves the successor. A refresh that presents the
+     * exchanged token between those two calls is treated as reuse
+     * ({@linkcode TokenServiceInterface.rotate} describes the cost).
      *
      * Rotation renews the refresh token's sliding lifetime, bounded by the
      * family's absolute cap when the token service implements
@@ -122,6 +126,13 @@ export class RefreshTokenGrant extends AbstractGrant {
         if (familyExpiresAt) {
             this.capAtFamilyExpiry(nextRefreshToken, familyExpiresAt);
         }
+        if (tokenService.rotate) {
+            const rotated = await tokenService.rotate(currentToken, nextRefreshToken);
+            if (!rotated) {
+                throw new InvalidGrantError("refresh_token was already consumed");
+            }
+            return rotated;
+        }
         const claimed = tokenService.revokeRotated
             ? await tokenService.revokeRotated(currentToken)
             : await tokenService.revoke(currentToken);

package/dist/server/resource-server.d.ts

@@ -22,17 +22,18 @@ export interface ResourceServerServices<Client extends ClientInterface, User, S
 }
 /** Per-request context resolved by a {@link ResourceServer}. */
 export interface ResourceServerContext<Client extends ClientInterface, User, S extends AbstractScope> {
-    /** Tenant-scoped services to use for this request. */
+    /** The services to use for this request. */
     services: ResourceServerServices<Client, User, S>;
 }
 /** Options for configuring the resource server. */
 export interface ResourceServerOptions<Client extends ClientInterface, User, S extends AbstractScope> {
     /**
-     * Resolves the per-request context — the (e.g. tenant-scoped) {@link
-     * ResourceServerServices} for THIS request — so a single instance serves
-     * every tenant/origin. This is the only services seam: for a single-tenant
-     * server it is a constant function returning the same services every time
-     * (create the services once, outside `resolve`, and return them here).
+     * Resolves the per-request configuration — the {@link
+     * ResourceServerServices} for THIS request — so one server can serve the
+     * origins or applications a business operates. This is the only services
+     * seam: for a single deployment it is a constant function returning the
+     * same services every time (create the services once, outside `resolve`,
+     * and return them here).
      */
     resolve: (request: Request) => ResourceServerContext<Client, User, S> | Promise<ResourceServerContext<Client, User, S>>;
     /** Scope constructor used to parse and compare scopes. Defaults to {@linkcode BasicScope}. */
@@ -133,10 +134,9 @@ export interface AuthenticatedContext<Client extends ClientInterface, User, S ex
  * authentication. Framework-agnostic: it works on web `Request`/`Response`, so
  * an adapter (Hono, etc.) wires {@linkcode authenticate} into its middleware.
  *
- * A single instance serves every tenant/origin; per-request services come from
- * the `resolve` callback in {@linkcode ResourceServerOptions}. For a
- * single-tenant server, `resolve` is a constant function returning the same
- * services every time.
+ * Per-request services come from the `resolve` callback in
+ * {@linkcode ResourceServerOptions}. For a single deployment, `resolve` is a
+ * constant function returning the same services every time.
  *
  * {@linkcode authenticate} throws {@linkcode HttpError} subclasses on failure
  * ({@linkcode AccessDeniedError} when no token is sent,

package/dist/server/resource-server.js

@@ -31,10 +31,9 @@ const CHALLENGE_ERROR_CODES = new Set([
  * authentication. Framework-agnostic: it works on web `Request`/`Response`, so
  * an adapter (Hono, etc.) wires {@linkcode authenticate} into its middleware.
  *
- * A single instance serves every tenant/origin; per-request services come from
- * the `resolve` callback in {@linkcode ResourceServerOptions}. For a
- * single-tenant server, `resolve` is a constant function returning the same
- * services every time.
+ * Per-request services come from the `resolve` callback in
+ * {@linkcode ResourceServerOptions}. For a single deployment, `resolve` is a
+ * constant function returning the same services every time.
  *
  * {@linkcode authenticate} throws {@linkcode HttpError} subclasses on failure
  * ({@linkcode AccessDeniedError} when no token is sent,

package/dist/server/services/token.d.ts

@@ -129,6 +129,32 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * it, so a sign-out racing a refresh still ends the successor.
      */
     revokeRotated?(token: RefreshToken<Client, User, Scope>): Promise<boolean>;
+    /**
+     * Rotates a refresh token in one atomic step: claims `current` and persists
+     * `next`, its successor in the same family, or does neither. Resolves the
+     * saved successor, or `undefined` with nothing persisted when `current` was
+     * already claimed or revoked, or its family has been revoked. Concurrent
+     * calls for one `current` produce exactly one successor.
+     *
+     * When implemented, the refresh grant calls it instead of
+     * {@linkcode revokeRotated} (or {@linkcode revoke}) followed by
+     * {@linkcode save}. Without it, the grant claims and saves in two calls,
+     * and a request that presents `current` between them finds it revoked with
+     * no live successor: reuse detection revokes the family and fires
+     * `onTokenReuse`, so a benign concurrent refresh signs the person out, and a
+     * store whose `revokeFamily` does not keep the family revoked leaves the
+     * successor live.
+     *
+     * Treat the claim as a rotation, never an end of grant: stamp the
+     * rotated-out record with {@linkcode RefreshToken.rotatedAt} exactly as
+     * {@linkcode revokeRotated} does, keep it findable through
+     * {@linkcode getRevokedRefreshToken}, and revoke its access token as
+     * `revokeRotated` would. Make it linearizable with
+     * {@linkcode revokeFamily}, as that method requires.
+     * `runTokenRotationContractTests` checks it under concurrent callers, with
+     * the store's barrier wired between its claim and its insert.
+     */
+    rotate?(current: RefreshToken<Client, User, Scope>, next: RefreshToken<Client, User, Scope>): Promise<RefreshToken<Client, User, Scope> | undefined>;
     /**
      * Revokes all tokens issued with the given authorization code.
      * Returns true if any tokens were revoked (indicating code replay).
@@ -164,9 +190,17 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * `/revoke` ends the family without firing `onTokenReuse`, so any audit
      * trail for that case has to come from this method.
      *
-     * Keep the family revoked: a successor that a concurrent rotation saves
-     * after this call must be stored already revoked, as
-     * `MemoryTokenService` does.
+     * Without {@linkcode rotate}, keep the family revoked: a successor that a
+     * concurrent rotation saves after this call must be stored already revoked,
+     * as `MemoryTokenService` does. A store that implements `rotate` meets this
+     * through the linearizability below, since the refresh grant then never
+     * saves a rotation's successor separately.
+     *
+     * With {@linkcode rotate}, make the two linearizable: once this resolves,
+     * the family has no live member and no later `rotate` of a member
+     * succeeds, and a `rotate` that committed before this began has its
+     * successor revoked. A store whose `rotate` can be paused between its claim
+     * and its insert meets this by taking one per-family lock in both methods.
      */
     revokeFamily?(familyId: string): Promise<boolean>;
     /**

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

@@ -24,6 +24,12 @@
  * also have separate suites. They use app-owned fixture helpers to verify
  * conditional credential writes and immediate, user-scoped session revocation.
  *
+ * `TokenServiceInterface.rotate` has a runner of its own for concurrent
+ * schedules: two rotations of one refresh token, a family revocation racing a
+ * rotation, and a replay racing a refresh. A store that awaits between its
+ * claim and its insert wires `TokenRotationBarriers` into `rotate`, so the
+ * suite can hold a rotation there.
+ *
  * The service runners take a factory plus seed helpers because `add` /
  * `register` methods aren't part of the public service interfaces — the
  * consumer tells the runner how to populate test data.
@@ -33,6 +39,7 @@
 export { runUserServiceContractTests, type UserServiceContractOptions, } from "./user.ts";
 export { type ClientServiceContractOptions, runClientServiceContractTests, } from "./client.ts";
 export { runTokenServiceContractTests, type TokenServiceContractOptions, } from "./token.ts";
+export { runTokenRotationContractTests, type TokenRotationBarriers, type TokenRotationContractOptions, type TokenRotationContractServices, } from "./token-rotation.ts";
 export { runTokenReaderContractTests, type TokenReaderContractFixture, type TokenReaderContractOptions, } from "./token-reader.ts";
 export { type AuthorizationCodeServiceContractOptions, runAuthorizationCodeServiceContractTests, } from "./authorization-code.ts";
 export { type DeviceAuthorizationServiceContractOptions, runDeviceAuthorizationServiceContractTests, } from "./device-authorization.ts";

package/dist/testing/contract/mod.js

@@ -24,6 +24,12 @@
  * also have separate suites. They use app-owned fixture helpers to verify
  * conditional credential writes and immediate, user-scoped session revocation.
  *
+ * `TokenServiceInterface.rotate` has a runner of its own for concurrent
+ * schedules: two rotations of one refresh token, a family revocation racing a
+ * rotation, and a replay racing a refresh. A store that awaits between its
+ * claim and its insert wires `TokenRotationBarriers` into `rotate`, so the
+ * suite can hold a rotation there.
+ *
  * The service runners take a factory plus seed helpers because `add` /
  * `register` methods aren't part of the public service interfaces — the
  * consumer tells the runner how to populate test data.
@@ -33,6 +39,7 @@
 export { runUserServiceContractTests, } from "./user.js";
 export { runClientServiceContractTests, } from "./client.js";
 export { runTokenServiceContractTests, } from "./token.js";
+export { runTokenRotationContractTests, } from "./token-rotation.js";
 export { runTokenReaderContractTests, } from "./token-reader.js";
 export { runAuthorizationCodeServiceContractTests, } from "./authorization-code.js";
 export { runDeviceAuthorizationServiceContractTests, } from "./device-authorization.js";

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

@@ -0,0 +1,95 @@
+/**
+ * Contract test suite for {@link TokenServiceInterface.rotate} and its
+ * linearizability with {@link TokenServiceInterface.revokeFamily}.
+ *
+ * `runTokenServiceContractTests` checks what one caller sees. This suite
+ * checks what concurrent callers see: two rotations of one refresh token, a
+ * family revocation racing a rotation, a replay racing a refresh through the
+ * refresh grant, a rotation in an unrelated family, and a rotation whose
+ * insert fails. Each case asserts the store's end state, the live tokens of
+ * the family, not only the value each call resolved.
+ *
+ * The store under test awaits {@link TokenRotationBarriers.afterClaim} inside
+ * `rotate`, between its claim and its insert, so the suite can hold a rotation
+ * there and race the other call against it; a store that never reaches the
+ * barrier fails every held case. Only a store whose `rotate` never awaits
+ * between its claim and its insert, such as `MemoryTokenService`, opts out with
+ * `rotateAwaitsBarrier: false`; the suite then runs those schedules as
+ * overlapping calls.
+ *
+ * @module
+ */
+import type { ClientInterface } from "../../models/client.ts";
+import type { AbstractScope, BasicScope } from "../../models/scope.ts";
+import type { ClientServiceInterface } from "../../server/services/client.ts";
+import type { TokenServiceInterface } from "../../server/services/token.ts";
+import type { UserServiceInterface } from "../../server/services/user.ts";
+import type { MemoryUserShape } from "../services.ts";
+/**
+ * The point inside a store's {@linkcode TokenServiceInterface.rotate} at which
+ * {@link runTokenRotationContractTests} holds a rotation. Wire it into a test
+ * build of the store.
+ */
+export interface TokenRotationBarriers {
+    /**
+     * Await this inside `rotate` after claiming `current` and before persisting
+     * `next`, still inside the atomic step: within the transaction and holding
+     * the family's lock. When it rejects, fail the rotation as a failed insert
+     * would: leave `current` live, persist nothing, and reject or resolve
+     * `undefined`.
+     */
+    afterClaim(): Promise<void>;
+}
+/** Services built for each case of {@link runTokenRotationContractTests}. */
+export interface TokenRotationContractServices<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> {
+    /** The user service the token service hydrates users from. */
+    userService: UserServiceInterface<U>;
+    /** The client service the token service hydrates clients from. */
+    clientService: ClientServiceInterface<C, U>;
+    /** The token service under test. It must implement `rotate`. */
+    tokenService: TokenServiceInterface<C, U, S>;
+}
+/** Options for {@link runTokenRotationContractTests}. */
+export interface TokenRotationContractOptions<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> {
+    /**
+     * Returns fresh services for each case, with `rotate` awaiting
+     * `barriers.afterClaim()` between its claim and its insert. A store that
+     * sets `rotateAwaitsBarrier: false` ignores `barriers`.
+     */
+    makeServices(barriers: TokenRotationBarriers): Promise<TokenRotationContractServices<C, U, S>> | TokenRotationContractServices<C, U, S>;
+    /** Persists a user with the given password into the user service under test. */
+    addUser(service: UserServiceInterface<U>, user: U, password: string): Promise<void>;
+    /** Persists a client into the client service under test. */
+    addClient(service: ClientServiceInterface<C, U>, client: C): Promise<void>;
+    /** Builds a distinct user fixture for the given sequence number. Defaults to a minimal `{ id, username }` shape. */
+    makeUser?(seq: number): U;
+    /** Builds a distinct client fixture for the given sequence number. Defaults to a client granting `authorization_code` and `refresh_token`. */
+    makeClient?(seq: number): C;
+    /**
+     * Whether `rotate` awaits `barriers.afterClaim()`. Defaults to `true`: the
+     * suite holds a rotation between its claim and its insert while it runs a
+     * family revocation, a second rotation, a replayed refresh, or a rotation in
+     * another family, and fails the insert there. Set `false` only when
+     * `rotate` never awaits between its claim and its insert, as in
+     * `MemoryTokenService`; the suite then runs those schedules as overlapping
+     * calls, which cannot reach a gap inside `rotate`.
+     */
+    rotateAwaitsBarrier?: boolean;
+    /**
+     * Milliseconds the suite lets a call run against a held rotation before it
+     * releases the rotation; a call that has not settled by then is taken to
+     * be waiting on it. Defaults to 100. Raise it for a store whose calls take
+     * longer to reach the lock they wait on.
+     */
+    blockedAfterMs?: number;
+    /** Overrides the name passed to the outer `describe` block. */
+    describeName?: string;
+}
+/**
+ * Runs the rotation contract suite: concurrent schedules of
+ * {@linkcode TokenServiceInterface.rotate} against itself, against
+ * {@linkcode TokenServiceInterface.revokeFamily}, and through the refresh
+ * grant. The service must implement `rotate`, `revokeFamily` and
+ * `getRevokedRefreshToken`.
+ */
+export declare function runTokenRotationContractTests<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope>(options: TokenRotationContractOptions<C, U, S>): void;