@idp.global/sdk 19.4.0 → 19.6.0

package/ts_relyingparty/classes.rpmodels.ts

@@ -129,7 +129,9 @@ export class RelyingPartyLoginAttemptDoc extends plugins.nosqldb.SmartDataDbDoc<
 /**
  * The single-use code a bearer login hands its client. Only the hash of the
  * code is stored; the code is bound to the client's S256 challenge, lives at
- * most a minute and is consumed by one conditional update.
+ * most a minute and is consumed by one conditional update. The `sessionId`
+ * index is what the session sweep and the erase delete a session's hand-offs
+ * by.
  */
 export class RelyingPartyBearerHandoffDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartyBearerHandoffDoc, RelyingPartyBearerHandoffDoc> {
   @plugins.nosqldb.unI()
@@ -141,6 +143,7 @@ export class RelyingPartyBearerHandoffDoc extends plugins.nosqldb.SmartDataDbDoc
 
   /** the session the login opened; the code is its only way out */
   @plugins.nosqldb.svDb()
+  @plugins.nosqldb.index()
   public sessionId: string = '';
 
   @plugins.nosqldb.svDb()
@@ -163,8 +166,9 @@ export class RelyingPartyBearerHandoffDoc extends plugins.nosqldb.SmartDataDbDoc
  * One generation of a bearer session's tokens: an access token and the
  * refresh token that replaces both. Only hashes are stored. Exactly one
  * generation of a session is current (`rotatedAt` `null`); a rotated one is
- * kept until the session expires, so its refresh token coming back is
- * recognized as reuse.
+ * kept until its session is swept, so its refresh token coming back is
+ * recognized as reuse. The `sessionId` index is what the session sweep and
+ * the erase delete a session's generations by.
  */
 export class RelyingPartyBearerTokenDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartyBearerTokenDoc, RelyingPartyBearerTokenDoc> {
   @plugins.nosqldb.unI()
@@ -177,6 +181,7 @@ export class RelyingPartyBearerTokenDoc extends plugins.nosqldb.SmartDataDbDoc<R
   public refreshTokenHash: string = '';
 
   @plugins.nosqldb.svDb()
+  @plugins.nosqldb.index()
   public sessionId: string = '';
 
   @plugins.nosqldb.svDb()
@@ -190,9 +195,27 @@ export class RelyingPartyBearerTokenDoc extends plugins.nosqldb.SmartDataDbDoc<R
   @plugins.nosqldb.index()
   public expiresAt: number = 0;
 
-  /** `null` while this generation is current; when its refresh token was spent otherwise */
+  /** `null` while this generation is current; when its refresh token was spent, or the generation revoked, otherwise */
   @plugins.nosqldb.svDb()
   public rotatedAt: number | null = null;
+
+  /**
+   * When its access token or its refresh token was first presented; `null`
+   * until then (and on a generation stored before 19.6.0). A rotated
+   * generation whose successor was never presented may come back within the
+   * reuse grace window as a lost answer.
+   */
+  @plugins.nosqldb.svDb()
+  public firstUsedAt: number | null = null;
+
+  /**
+   * The generation that replaced this one: set by its rotation and moved to
+   * the new one when a lost answer is issued again. `null` on a current
+   * generation, on one that was revoked unpresented, and on one stored before
+   * 19.6.0.
+   */
+  @plugins.nosqldb.svDb()
+  public successorId: string | null = null;
 }
 
 export const RELYING_PARTY_DEFAULT_COLLECTION_NAMES = {

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);
 

package/ts_relyingparty/helpers.cookies.ts

@@ -3,6 +3,12 @@ export interface ICookieOptions {
   maxAgeSeconds?: number;
   sameSite?: 'Lax' | 'Strict' | 'None';
   secure?: boolean;
+  /**
+   * `Partitioned` (CHIPS): the browser keeps the cookie per top-level site, so
+   * a page framed on another site gets a cookie jar of its own there. Needs
+   * `secure`; a cookie set partitioned is also cleared partitioned.
+   */
+  partitioned?: boolean;
 }
 
 // Control characters, space, DEL and the cookie delimiters are never valid.
@@ -60,6 +66,13 @@ export const serializeCookie = (
   if (optionsArg.sameSite) {
     parts.push('SameSite=' + optionsArg.sameSite);
   }
+  if (optionsArg.partitioned) {
+    if (!optionsArg.secure) {
+      // browsers drop a partitioned cookie that is not set Secure
+      throw new Error('A Partitioned cookie needs Secure');
+    }
+    parts.push('Partitioned');
+  }
   if (optionsArg.maxAgeSeconds !== undefined) {
     if (!Number.isSafeInteger(optionsArg.maxAgeSeconds) || optionsArg.maxAgeSeconds < 0) {
       throw new Error('Invalid cookie max age');

package/ts_relyingparty/interfaces.ts

@@ -2,9 +2,13 @@ import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcPrompt, TOidcTo
 import type { TRelyingPartyBearerClientKind } from './contract.bearer.js';
 
 export type {
+  IRelyingPartyBearerClaimRequest,
   IRelyingPartyBearerErrorAnswer,
+  IRelyingPartyBearerLoginQuery,
   IRelyingPartyBearerLogoutAnswer,
+  IRelyingPartyBearerLogoutRequest,
   IRelyingPartyBearerMessage,
+  IRelyingPartyBearerRefreshRequest,
   IRelyingPartyBearerSessionAnswer,
   IRelyingPartyBearerSessionInfo,
   IRelyingPartyBearerTokenAnswer,
@@ -41,6 +45,27 @@ export interface IResolvedRelyingPartySession<TPrincipal extends object | undefi
   csrfToken: string;
 }
 
+/**
+ * How the session cookie and the login's intent cookie are sent across
+ * sites; one policy for both, on every cookie they are set and cleared with.
+ */
+export interface IRelyingPartyCookiePolicy {
+  /**
+   * `Lax`, the default: the browser sends the cookies with this origin's own
+   * requests and with a top-level navigation to it, never into a frame on
+   * another site. `None`: also for a page of this origin framed on another
+   * site; it needs an https `publicOrigin`, because a `SameSite=None` cookie
+   * must be `Secure`.
+   */
+  sameSite?: 'Lax' | 'None';
+  /**
+   * `Partitioned` (CHIPS): the browser keeps the cookies per top-level site,
+   * so the framed application has a jar of its own under each site that frames
+   * it. Only with `sameSite: 'None'`. `false` by default.
+   */
+  partitioned?: boolean;
+}
+
 /** A session just opened: the answer, the CSRF token and the `Set-Cookie` value that carries it. */
 export interface IRelyingPartySessionOpening {
   session: IRelyingPartySession;
@@ -115,6 +140,15 @@ export interface IRelyingPartyBearerOptions {
   returnTargets: IRelyingPartyBearerReturnTargets;
   /** how long an access token lives, in seconds; 900 by default, never past its session */
   accessTokenMaxAgeSeconds?: number;
+  /**
+   * How long after a rotation its spent refresh token may come back as a lost
+   * answer instead of reuse, in whole seconds: 60 by default, 0 turns it off,
+   * at most 300. Within it, a spent refresh token whose successor was never
+   * presented (neither its access token nor its refresh token) revokes that
+   * successor and answers a new pair; once the successor was presented, or
+   * after the window, it is reuse and ends the session.
+   */
+  refreshReuseGraceSeconds?: number;
 }
 
 /** What a bearer client sends to start its login. Every field is checked as untrusted input. */
@@ -156,6 +190,37 @@ export interface IRelyingPartyBearerHandoff {
   expiresAt: number;
 }
 
+/**
+ * A bearer session the application opened for a device it paired
+ * (`openBearerHandoff`): the session, which has no provider login of its own
+ * (`idpSubject` and `loginAttemptId` are absent), and the single-use code the
+ * device claims at `bearer/claim` with the verifier of its challenge. The
+ * code is no token; only its hash is stored.
+ */
+export interface IRelyingPartyBearerHandoffOpening {
+  session: IRelyingPartySession;
+  code: string;
+  /** epoch milliseconds, at most `BEARER_HANDOFF_MAX_AGE_SECONDS` after the opening and never past the session */
+  expiresAt: number;
+}
+
+/**
+ * What `eraseSessionsOfPrincipal` removed of one principal: the sessions it
+ * ended first, and the rows it deleted.
+ */
+export interface IRelyingPartySessionsErasure {
+  /** sessions not revoked yet (an expired one too) that it ended, each with `onSessionEnded` and its provider tokens handed back */
+  endedSessions: number;
+  /** session rows, live or ended */
+  deletedSessions: number;
+  /** the sign-in transactions the provider sessions came out of */
+  deletedLoginAttempts: number;
+  /** bearer hand-offs, claimed or not */
+  deletedBearerHandoffs: number;
+  /** bearer token generations, current or rotated */
+  deletedBearerTokens: number;
+}
+
 /**
  * The relying party's own tokens of a bearer session. The refresh token
  * rotates on every use; a rotated one coming back ends the session.
@@ -275,6 +340,8 @@ export type TRelyingPartyEventName =
   | 'session_sweep_failed'
   /** a bearer hand-off code or refresh token came back after its use; `reason` names which, the session ended */
   | 'bearer_credential_reused'
+  /** a spent refresh token came back within `refreshReuseGraceSeconds` before its successor was presented: the successor was revoked and a new pair issued */
+  | 'bearer_refresh_reissued'
   /** an application hook threw; the step it belonged to ran on regardless */
   | 'hook_failed'
   /** a session whose opening failed could not be revoked; its provider tokens went back anyway */
@@ -298,20 +365,22 @@ export interface IRelyingPartyHooks {
    * A provider login opened a session, linked to its attempt. Runs before the
    * login answers; a throw fails the login: the session is revoked, the
    * provider tokens are handed back and the original error is rethrown.
+   * `delivery` is where a bearer login's outcome goes (its client kind, return
+   * target and the client's `state`); a cookie login has none.
    */
-  onProviderSessionOpened?(eventArg: { session: IRelyingPartySession }): Promise<void>;
+  onProviderSessionOpened?(eventArg: { session: IRelyingPartySession; delivery?: IRelyingPartyBearerDelivery }): Promise<void>;
   /**
    * A session ended, or a caller tried to end one that was already over
    * (`revokedHere: false`). Close its live connections when `revokedHere`,
    * drop cached authority either way. Must not wait. A throw (or a rejected
    * promise) is reported as a `hook_failed` event and never stops the end:
-   * the provider tokens go back regardless.
+   * the provider tokens go back regardless. An end that revoked the session
+   * here names its principal (`principalId`); one that found it over already
+   * does not.
    */
-  onSessionEnded?(eventArg: {
-    sessionId: string;
-    reason: TRelyingPartySessionEndReason;
-    revokedHere: boolean;
-  }): void;
+  onSessionEnded?(eventArg:
+    | { sessionId: string; reason: TRelyingPartySessionEndReason; revokedHere: true; principalId: string }
+    | { sessionId: string; reason: TRelyingPartySessionEndReason; revokedHere: false }): void;
   /**
    * Structured diagnostics; the default writes one JSON line to
    * `console.error`. A throwing sink never interrupts the step that reported:

package/ts_relyingparty/testing.ts

@@ -231,16 +231,20 @@ export class RelyingPartyProviderDouble implements IOidcProvider {
 
   public async completeAuthorization(optionsArg: IOidcCompletionOptions): Promise<IOidcCompletion> {
     if (!this.#discovered) {
-      throw new OidcCompletionError('token_exchange', notDiscovered());
+      throw new OidcCompletionError('token_exchange', notDiscovered(), { code: 'provider_unreachable' });
     }
     const code = optionsArg.callbackUrl.searchParams.get('code') ?? '';
     const issued = this.#codes.get(code);
     this.#codes.delete(code);
     if (!issued || issued.state !== optionsArg.state) {
-      throw new OidcCompletionError('token_exchange', new Error('unknown, used or foreign code'));
+      // what idp.global's token endpoint answers for such a code
+      throw new OidcCompletionError('token_exchange', new Error('unknown, used or foreign code'), {
+        code: 'token_exchange_refused',
+        oauthError: 'invalid_grant',
+      });
     }
     if (issued.nonce !== optionsArg.nonce) {
-      throw new OidcCompletionError('token_validation', new Error('nonce mismatch'));
+      throw new OidcCompletionError('token_validation', new Error('nonce mismatch'), { code: 'login_mismatch' });
     }
     this.completions.push({ subject: issued.subject, state: issued.state });
     if (this.completionFailure) {