@idp.global/sdk 19.4.0 → 19.5.0

package/ts_browser/classes.relyingpartybearerclient.ts

@@ -1,13 +1,22 @@
 import {
+  isPkceVerifier,
   RELYING_PARTY_BEARER_MESSAGE_TYPE,
+  type IRelyingPartyBearerClaimRequest,
+  type IRelyingPartyBearerLoginQuery,
   type IRelyingPartyBearerLogoutAnswer,
+  type IRelyingPartyBearerLogoutRequest,
+  type IRelyingPartyBearerRefreshRequest,
   type IRelyingPartyBearerTokenAnswer,
 } from '../ts_relyingparty/contract.bearer.js';
 
 export type {
+  IRelyingPartyBearerClaimRequest,
   IRelyingPartyBearerErrorAnswer,
+  IRelyingPartyBearerLoginQuery,
   IRelyingPartyBearerLogoutAnswer,
+  IRelyingPartyBearerLogoutRequest,
   IRelyingPartyBearerMessage,
+  IRelyingPartyBearerRefreshRequest,
   IRelyingPartyBearerSessionAnswer,
   IRelyingPartyBearerSessionInfo,
   IRelyingPartyBearerTokenAnswer,
@@ -49,6 +58,19 @@ export interface IRelyingPartyBearerTokenStorage {
   clear(optionsArg: { signal: AbortSignal }): Promise<void>;
 }
 
+/**
+ * A PKCE pair (RFC 7636): the verifier the client keeps and the S256
+ * challenge it hands out. `codeVerifier` is the secret that makes a code
+ * worth anything; keep it like a pending login, never in a URL, a log or a
+ * message.
+ */
+export interface IRelyingPartyBearerPkce {
+  /** 43 characters from 32 random bytes */
+  codeVerifier: string;
+  /** BASE64URL(SHA-256(codeVerifier)) */
+  codeChallenge: string;
+}
+
 /**
  * A login on its way: what `createLogin` made and the receiver needs back.
  * A `web` login leaves the page, so the application keeps it until the
@@ -149,7 +171,7 @@ export type TRelyingPartyBearerClientErrorCode =
   | 'state_mismatch'
   /** the delivery carries no code; `deliveryError` says why */
   | 'login_failed'
-  /** this login was received once already; a code is claimed once, never again */
+  /** this login, or this PKCE pair, was received once already; a code is claimed once, never again */
   | 'already_received'
   /** the browser opened no popup */
   | 'popup_blocked'
@@ -219,6 +241,12 @@ const isText = (valueArg: unknown): valueArg is string => typeof valueArg === 's
 
 const isTime = (valueArg: unknown): valueArg is number => typeof valueArg === 'number' && Number.isFinite(valueArg);
 
+/** What the client posts to the bearer routes. */
+type TRelyingPartyBearerRequestBody =
+  | IRelyingPartyBearerClaimRequest
+  | IRelyingPartyBearerRefreshRequest
+  | IRelyingPartyBearerLogoutRequest;
+
 /** Throws `request_failed` once a section's deadline has fired: nothing is sent or written past it. */
 const inTime = (signalArg: AbortSignal): void => {
   if (signalArg.aborted) {
@@ -278,7 +306,9 @@ const tokenAnswerOf = (answerArg: unknown): IRelyingPartyBearerTokenAnswer | nul
  * request or write never holds the other tabs. A login replaces the stored
  * pair and ends that pair's session. Rotation is strict at the relying
  * party: a refresh token spent once ends the session when it comes back, so
- * nothing here retries a claim or a refresh.
+ * nothing here retries a claim or a refresh. A code that reaches the client
+ * another way, such as a device pairing, is claimed through `createPkce` and
+ * `claimCode` under the same rules, without a window.
  *
  * It needs the Web Locks API and Web Crypto, both of them only in a secure
  * context, and has no fallback for either.
@@ -296,6 +326,8 @@ export class RelyingPartyBearerClient {
   readonly #now: () => number;
   /** the states of the logins received here; a login is received once */
   readonly #receivedStates = new Set<string>();
+  /** the challenges of the pairs `claimCode` claimed with here; a pair is claimed with once */
+  readonly #claimedChallenges = new Set<string>();
 
   constructor(optionsArg: IRelyingPartyBearerClientOptions) {
     const origin = optionsArg?.origin;
@@ -375,17 +407,63 @@ export class RelyingPartyBearerClient {
     if (!isText(returnTarget)) {
       throw new Error('returnTarget must name the configured return target');
     }
-    const codeVerifier = randomBase64Url();
+    const { codeVerifier, codeChallenge } = await this.createPkce();
     const state = randomBase64Url();
+    const query: Required<IRelyingPartyBearerLoginQuery> = {
+      client_kind: clientKind,
+      return_target: returnTarget,
+      code_challenge: codeChallenge,
+      code_challenge_method: 'S256',
+      state,
+    };
     const url = new URL(this.#paths.login);
-    url.searchParams.set('client_kind', clientKind);
-    url.searchParams.set('return_target', returnTarget);
-    url.searchParams.set('code_challenge', await pkceChallengeOf(codeVerifier));
-    url.searchParams.set('code_challenge_method', 'S256');
-    url.searchParams.set('state', state);
+    for (const [name, value] of Object.entries(query)) {
+      url.searchParams.set(name, value);
+    }
     return { clientKind, returnTarget, state, codeVerifier, url: url.href };
   }
 
+  /**
+   * A fresh PKCE pair: a verifier from 32 random bytes and its S256
+   * challenge. For a code the client does not receive through its own login,
+   * such as one the application delivers to a device it pairs: the challenge
+   * goes to the application, and `claimCode` claims the code with the pair.
+   * Needs no window.
+   */
+  public async createPkce(): Promise<IRelyingPartyBearerPkce> {
+    const codeVerifier = randomBase64Url();
+    return { codeVerifier, codeChallenge: await pkceChallengeOf(codeVerifier) };
+  }
+
+  /**
+   * Claims a hand-off code that was bound to `pkceArg`'s challenge and
+   * reached this client some other way than its own login, such as a device
+   * pairing (`openBearerHandoff` at the relying party). It is received like
+   * a login: one claim, never retried, under `requestTimeoutMs`, and the
+   * claimed pair replaces the stored one under the lock, whose session is
+   * ended then (`IRelyingPartyBearerLoginResult`). A pair is claimed with
+   * once: a second call with it, after a failed claim too, is
+   * `already_received` and sends nothing. A pair that is not one (a
+   * malformed verifier, a challenge that is not its S256) or a code that is
+   * not text is refused before anything is sent. Needs no window.
+   */
+  public async claimCode(pkceArg: IRelyingPartyBearerPkce, codeArg: string): Promise<IRelyingPartyBearerLoginResult> {
+    const codeVerifier: unknown = pkceArg?.codeVerifier;
+    const codeChallenge: unknown = pkceArg?.codeChallenge;
+    if (!isPkceVerifier(codeVerifier) || typeof codeChallenge !== 'string' || codeChallenge !== await pkceChallengeOf(codeVerifier)) {
+      throw new Error('claimCode needs a PKCE pair: a verifier and its S256 challenge, as createPkce makes them');
+    }
+    if (!isText(codeArg)) {
+      throw new Error('claimCode needs the hand-off code as text');
+    }
+    if (this.#claimedChallenges.has(codeChallenge)) {
+      throw new RelyingPartyBearerClientError('already_received');
+    }
+    // taken before the claim is sent: a failed claim uses the pair up too
+    this.#claimedChallenges.add(codeChallenge);
+    return this.claim(codeArg, codeVerifier);
+  }
+
   /**
    * Receives a `web` login on its return target page. The delivery leaves
    * the address first, before anything is checked, so neither a reload nor
@@ -548,9 +626,14 @@ export class RelyingPartyBearerClient {
     if (!isText(codeArg)) {
       throw new RelyingPartyBearerClientError('unexpected_answer');
     }
+    return this.claim(codeArg, loginArg.codeVerifier);
+  }
+
+  /** Claims a code once with its verifier and stores the pair in place of the one before. */
+  private async claim(codeArg: string, codeVerifierArg: string): Promise<IRelyingPartyBearerLoginResult> {
+    const body: IRelyingPartyBearerClaimRequest = { code: codeArg, codeVerifier: codeVerifierArg };
     // the claim touches no stored pair, so it holds no lock, only its own deadline; a failed one leaves the stored pair as it was
-    const answer = tokenAnswerOf(await this.withDeadline((signalArg) =>
-      this.post(this.#paths.claim, { code: codeArg, codeVerifier: loginArg.codeVerifier }, {}, signalArg)));
+    const answer = tokenAnswerOf(await this.withDeadline((signalArg) => this.post(this.#paths.claim, body, {}, signalArg)));
     if (!answer) {
       throw new RelyingPartyBearerClientError('unexpected_answer', { status: 200 });
     }
@@ -695,8 +778,9 @@ export class RelyingPartyBearerClient {
         return current;
       }
       let answer: IRelyingPartyBearerTokenAnswer | null;
+      const body: IRelyingPartyBearerRefreshRequest = { refreshToken: current.refreshToken };
       try {
-        answer = tokenAnswerOf(await this.post(this.#paths.refresh, { refreshToken: current.refreshToken }, {}, signalArg));
+        answer = tokenAnswerOf(await this.post(this.#paths.refresh, body, {}, signalArg));
       } catch (error) {
         if (error instanceof RelyingPartyBearerClientError && error.answerError === 'invalid_bearer_grant') {
           // the session is over: this pair opens nothing any more
@@ -718,12 +802,8 @@ export class RelyingPartyBearerClient {
 
   /** Ends the session of a pair through the logout route and answers whether that ended a live one. */
   private async endSessionOf(pairArg: IRelyingPartyBearerStoredTokens, signalArg: AbortSignal): Promise<boolean> {
-    const answer = await this.post(
-      this.#paths.logout,
-      { refreshToken: pairArg.refreshToken },
-      { authorization: `Bearer ${pairArg.accessToken}` },
-      signalArg,
-    );
+    const body: IRelyingPartyBearerLogoutRequest = { refreshToken: pairArg.refreshToken };
+    const answer = await this.post(this.#paths.logout, body, { authorization: `Bearer ${pairArg.accessToken}` }, signalArg);
     if (!isRecord(answer) || typeof answer.endedLiveSession !== 'boolean') {
       throw new RelyingPartyBearerClientError('unexpected_answer', { status: 200 });
     }
@@ -772,7 +852,7 @@ export class RelyingPartyBearerClient {
    */
   private async post(
     urlArg: string,
-    bodyArg: Record<string, string>,
+    bodyArg: TRelyingPartyBearerRequestBody,
     headersArg: Record<string, string> = {},
     signalArg?: AbortSignal,
   ): Promise<unknown> {

package/ts_relyingparty/classes.errors.ts

@@ -14,6 +14,8 @@ export type TRelyingPartyErrorCode =
   | 'invalid_bearer_handoff'
   /** a refresh token that is unknown, rotated, expired, or of a session that is over */
   | 'invalid_bearer_grant'
+  /** `openBearerHandoff` named an opener that is no live provider login: unknown, ended, expired, of an inactive principal, or without a provider login of its own */
+  | 'invalid_handoff_opener'
   /** a `sessionsOfPrincipal` cursor that no page of it answered */
   | 'invalid_sessions_cursor';
 
@@ -27,6 +29,7 @@ const RELYING_PARTY_ERROR_STATUS: Readonly<Record<TRelyingPartyErrorCode, number
   return_target_not_allowed: 400,
   invalid_bearer_handoff: 400,
   invalid_bearer_grant: 400,
+  invalid_handoff_opener: 400,
   invalid_sessions_cursor: 400,
 };
 

package/ts_relyingparty/classes.relyingpartysessions.ts

@@ -39,6 +39,7 @@ import type {
   IProviderToken,
   IRelyingPartyBearerDelivery,
   IRelyingPartyBearerHandoff,
+  IRelyingPartyBearerHandoffOpening,
   IRelyingPartyBearerLoginRequest,
   IRelyingPartyBearerLoginStart,
   IRelyingPartyBearerOptions,
@@ -52,6 +53,7 @@ import type {
   IRelyingPartyLoginStart,
   IRelyingPartySession,
   IRelyingPartySessionOpening,
+  IRelyingPartySessionsErasure,
   IRelyingPartySessionsPage,
   IRelyingPartySessionsPageOptions,
   IResolvedRelyingPartySession,
@@ -159,7 +161,7 @@ export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefi
 export interface IRelyingPartyBearerOnlySessionsOptions<TPrincipal extends object | undefined = undefined>
   extends Omit<IRelyingPartySessionsOptions<TPrincipal>, 'provider' | 'csrfKey' | 'csrfLabel' | 'cookieNames' | 'cookieSessions' | 'bearer'> {
   cookieSessions: false;
-  /** every bearer session is a provider login */
+  /** every bearer session comes from a live provider login, directly or through a hand-off opened from one */
   provider: IOidcProvider;
   bearer: IRelyingPartyBearerOptions;
   csrfKey?: never;
@@ -190,7 +192,7 @@ const bearerModeOf = (
     throw new Error('bearer must be an object with returnTargets');
   }
   if (!optionsArg.hasProvider) {
-    throw new Error('bearer needs a provider: every bearer session is a provider login');
+    throw new Error('bearer needs a provider: every bearer session comes from a provider login');
   }
   const { BearerHandoff, BearerToken } = optionsArg.models;
   if (!BearerHandoff || !BearerToken) {
@@ -297,10 +299,10 @@ const cookieNameFor = (
  * ended sessions are swept one bounded batch at a time when a login starts or
  * the application opens a session, and the only timer — the revocation
  * budget — is unreferenced and cleared on every path. Every session comes
- * from a login start or from `openSession`, and each of those sweeps a batch
- * of at least one first, so removal keeps pace with creation and the ended
- * sessions kept stay bounded. Nothing here does I/O while it is constructed,
- * so it is built before the database connects.
+ * from a login start, `openSession` or `openBearerHandoff`, and each of those
+ * sweeps a batch of at least one first, so removal keeps pace with creation
+ * and the ended sessions kept stay bounded. Nothing here does I/O while it is
+ * constructed, so it is built before the database connects.
  *
  * `TPrincipal` is what a `principals.resolve` answers; with `isActive`
  * principals it stays `undefined`.
@@ -580,6 +582,54 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return ended;
   }
 
+  /**
+   * Erases every session of a principal, live or ended, and every row that
+   * belongs to one, without waiting for a sweep: what an application runs
+   * when it deletes an account, after its own erasers and before its user
+   * record.
+   *
+   * First each session not revoked yet, an expired one too, ends as
+   * `endSession` ends it: its tokens stop working at once, `onSessionEnded`
+   * names the principal, and its provider tokens go back to idp.global,
+   * which a deleted row could no longer do. Then each session's rows go: in
+   * bearer mode its hand-offs, claimed or not, and its token generations;
+   * the login attempt a provider session came out of; and the session row
+   * last, because it is the only link from the principal to the others, so
+   * an erase that fails half way leaves a retry everything it needs. A
+   * session opened or a token issued while the erase runs is not covered;
+   * it works only while the principal is active.
+   */
+  public async eraseSessionsOfPrincipal(principalIdArg: string): Promise<IRelyingPartySessionsErasure> {
+    if (typeof principalIdArg !== 'string' || principalIdArg === '') {
+      throw new Error('eraseSessionsOfPrincipal needs a principal id');
+    }
+    const erasure: IRelyingPartySessionsErasure = {
+      endedSessions: 0,
+      deletedSessions: 0,
+      deletedLoginAttempts: 0,
+      deletedBearerHandoffs: 0,
+      deletedBearerTokens: 0,
+    };
+    const sessions = await this.#models.Session.getInstances({ userId: principalIdArg });
+    for (const session of sessions) {
+      if (session.revokedAt === undefined && (await this.endSession(session.id))) {
+        erasure.endedSessions += 1;
+      }
+    }
+    const bearerModels = this.#bearer?.models;
+    for (const session of sessions) {
+      if (bearerModels) {
+        erasure.deletedBearerHandoffs += (await bearerModels.BearerHandoff.atomicDeleteMany({ sessionId: session.id })).deletedCount;
+        erasure.deletedBearerTokens += (await bearerModels.BearerToken.atomicDeleteMany({ sessionId: session.id })).deletedCount;
+      }
+      if (session.loginAttemptId) {
+        erasure.deletedLoginAttempts += (await this.#models.LoginAttempt.atomicDelete({ id: session.loginAttemptId })).deletedCount;
+      }
+      erasure.deletedSessions += (await this.#models.Session.atomicDelete({ id: session.id })).deletedCount;
+    }
+    return erasure;
+  }
+
   /**
    * One page of a principal's live sessions, newest first: the ones neither
    * ended nor expired, and none at all while the principal is not active —
@@ -876,28 +926,85 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if (!isPkceChallenge(codeChallenge)) {
       throw new RelyingPartyError('invalid_or_replayed_login');
     }
-    const code = randomToken(32);
-    let handoff: RelyingPartyBearerHandoffDoc | undefined;
+    let handoff: { code: string; expiresAt: number } | undefined;
     const opened = await this.openProviderLogin(provider, callbackUrlArg, state, attempt, async (sessionArg) => {
-      const created = new bearer.models.BearerHandoff();
-      created.id = 'rbh_' + randomToken(18);
-      created.codeHash = sha256(code);
-      created.sessionId = sessionArg.id;
-      created.codeChallenge = codeChallenge;
-      created.createdAt = this.#now();
-      created.expiresAt = Math.min(created.createdAt + BEARER_HANDOFF_MAX_AGE_SECONDS * 1_000, sessionArg.expiresAt);
-      created.consumedAt = null;
-      await created.save();
-      handoff = created;
+      handoff = await this.storeBearerHandoff(bearer, sessionArg, codeChallenge);
     });
+    const stored = handoff as { code: string; expiresAt: number };
     return {
       session: this.snapshot(opened.document),
       delivery,
-      code,
-      expiresAt: (handoff as RelyingPartyBearerHandoffDoc).expiresAt,
+      code: stored.code,
+      expiresAt: stored.expiresAt,
     };
   }
 
+  /**
+   * Opens a bearer session for a device the application pairs to a person
+   * who is signed in here, and answers its single-use hand-off code, which
+   * the device claims at `bearer/claim` with the verifier of `codeChallenge`,
+   * exactly like the code of a bearer login.
+   *
+   * `openerSessionId` names the session that confirmed the pairing, taken
+   * from the application's own record, never from the device. It must be a
+   * live provider login: not ended, not expired, its principal active, and
+   * with a provider login of its own. A session the application opened
+   * itself or one opened here does not qualify, so a paired device never
+   * pairs another one. Anything else throws
+   * `RelyingPartyError('invalid_handoff_opener')`.
+   *
+   * The new session acts as the opener's principal and has no provider login
+   * of its own: it ends by its expiry, `endSession`, `endSessionsOfPrincipal`,
+   * `bearer/logout` or the reuse of one of its credentials, never by an
+   * idp.global logout, and `AuthorityObserver` refuses it
+   * (`authority_login_required`). `maxAgeSeconds` is a whole number from 1 to
+   * `sessionMaxAgeSeconds`, the default, as for `openSession`. The code lives
+   * `BEARER_HANDOFF_MAX_AGE_SECONDS` at most and never past the session, and
+   * only its hash is stored; a code nobody claims ends its session. Nothing
+   * is stored for a refused opening.
+   */
+  public async openBearerHandoff(optionsArg: {
+    openerSessionId: string;
+    codeChallenge: string;
+    maxAgeSeconds?: number;
+  }): Promise<IRelyingPartyBearerHandoffOpening> {
+    const bearer = this.requireBearer();
+    if (!isPkceChallenge(optionsArg?.codeChallenge)) {
+      throw new RelyingPartyError('invalid_bearer_request');
+    }
+    const codeChallenge = optionsArg.codeChallenge;
+    const maxAgeSeconds = optionsArg.maxAgeSeconds ?? this.sessionMaxAgeSeconds;
+    if (!Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds < 1 || maxAgeSeconds > this.sessionMaxAgeSeconds) {
+      throw new RangeError(`openBearerHandoff maxAgeSeconds must be a whole number from 1 to ${this.sessionMaxAgeSeconds}`);
+    }
+    await this.sweepBearerState();
+    await this.sweepEndedSessions();
+    // read after the sweeps, so the opener is as live as it can be when the session is created
+    const openerSessionId = optionsArg.openerSessionId;
+    const opener = typeof openerSessionId === 'string' && openerSessionId.length > 0
+      ? await this.liveSession(await this.#models.Session.getInstance({ id: openerSessionId }))
+      : null;
+    if (!opener || typeof opener.document.idpSubject !== 'string' || opener.document.idpSubject.length === 0) {
+      throw new RelyingPartyError('invalid_handoff_opener');
+    }
+    // the token is never handed out: the session is reached by its code only, as a bearer login's
+    const session = this.newSessionDoc(randomToken(32), opener.document.userId, maxAgeSeconds);
+    await session.save();
+    let handoff: { code: string; expiresAt: number };
+    try {
+      handoff = await this.storeBearerHandoff(bearer, session, codeChallenge);
+    } catch (error) {
+      // the code never leaves, so the session is unreachable: it is revoked before the error goes on
+      try {
+        await this.discardUnopenedSession(session.id);
+      } catch (discardError) {
+        this.emit({ event: 'session_discard_failed', sessionId: session.id, message: errorMessage(discardError) });
+      }
+      throw error;
+    }
+    return { session: this.snapshot(session), code: handoff.code, expiresAt: handoff.expiresAt };
+  }
+
   /** `abandonLogin` for a bearer login: the provider came back without a code. */
   public async abandonBearerLogin(callbackUrlArg: URL): Promise<void> {
     const state = singleStateOf(callbackUrlArg);
@@ -958,9 +1065,11 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * access and refresh token answer, and the old access token stops working.
    * Rotation is strict — a client serializes its refreshes — because a
    * refresh token that comes back after it was spent ends the whole session.
-   * The provider login is checked on the way: a login idp.global ended ends
-   * the session here (`invalid_bearer_grant`), an unreachable provider fails
-   * with `AuthorityTokenError('authority_unavailable')` and spends nothing.
+   * The provider login of a bearer login is checked on the way: a login
+   * idp.global ended ends the session here (`invalid_bearer_grant`), an
+   * unreachable provider fails with `AuthorityTokenError('authority_unavailable')`
+   * and spends nothing. A session `openBearerHandoff` opened has no provider
+   * login (no `idpSubject` is stored) and rotates without the provider.
    */
   public async refreshBearerTokens(refreshTokenArg: unknown): Promise<IRelyingPartyBearerTokens> {
     const bearer = this.requireBearer();
@@ -984,13 +1093,17 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if (!live) {
       throw new RelyingPartyError('invalid_bearer_grant');
     }
-    try {
-      await this.liveProviderToken(live.document.id, live.document.userId);
-    } catch (error) {
-      if (error instanceof AuthorityTokenError && error.code === 'authority_login_required') {
-        throw new RelyingPartyError('invalid_bearer_grant');
+    // decided by what the session stores alone, never by a failure: a session
+    // with a provider subject is a provider login and always asks the provider
+    if (typeof live.document.idpSubject === 'string') {
+      try {
+        await this.liveProviderToken(live.document.id, live.document.userId);
+      } catch (error) {
+        if (error instanceof AuthorityTokenError && error.code === 'authority_login_required') {
+          throw new RelyingPartyError('invalid_bearer_grant');
+        }
+        throw error;
       }
-      throw error;
     }
     // the next generation first: a rotation that fails half way leaves an
     // unknown generation behind, never a session without a current one
@@ -1466,7 +1579,8 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     }
     try {
       await beforeOpenedArg?.(session);
-      await this.#hooks.onProviderSessionOpened?.({ session: this.snapshot(session) });
+      const delivery = this.bearerDeliveryOfAttempt(attemptArg);
+      await this.#hooks.onProviderSessionOpened?.({ session: this.snapshot(session), ...(delivery ? { delivery } : {}) });
     } catch (error) {
       // the cookie (or the hand-off code) never leaves, so the session is
       // unreachable: it is revoked and its sealed tokens erased before the
@@ -1500,6 +1614,29 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     };
   }
 
+  /**
+   * Stores a new hand-off of a session, bound to the client's challenge, and
+   * answers its code, which is stored only as a hash. The code lives
+   * `BEARER_HANDOFF_MAX_AGE_SECONDS` at most and never past the session.
+   */
+  private async storeBearerHandoff(
+    bearerArg: IBearerMode,
+    sessionArg: RelyingPartySessionDoc,
+    codeChallengeArg: string,
+  ): Promise<{ code: string; expiresAt: number }> {
+    const code = randomToken(32);
+    const handoff = new bearerArg.models.BearerHandoff();
+    handoff.id = 'rbh_' + randomToken(18);
+    handoff.codeHash = sha256(code);
+    handoff.sessionId = sessionArg.id;
+    handoff.codeChallenge = codeChallengeArg;
+    handoff.createdAt = this.#now();
+    handoff.expiresAt = Math.min(handoff.createdAt + BEARER_HANDOFF_MAX_AGE_SECONDS * 1_000, sessionArg.expiresAt);
+    handoff.consumedAt = null;
+    await handoff.save();
+    return { code, expiresAt: handoff.expiresAt };
+  }
+
   /** Stores the next token generation of a live session and answers its tokens; none of them is stored in the clear. */
   private async issueBearerTokens(bearerArg: IBearerMode, sessionArg: RelyingPartySessionDoc): Promise<IRelyingPartyBearerTokens> {
     const accessToken = randomToken(32);
@@ -1591,11 +1728,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * local revocation and the provider revocation: a throw or a rejection is
    * reported as `hook_failed` and the end runs on.
    */
-  private notifySessionEnded(eventArg: {
-    sessionId: string;
-    reason: TRelyingPartySessionEndReason;
-    revokedHere: boolean;
-  }): void {
+  private notifySessionEnded(eventArg: Parameters<NonNullable<IRelyingPartyHooks['onSessionEnded']>>[0]): void {
     const hook = this.#hooks.onSessionEnded;
     if (!hook) {
       return;
@@ -1626,10 +1759,11 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
       return null;
     }
     const before = await this.revokeSessionDocument(sessionIdArg);
-    this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere: before !== null });
     if (!before) {
+      this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere: false });
       return null;
     }
+    this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere: true, principalId: before.userId });
     return { sealedAccessToken: before.sealedAccessToken, sealedRefreshToken: before.sealedRefreshToken };
   }
 

package/ts_relyingparty/contract.bearer.ts

@@ -41,6 +41,52 @@ export interface IRelyingPartyBearerMessage {
  */
 export type TRelyingPartyBearerDeliveryError = 'access_denied' | 'authentication_failed' | (string & {});
 
+/** RFC 7636 §4.1: a code verifier is 43 to 128 characters of `A-Z a-z 0-9 . _ ~ -`. */
+const PKCE_VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/u;
+
+/** Whether a value is a well-formed PKCE code verifier (RFC 7636 §4.1). */
+export const isPkceVerifier = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && PKCE_VERIFIER.test(valueArg);
+
+/**
+ * The query of `GET <prefix>bearer/login`, by its parameter names on the
+ * wire. The routes check every parameter as untrusted input.
+ */
+export interface IRelyingPartyBearerLoginQuery {
+  client_kind: TRelyingPartyBearerClientKind;
+  /** one of the configured return targets of the kind, exactly; a loopback target with the client's port */
+  return_target: string;
+  /** BASE64URL(SHA-256(code verifier)), 43 characters */
+  code_challenge: string;
+  /** only `S256` is accepted */
+  code_challenge_method: 'S256';
+  /** the client's own correlation value, 1 to 256 characters of `A-Z a-z 0-9 . _ ~ -`, handed back with the outcome */
+  state?: string;
+}
+
+/** The JSON body of `POST <prefix>bearer/claim`. */
+export interface IRelyingPartyBearerClaimRequest {
+  /** the hand-off code, claimed once */
+  code: string;
+  /** the verifier of the challenge the code is bound to (`isPkceVerifier`) */
+  codeVerifier: string;
+}
+
+/** The JSON body of `POST <prefix>bearer/refresh`. */
+export interface IRelyingPartyBearerRefreshRequest {
+  /** the current refresh token; this call spends it */
+  refreshToken: string;
+}
+
+/**
+ * The JSON body of `POST <prefix>bearer/logout`. The session is named by
+ * `Authorization: Bearer <accessToken>`, or by `refreshToken` once that access
+ * token has expired.
+ */
+export interface IRelyingPartyBearerLogoutRequest {
+  refreshToken?: string;
+}
+
 /** The session a bearer answer names. */
 export interface IRelyingPartyBearerSessionInfo {
   sessionId: string;

package/ts_relyingparty/helpers.bearer.ts

@@ -1,4 +1,5 @@
 import {
+  isPkceVerifier,
   RELYING_PARTY_BEARER_MESSAGE_TYPE,
   type IRelyingPartyBearerMessage,
   type TRelyingPartyBearerClientKind,
@@ -7,7 +8,8 @@ import { sha256, timingSafeEqualString } from './helpers.crypto.js';
 import { sanitizeReturnPath } from './helpers.returnpath.js';
 import type { IRelyingPartyBearerDelivery, IRelyingPartyBearerReturnTargets } from './interfaces.js';
 
-export { RELYING_PARTY_BEARER_MESSAGE_TYPE };
+// the verifier check lives in the import-free contract, which the browser client shares
+export { isPkceVerifier, RELYING_PARTY_BEARER_MESSAGE_TYPE };
 
 export const RELYING_PARTY_BEARER_CLIENT_KINDS: readonly TRelyingPartyBearerClientKind[] = Object.freeze([
   'web',
@@ -20,8 +22,6 @@ export const RELYING_PARTY_BEARER_CLIENT_KINDS: readonly TRelyingPartyBearerClie
 const MAX_RETURN_TARGET_LENGTH = 2_048;
 /** BASE64URL of a SHA-256 digest, without padding (RFC 7636 §4.2). */
 const PKCE_CHALLENGE = /^[A-Za-z0-9_-]{43}$/u;
-/** RFC 7636 §4.1: 43 to 128 unreserved characters. */
-const PKCE_VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/u;
 const CLIENT_STATE = /^[A-Za-z0-9._~-]{1,256}$/u;
 const LOOPBACK_HOSTS: readonly string[] = ['127.0.0.1', '[::1]'];
 /** A private-use scheme is a reverse domain name: it has a dot, and no web scheme has one (RFC 8252 §7.1). */
@@ -33,9 +33,6 @@ export const isBearerClientKind = (valueArg: unknown): valueArg is TRelyingParty
 export const isPkceChallenge = (valueArg: unknown): valueArg is string =>
   typeof valueArg === 'string' && PKCE_CHALLENGE.test(valueArg);
 
-export const isPkceVerifier = (valueArg: unknown): valueArg is string =>
-  typeof valueArg === 'string' && PKCE_VERIFIER.test(valueArg);
-
 export const isBearerClientState = (valueArg: unknown): valueArg is string =>
   typeof valueArg === 'string' && CLIENT_STATE.test(valueArg);