@idp.global/sdk 19.0.0 → 19.1.0

package/ts_relyingparty/interfaces.ts

@@ -1,4 +1,4 @@
-import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcTokenHint } from './classes.idpoidcprovider.js';
+import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcPrompt, TOidcTokenHint } from './classes.idpoidcprovider.js';
 
 /** A session as the application reads it; no token and no sealed value is part of it. */
 export interface IRelyingPartySession {
@@ -35,6 +35,27 @@ export interface IRelyingPartySessionOpening {
   sessionCookie: string;
 }
 
+/**
+ * What `startLogin` carries besides the return path. `intent` is the
+ * application's own text — the invitation a login accepts, the account it
+ * links, the client it authorizes — sealed into the login attempt and handed
+ * to admission (`IRelyingPartyAdmission`) when exactly this login comes back;
+ * it never travels through the browser or the provider.
+ */
+export interface IRelyingPartyLoginOptions {
+  /** at most `RELYING_PARTY_MAX_INTENT_LENGTH` characters, not empty */
+  intent?: string;
+  prompt?: TOidcPrompt;
+}
+
+/** What admission learns about the login besides the provider's completion. */
+export interface IRelyingPartyAdmission {
+  /** the intent `startLogin` was given for this login, opened from its seal; absent when there was none */
+  intent?: string;
+  /** the login attempt the session will name (`IRelyingPartySession.loginAttemptId`) */
+  loginAttemptId: string;
+}
+
 /** The redirect that starts a provider login, and the cookie that binds it to this browser. */
 export interface IRelyingPartyLoginStart {
   authorizationUrl: URL;
@@ -66,7 +87,7 @@ export interface IAuthorityTokenSource {
  * then handed back and the refusal reaches the caller unchanged.
  */
 export interface IRelyingPartyPrincipals {
-  admit(completionArg: IOidcCompletion): Promise<{ principalId: string }>;
+  admit(completionArg: IOidcCompletion, admissionArg: IRelyingPartyAdmission): Promise<{ principalId: string }>;
   /** Whether a principal may act right now; a session of an inactive principal resolves to nothing. */
   isActive(principalIdArg: string): Promise<boolean>;
 }
@@ -78,7 +99,7 @@ export interface IRelyingPartyPrincipals {
  * `principal`. Give either `isActive` or `resolve`, never both.
  */
 export interface IRelyingPartyPrincipalResolver<TPrincipal extends object | undefined> {
-  admit(completionArg: IOidcCompletion): Promise<{ principalId: string }>;
+  admit(completionArg: IOidcCompletion, admissionArg: IRelyingPartyAdmission): Promise<{ principalId: string }>;
   /** The principal object when it may act right now, `null` otherwise; any answer that is not an object (including `false`) resolves the session to nothing. */
   resolve(principalIdArg: string): Promise<TPrincipal | null>;
 }

package/ts_relyingparty/testing.ts

@@ -0,0 +1,306 @@
+import * as plugins from './plugins.js';
+import {
+  OidcCompletionError,
+  OidcRefreshRefusedError,
+  type IOidcAuthorizationOptions,
+  type IOidcCompletion,
+  type IOidcCompletionOptions,
+  type IOidcOrganizationClaim,
+  type IOidcOrganizationObservation,
+  type IOidcProvider,
+  type IOidcRefreshedTokens,
+  type TOidcTokenHint,
+} from './classes.idpoidcprovider.js';
+
+/**
+ * `@idp.global/sdk/relyingparty/testing`: an in-process idp.global for the
+ * tests of an application built on `RelyingPartySessions`. It is a test
+ * double and nothing else — no socket, no persistence, no check a real
+ * provider makes beyond the ones named here — and belongs in test code only.
+ */
+
+/** A person at the double, with the organizations idp.global reports for them. */
+export interface IProviderDoublePersona {
+  /** the stable `sub` */
+  subject: string;
+  displayName?: string;
+  email?: string;
+  /** `email_verified`; `true` when absent, as for an active idp.global account */
+  emailVerified?: boolean;
+  /** the `organizations` claim, and what introspection answers for each organization */
+  organizations?: IOidcOrganizationClaim[];
+}
+
+export interface IProviderDoubleOptions {
+  /** the issuer origin the authorization URLs point at; `https://idp.test` by default */
+  issuer?: string;
+  /** how long an access token lives, in seconds; 3600 by default, `0` names no lifetime */
+  accessTokenLifetimeSeconds?: number;
+  /** the clock every expiry reads; tests step it instead of sleeping */
+  now?: () => number;
+  requestTimeoutSeconds?: number;
+}
+
+interface IIssuedCode {
+  state: string;
+  nonce: string;
+  subject: string;
+}
+
+interface IIssuedToken {
+  subject: string;
+  family: string;
+  /** epoch milliseconds; `0` for no expiry */
+  expiresAt: number;
+  kind: 'access' | 'refresh';
+  revoked: boolean;
+  /** a refresh token that was rotated: using it again is reuse */
+  used: boolean;
+}
+
+const randomToken = (): string => plugins.crypto.randomBytes(18).toString('base64url');
+
+/**
+ * The provider as `IOidcProvider` sees it. A test adds personas, names the one
+ * the next login signs in as (`signInNextAs`), follows the authorization URL
+ * back with `callbackUrlFor`, and changes what idp.global reports live
+ * (`setOrganizationRoles`, `endLoginsOf`). Codes are single use and bound to
+ * their login's state; access tokens introspect for their subject while they
+ * live; refresh tokens rotate, and a superseded one coming back revokes its
+ * whole family, as idp.global's reuse detection does. Every call is recorded,
+ * and each step can be made to fail.
+ */
+export class RelyingPartyProviderDouble implements IOidcProvider {
+  public readonly requestTimeoutSeconds: number;
+  public readonly issuer: string;
+  public accessTokenLifetimeSeconds: number;
+
+  public readonly authorizations: IOidcAuthorizationOptions[] = [];
+  public readonly completions: Array<{ subject: string; state: string }> = [];
+  public readonly revocations: Array<{ token: string; hint: TOidcTokenHint }> = [];
+  public readonly introspections: Array<{ accessToken: string; subject: string; organizationId: string }> = [];
+  public readonly refreshes: string[] = [];
+
+  /** when set, the completion of a login fails with it (an `OidcCompletionError` names its stage) */
+  public completionFailure?: Error;
+  /** when set, every introspection fails with it (an `OidcAuthorityUnavailableError` for an unreachable provider) */
+  public introspectionFailure?: Error;
+  /** when set, every refresh fails with it */
+  public refreshFailure?: Error;
+  /** when set, every revocation fails with it, after it was recorded */
+  public revocationFailure?: Error;
+  /** runs inside an introspection before it answers: a test holds one open with it */
+  public onIntrospect?: (optionsArg: { accessToken: string; subject: string; organizationId: string }) => Promise<void>;
+  /** runs inside a refresh before it answers: a test races a logout with it */
+  public onRefresh?: (refreshTokenArg: string) => Promise<void>;
+
+  readonly #now: () => number;
+  readonly #personas = new Map<string, IProviderDoublePersona>();
+  readonly #codes = new Map<string, IIssuedCode>();
+  readonly #tokens = new Map<string, IIssuedToken>();
+  #next?: string;
+
+  constructor(optionsArg: IProviderDoubleOptions = {}) {
+    this.issuer = new URL(optionsArg.issuer ?? 'https://idp.test').origin;
+    this.accessTokenLifetimeSeconds = optionsArg.accessTokenLifetimeSeconds ?? 3_600;
+    this.requestTimeoutSeconds = optionsArg.requestTimeoutSeconds ?? 10;
+    this.#now = optionsArg.now ?? (() => Date.now());
+  }
+
+  // ---- personas ----
+
+  /** Adds a persona, or replaces the one with its subject. */
+  public addPersona(personaArg: IProviderDoublePersona): void {
+    this.#personas.set(personaArg.subject, {
+      ...personaArg,
+      organizations: (personaArg.organizations ?? []).map((entryArg) => ({ ...entryArg, roles: [...entryArg.roles] })),
+    });
+  }
+
+  public persona(subjectArg: string): IProviderDoublePersona | undefined {
+    return this.#personas.get(subjectArg);
+  }
+
+  /** The persona the next authorization signs in as; a persona given whole is added first. */
+  public signInNextAs(personaArg: string | IProviderDoublePersona): void {
+    if (typeof personaArg !== 'string') {
+      this.addPersona(personaArg);
+    }
+    const subject = typeof personaArg === 'string' ? personaArg : personaArg.subject;
+    if (!this.#personas.has(subject)) {
+      throw new Error(`RelyingPartyProviderDouble: no persona ${subject}; addPersona first`);
+    }
+    this.#next = subject;
+  }
+
+  /**
+   * What idp.global reports for the persona in an organization from now on:
+   * its roles, or `null` when the persona is no member any more. Introspection
+   * reads it at once; the claims of a login are those of its sign-in.
+   */
+  public setOrganizationRoles(subjectArg: string, organizationIdArg: string, rolesArg: string[] | null): void {
+    const persona = this.requirePersona(subjectArg);
+    const organizations = (persona.organizations ?? []).filter((entryArg) => entryArg.id !== organizationIdArg);
+    if (rolesArg) {
+      const known = persona.organizations?.find((entryArg) => entryArg.id === organizationIdArg);
+      organizations.push({
+        id: organizationIdArg,
+        name: known?.name ?? organizationIdArg,
+        slug: known?.slug ?? organizationIdArg,
+        roles: [...rolesArg],
+      });
+    }
+    persona.organizations = organizations;
+  }
+
+  /** Ends every login of the persona at the provider: its tokens neither introspect nor rotate any more. */
+  public endLoginsOf(subjectArg: string): void {
+    for (const token of this.#tokens.values()) {
+      if (token.subject === subjectArg) {
+        token.revoked = true;
+      }
+    }
+  }
+
+  /** Where the provider would send the browser back after the login this authorization URL started. */
+  public callbackUrlFor(authorizationUrlArg: URL, redirectUriArg: URL | string): URL {
+    const callback = new URL(redirectUriArg);
+    callback.searchParams.set('code', authorizationUrlArg.searchParams.get('code') ?? '');
+    callback.searchParams.set('state', authorizationUrlArg.searchParams.get('state') ?? '');
+    return callback;
+  }
+
+  // ---- IOidcProvider ----
+
+  public async init(): Promise<void> {}
+
+  public async buildAuthorizationUrl(optionsArg: IOidcAuthorizationOptions): Promise<URL> {
+    if (!this.#next) {
+      throw new Error('RelyingPartyProviderDouble: name the persona this login signs in as with signInNextAs');
+    }
+    this.authorizations.push({ ...optionsArg });
+    const code = 'code_' + randomToken();
+    this.#codes.set(code, { state: optionsArg.state, nonce: optionsArg.nonce, subject: this.#next });
+    const url = new URL('/oauth/authorize', this.issuer);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('state', optionsArg.state);
+    url.searchParams.set('nonce', optionsArg.nonce);
+    if (optionsArg.prompt) {
+      url.searchParams.set('prompt', optionsArg.prompt);
+    }
+    // what the double hands back at once; a real provider answers it after the login page
+    url.searchParams.set('code', code);
+    return url;
+  }
+
+  public async completeAuthorization(optionsArg: IOidcCompletionOptions): Promise<IOidcCompletion> {
+    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'));
+    }
+    if (issued.nonce !== optionsArg.nonce) {
+      throw new OidcCompletionError('token_validation', new Error('nonce mismatch'));
+    }
+    this.completions.push({ subject: issued.subject, state: issued.state });
+    if (this.completionFailure) {
+      throw this.completionFailure;
+    }
+    const persona = this.requirePersona(issued.subject);
+    const family = randomToken();
+    const access = this.issue('access', issued.subject, family);
+    const refresh = this.issue('refresh', issued.subject, family);
+    return {
+      subject: persona.subject,
+      accessToken: access.token,
+      refreshToken: refresh.token,
+      accessTokenExpiresAt: access.expiresAt,
+      ...(persona.email !== undefined ? { email: persona.email } : {}),
+      emailVerified: persona.emailVerified ?? true,
+      ...(persona.displayName !== undefined ? { displayName: persona.displayName } : {}),
+      organizations: (persona.organizations ?? []).map((entryArg) => ({ ...entryArg, roles: [...entryArg.roles] })),
+    };
+  }
+
+  public async revokeToken(tokenArg: string, hintArg: TOidcTokenHint): Promise<void> {
+    this.revocations.push({ token: tokenArg, hint: hintArg });
+    if (this.revocationFailure) {
+      throw this.revocationFailure;
+    }
+    const token = this.#tokens.get(tokenArg);
+    if (token) {
+      token.revoked = true;
+    }
+  }
+
+  public async introspectOrganization(optionsArg: {
+    accessToken: string;
+    subject: string;
+    organizationId: string;
+  }): Promise<IOidcOrganizationObservation> {
+    this.introspections.push({ ...optionsArg });
+    await this.onIntrospect?.({ ...optionsArg });
+    if (this.introspectionFailure) {
+      throw this.introspectionFailure;
+    }
+    const token = this.#tokens.get(optionsArg.accessToken);
+    const inactive: IOidcOrganizationObservation = { active: false, roles: [], expiresAt: 0 };
+    if (!token || token.kind !== 'access' || !this.isLive(token) || token.subject !== optionsArg.subject) {
+      return inactive;
+    }
+    const membership = this.#personas.get(token.subject)?.organizations?.find((entryArg) => entryArg.id === optionsArg.organizationId);
+    if (!membership) {
+      return inactive;
+    }
+    return { active: true, roles: [...membership.roles].sort(), expiresAt: token.expiresAt };
+  }
+
+  public async refreshTokens(refreshTokenArg: string): Promise<IOidcRefreshedTokens> {
+    this.refreshes.push(refreshTokenArg);
+    await this.onRefresh?.(refreshTokenArg);
+    if (this.refreshFailure) {
+      throw this.refreshFailure;
+    }
+    const token = this.#tokens.get(refreshTokenArg);
+    if (!token || token.kind !== 'refresh' || token.revoked) {
+      throw new OidcRefreshRefusedError(new Error('invalid_grant'));
+    }
+    if (token.used) {
+      // reuse of a superseded refresh token: the family dies
+      for (const entry of this.#tokens.values()) {
+        if (entry.family === token.family) {
+          entry.revoked = true;
+        }
+      }
+      throw new OidcRefreshRefusedError(new Error('invalid_grant'));
+    }
+    token.used = true;
+    const access = this.issue('access', token.subject, token.family);
+    const refresh = this.issue('refresh', token.subject, token.family);
+    return { accessToken: access.token, refreshToken: refresh.token, accessTokenExpiresAt: access.expiresAt };
+  }
+
+  // ---- internals ----
+
+  private requirePersona(subjectArg: string): IProviderDoublePersona {
+    const persona = this.#personas.get(subjectArg);
+    if (!persona) {
+      throw new Error(`RelyingPartyProviderDouble: no persona ${subjectArg}`);
+    }
+    return persona;
+  }
+
+  private issue(kindArg: IIssuedToken['kind'], subjectArg: string, familyArg: string): { token: string; expiresAt: number } {
+    const token = (kindArg === 'access' ? 'at_' : 'rt_') + randomToken();
+    const expiresAt = kindArg === 'access' && this.accessTokenLifetimeSeconds > 0
+      ? this.#now() + this.accessTokenLifetimeSeconds * 1_000
+      : 0;
+    this.#tokens.set(token, { subject: subjectArg, family: familyArg, expiresAt, kind: kindArg, revoked: false, used: false });
+    return { token, expiresAt };
+  }
+
+  private isLive(tokenArg: IIssuedToken): boolean {
+    return !tokenArg.revoked && (tokenArg.expiresAt === 0 || tokenArg.expiresAt > this.#now());
+  }
+}