@idp.global/sdk 18.1.0 → 18.2.0

package/ts_relyingparty/classes.relyingpartysessions.ts

@@ -22,12 +22,13 @@ import type {
   IProviderToken,
   IRelyingPartyEvent,
   IRelyingPartyHooks,
+  IRelyingPartyLiveSession,
   IRelyingPartyLoginStart,
-  IRelyingPartyPrincipals,
   IRelyingPartySession,
   IRelyingPartySessionOpening,
   IResolvedRelyingPartySession,
   TLoginCallbackStage,
+  TRelyingPartyPrincipals,
   TRelyingPartySessionEndReason,
 } from './interfaces.js';
 
@@ -57,9 +58,13 @@ export const ACCESS_TOKEN_REFRESH_SKEW_MS = 60_000;
  */
 export const REFRESH_LOCK_MARGIN_MS = 20_000;
 
-export interface IRelyingPartySessionsOptions {
+export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefined = undefined> {
   models: IRelyingPartyModels;
-  principals: IRelyingPartyPrincipals;
+  /**
+   * `isActive` principals, or a `resolve` that answers the principal itself;
+   * its answer is then the `principal` of every live session.
+   */
+  principals: TRelyingPartyPrincipals<TPrincipal>;
   /** absent: no provider login; sessions are opened by the application only */
   provider?: IOidcProvider;
   /** the application's public origin, e.g. `https://app.example`; cookies are `Secure` exactly on https */
@@ -122,9 +127,13 @@ const cookieNameFor = (
  *
  * Nothing here runs on a timer: expired login attempts are swept when the next
  * login starts, and the only timer — the revocation budget — is unreferenced
- * and cleared on every path.
+ * and cleared on every path. 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`.
  */
-export class RelyingPartySessions implements IAuthorityTokenSource {
+export class RelyingPartySessions<TPrincipal extends object | undefined = undefined> implements IAuthorityTokenSource {
   public readonly publicOrigin: string;
   public readonly secureCookies: boolean;
   public readonly sessionCookieName: string;
@@ -132,7 +141,9 @@ export class RelyingPartySessions implements IAuthorityTokenSource {
   public readonly loginPathPrefix: string;
   public readonly sessionMaxAgeSeconds: number;
   readonly #models: IRelyingPartyModels;
-  readonly #principals: IRelyingPartyPrincipals;
+  readonly #admit: TRelyingPartyPrincipals<TPrincipal>['admit'];
+  /** the principal of a session when it may act right now, `null` otherwise */
+  readonly #activePrincipal: (principalIdArg: string) => Promise<{ principal: TPrincipal } | null>;
   readonly #provider?: IOidcProvider;
   readonly #secretBox: SecretBox;
   readonly #csrfKey: Buffer;
@@ -142,7 +153,7 @@ export class RelyingPartySessions implements IAuthorityTokenSource {
   /** one rotation per session in this process, however many requests need it at once */
   readonly #refreshesInFlight = new Map<string, Promise<IProviderToken>>();
 
-  constructor(optionsArg: IRelyingPartySessionsOptions) {
+  constructor(optionsArg: IRelyingPartySessionsOptions<TPrincipal>) {
     const origin = new URL(optionsArg.publicOrigin);
     if (origin.origin !== optionsArg.publicOrigin) {
       throw new Error('publicOrigin must be a bare origin such as https://app.example');
@@ -175,7 +186,34 @@ export class RelyingPartySessions implements IAuthorityTokenSource {
     }
     this.sessionMaxAgeSeconds = maxAge;
     this.#models = optionsArg.models;
-    this.#principals = optionsArg.principals;
+    const principals = optionsArg.principals;
+    const resolve: unknown = principals && Reflect.get(principals, 'resolve');
+    const isActive: unknown = principals && Reflect.get(principals, 'isActive');
+    if (!principals || typeof principals.admit !== 'function') {
+      throw new Error('principals needs an admit function');
+    }
+    if ((typeof resolve === 'function') === (typeof isActive === 'function')) {
+      throw new Error('principals needs exactly one of isActive and resolve');
+    }
+    this.#admit = (completionArg) => principals.admit(completionArg);
+    // choose the form by the same test the check above used, so a present but
+    // undefined `resolve` (a spread, a widened object) selects `isActive`
+    if (typeof resolve === 'function') {
+      const resolvePrincipal = resolve as (principalIdArg: string) => Promise<TPrincipal | null | undefined>;
+      this.#activePrincipal = async (principalIdArg) => {
+        const principal = await resolvePrincipal.call(principals, principalIdArg);
+        // only an object is a principal: null, undefined and any primitive such as
+        // `false` (an easy slip when moving from isActive) mean "not active"
+        return typeof principal === 'object' && principal !== null ? { principal } : null;
+      };
+    } else {
+      const principalIsActive = isActive as (principalIdArg: string) => Promise<boolean>;
+      this.#activePrincipal = async (principalIdArg) =>
+        (await principalIsActive.call(principals, principalIdArg))
+          // the isActive form exists only while TPrincipal is `undefined`
+          ? { principal: undefined as TPrincipal }
+          : null;
+    }
     this.#provider = optionsArg.provider;
     this.#secretBox = new SecretBox(optionsArg.sessionEncryptionKey);
     this.#csrfKey = Buffer.from(optionsArg.csrfKey);
@@ -220,7 +258,7 @@ export class RelyingPartySessions implements IAuthorityTokenSource {
   /** The live session behind the session cookie, or `null`. A read touches it at most once a minute. */
   public async resolveCookieSession(
     cookieHeaderArg: string | null | undefined,
-  ): Promise<IResolvedRelyingPartySession | null> {
+  ): Promise<IResolvedRelyingPartySession<TPrincipal> | null> {
     const token = parseCookies(cookieHeaderArg).get(this.sessionCookieName);
     if (!token || token.length > MAX_COOKIE_TOKEN_LENGTH) {
       return null;
@@ -230,7 +268,7 @@ export class RelyingPartySessions implements IAuthorityTokenSource {
     if (!live) {
       return null;
     }
-    return { session: this.snapshot(live), csrfToken: this.csrfTokenOf(token) };
+    return { session: this.snapshot(live.document), principal: live.principal, csrfToken: this.csrfTokenOf(token) };
   }
 
   /**
@@ -239,11 +277,16 @@ export class RelyingPartySessions implements IAuthorityTokenSource {
    * with. What a pinned socket connection runs per request.
    */
   public async revalidateSession(sessionIdArg: string): Promise<IRelyingPartySession | null> {
+    return (await this.revalidateLiveSession(sessionIdArg))?.session ?? null;
+  }
+
+  /** `revalidateSession`, answering the principal the same read resolved as well. */
+  public async revalidateLiveSession(sessionIdArg: string): Promise<IRelyingPartyLiveSession<TPrincipal> | null> {
     if (typeof sessionIdArg !== 'string' || sessionIdArg.length === 0) {
       return null;
     }
     const live = await this.liveSession(await this.#models.Session.getInstance({ id: sessionIdArg }));
-    return live ? this.snapshot(live) : null;
+    return live ? { session: this.snapshot(live.document), principal: live.principal } : null;
   }
 
   /** Whether a session is live right now, without touching it; what a sweep asks. */
@@ -255,10 +298,11 @@ export class RelyingPartySessions implements IAuthorityTokenSource {
     if (!session || session.revokedAt !== undefined || session.expiresAt <= this.#now()) {
       return false;
     }
-    return this.#principals.isActive(session.userId);
+    return (await this.#activePrincipal(session.userId)) !== null;
   }
 
-  public validateCsrf(resolvedArg: IResolvedRelyingPartySession, candidateArg: unknown): boolean {
+  /** Whether a candidate is the CSRF token of a resolved (or just opened) session, compared in constant time. */
+  public validateCsrf(resolvedArg: { csrfToken: string }, candidateArg: unknown): boolean {
     return typeof candidateArg === 'string' && timingSafeEqualString(resolvedArg.csrfToken, candidateArg);
   }
 
@@ -412,7 +456,7 @@ export class RelyingPartySessions implements IAuthorityTokenSource {
         pkceVerifier: this.#secretBox.open(attempt.sealedPkceVerifier),
       });
       stage = 'principal_admission';
-      const { principalId } = await this.#principals.admit(completion);
+      const { principalId } = await this.#admit(completion);
       stage = 'session_persistence';
       return await this.createProviderSession(attempt, principalId, completion);
     } catch (error) {
@@ -693,13 +737,16 @@ export class RelyingPartySessions implements IAuthorityTokenSource {
     };
   }
 
-  /** A session document that is live right now with an active principal, touched at most once a minute. */
-  private async liveSession(sessionArg: RelyingPartySessionDoc | null): Promise<RelyingPartySessionDoc | null> {
+  /** A session document that is live right now with its active principal, touched at most once a minute. */
+  private async liveSession(
+    sessionArg: RelyingPartySessionDoc | null,
+  ): Promise<{ document: RelyingPartySessionDoc; principal: TPrincipal } | null> {
     const now = this.#now();
     if (!sessionArg || sessionArg.revokedAt !== undefined || sessionArg.expiresAt <= now) {
       return null;
     }
-    if (!(await this.#principals.isActive(sessionArg.userId))) {
+    const active = await this.#activePrincipal(sessionArg.userId);
+    if (!active) {
       return null;
     }
     if (now - sessionArg.lastSeenAt > SESSION_TOUCH_INTERVAL_MS) {
@@ -714,7 +761,7 @@ export class RelyingPartySessions implements IAuthorityTokenSource {
       }
       sessionArg.lastSeenAt = now;
     }
-    return sessionArg;
+    return { document: sessionArg, principal: active.principal };
   }
 
   private async createProviderSession(

package/ts_relyingparty/classes.rpmodels.ts

@@ -1,4 +1,5 @@
 import * as plugins from './plugins.js';
+import { RelyingPartyDatabaseUnavailableError } from './classes.errors.js';
 
 /**
  * One browser session of a relying party. The persisted field names, their
@@ -106,7 +107,13 @@ export const RELYING_PARTY_DEFAULT_COLLECTION_NAMES = {
 } as const;
 
 export interface IRelyingPartyModelsOptions {
-  db: plugins.nosqldb.SmartdataDb;
+  /**
+   * The database, or a function that answers it once it exists. The function
+   * is called on every use of a model — never while the models or
+   * `RelyingPartySessions` are constructed — so an application creates both
+   * before its database connects and binds the database it connects later.
+   */
+  db: plugins.nosqldb.SmartdataDb | (() => plugins.nosqldb.SmartdataDb);
   /**
    * The persisted collection names. An application that already stores these
    * documents names its existing collections here.
@@ -125,21 +132,38 @@ export interface IRelyingPartyModels {
 /**
  * Binds the two relying-party models to one database. Each call declares its
  * own model classes, so several databases — and several applications in one
- * process — never share a binding.
+ * process — never share a binding. A deferred `db` is resolved on every use,
+ * the way `@Collection(() => db)` resolves it; a use before it answers a
+ * `SmartdataDb` throws `RelyingPartyDatabaseUnavailableError`.
  */
 export const createRelyingPartyModels = (optionsArg: IRelyingPartyModelsOptions): IRelyingPartyModels => {
-  const db = optionsArg.db;
-  if (!(db instanceof plugins.nosqldb.SmartdataDb)) {
-    throw new Error('createRelyingPartyModels needs a SmartdataDb of @lossless.org/client/nosqldb');
+  const dbOption = optionsArg.db;
+  if (!(dbOption instanceof plugins.nosqldb.SmartdataDb) && typeof dbOption !== 'function') {
+    throw new Error('createRelyingPartyModels needs a SmartdataDb of @lossless.org/client/nosqldb or a function answering one');
   }
+  const resolveDb = (): plugins.nosqldb.SmartdataDb => {
+    if (dbOption instanceof plugins.nosqldb.SmartdataDb) {
+      return dbOption;
+    }
+    let resolved: unknown;
+    try {
+      resolved = dbOption();
+    } catch (error) {
+      throw new RelyingPartyDatabaseUnavailableError(error);
+    }
+    if (!(resolved instanceof plugins.nosqldb.SmartdataDb)) {
+      throw new RelyingPartyDatabaseUnavailableError();
+    }
+    return resolved;
+  };
   const sessions = optionsArg.collectionNames?.sessions ?? RELYING_PARTY_DEFAULT_COLLECTION_NAMES.sessions;
   const loginAttempts = optionsArg.collectionNames?.loginAttempts
     ?? RELYING_PARTY_DEFAULT_COLLECTION_NAMES.loginAttempts;
 
-  @plugins.nosqldb.Collection(() => db, { collectionName: sessions })
+  @plugins.nosqldb.Collection(resolveDb, { collectionName: sessions })
   class BoundSessionDoc extends RelyingPartySessionDoc {}
 
-  @plugins.nosqldb.Collection(() => db, { collectionName: loginAttempts })
+  @plugins.nosqldb.Collection(resolveDb, { collectionName: loginAttempts })
   class BoundLoginAttemptDoc extends RelyingPartyLoginAttemptDoc {}
 
   return { Session: BoundSessionDoc, LoginAttempt: BoundLoginAttemptDoc };

package/ts_relyingparty/classes.socketbinding.ts

@@ -11,6 +11,15 @@ export type TRelyingPartySocketTransport = Pick<
 
 export type TRelyingPartySocketConnection = plugins.typedsocket.ISmartServeConnectionWrapper;
 
+/** The SmartServe WebSocket peer underneath a connection, as a TypedSocket server hands it out. */
+export type TRelyingPartySocketPeer = TRelyingPartySocketConnection['peer'];
+
+/** A connection wrapper or its peer; `TypedSocket.setServerTag` takes either. */
+export type TRelyingPartySocketTarget = TRelyingPartySocketConnection | TRelyingPartySocketPeer;
+
+const peerOf = (targetArg: TRelyingPartySocketTarget): TRelyingPartySocketPeer =>
+  'peer' in targetArg ? targetArg.peer : targetArg;
+
 /** What a browser connection is pinned to for its whole life; no cookie and no CSRF token is kept. */
 export interface IRelyingPartyPinnedSession {
   sessionId: string;
@@ -28,8 +37,8 @@ export type TRelyingPartySocketRegistration =
   | { registered: true; pinned: IRelyingPartyPinnedSession; expiresAt: number }
   | { registered: false; refusal: IRelyingPartySocketRefusal };
 
-export interface IRelyingPartySocketBindingOptions {
-  sessions: RelyingPartySessions;
+export interface IRelyingPartySocketBindingOptions<TPrincipal extends object | undefined = undefined> {
+  sessions: RelyingPartySessions<TPrincipal>;
   /** the transport typedserver created; `undefined` before the server runs */
   transport: () => TRelyingPartySocketTransport | undefined;
   /** the server-owned tag prefix that finds the connections of a session */
@@ -45,20 +54,20 @@ export interface IRelyingPartySocketBindingOptions {
  * request. Connection limits, rate limits and sweeps belong to the
  * application's socket gate.
  */
-export class RelyingPartySocketBinding {
-  readonly #sessions: RelyingPartySessions;
+export class RelyingPartySocketBinding<TPrincipal extends object | undefined = undefined> {
+  readonly #sessions: RelyingPartySessions<TPrincipal>;
   readonly #transport: () => TRelyingPartySocketTransport | undefined;
   public readonly tagPrefix: string;
 
-  constructor(optionsArg: IRelyingPartySocketBindingOptions) {
+  constructor(optionsArg: IRelyingPartySocketBindingOptions<TPrincipal>) {
     this.#sessions = optionsArg.sessions;
     this.#transport = optionsArg.transport;
     this.tagPrefix = optionsArg.tagPrefix ?? 'idp_rp_session:';
   }
 
-  /** The upgrade headers a connection arrived with. */
-  public upgradeOf(connectionArg: TRelyingPartySocketConnection): { origin: string | null; cookie: string | null } {
-    const headers = connectionArg.peer.context.headers;
+  /** The upgrade headers a connection (or its peer) arrived with. */
+  public upgradeOf(targetArg: TRelyingPartySocketTarget): { origin: string | null; cookie: string | null } {
+    const headers = peerOf(targetArg).context.headers;
     return { origin: headers.get('origin'), cookie: headers.get('cookie') };
   }
 
@@ -99,31 +108,36 @@ export class RelyingPartySocketBinding {
     return this.tagPrefix + sessionIdArg;
   }
 
-  /** Tags a connection with its session; throws when the transport is not running or the connection is gone. */
-  public tagConnection(connectionArg: TRelyingPartySocketConnection, sessionIdArg: string): void {
+  /**
+   * Tags a connection — its wrapper or its peer — with its session; throws
+   * when the transport is not running or the connection is gone.
+   */
+  public tagConnection(targetArg: TRelyingPartySocketTarget, sessionIdArg: string): void {
     const transport = this.#transport();
     if (!transport) {
       throw new Error('The socket transport is not running');
     }
-    transport.setServerTag(connectionArg, this.tagOf(sessionIdArg));
+    transport.setServerTag(targetArg, this.tagOf(sessionIdArg));
   }
 
   /**
    * The pinned session as it stands right now: re-read, live, its principal
-   * active and unchanged, touched under the liveness it was read with. The
+   * active and unchanged (and resolved, with `principals.resolve`), touched
+   * under the liveness it was read with. The
    * browser keeps proving itself with its CSRF token, compared against the
    * hash the registration kept. Nothing of this is cached.
    */
   public async revalidate(
     pinnedArg: IRelyingPartyPinnedSession,
-  ): Promise<{ session: IRelyingPartySession; verifyCsrf(candidateArg: unknown): boolean } | null> {
-    const session = await this.#sessions.revalidateSession(pinnedArg.sessionId);
-    if (!session || session.principalId !== pinnedArg.principalId) {
+  ): Promise<{ session: IRelyingPartySession; principal: TPrincipal; verifyCsrf(candidateArg: unknown): boolean } | null> {
+    const live = await this.#sessions.revalidateLiveSession(pinnedArg.sessionId);
+    if (!live || live.session.principalId !== pinnedArg.principalId) {
       return null;
     }
     const expectedHash = pinnedArg.csrfTokenHash;
     return {
-      session,
+      session: live.session,
+      principal: live.principal,
       verifyCsrf: (candidateArg) =>
         typeof candidateArg === 'string'
         && expectedHash.length > 0

package/ts_relyingparty/interfaces.ts

@@ -13,14 +13,25 @@ export interface IRelyingPartySession {
   loginAttemptId?: string;
 }
 
-/** A live session behind a cookie, with the CSRF token derived for it. */
-export interface IResolvedRelyingPartySession {
+/**
+ * A live session with the principal it acts as. `principal` is what
+ * `principals.resolve` answered for it in the same read; with `isActive`
+ * principals it is `undefined`.
+ */
+export interface IRelyingPartyLiveSession<TPrincipal extends object | undefined = undefined> {
   session: IRelyingPartySession;
+  principal: TPrincipal;
+}
+
+/** A live session behind a cookie, with its principal and the CSRF token derived for it. */
+export interface IResolvedRelyingPartySession<TPrincipal extends object | undefined = undefined> extends IRelyingPartyLiveSession<TPrincipal> {
   csrfToken: string;
 }
 
 /** A session just opened: the answer, the CSRF token and the `Set-Cookie` value that carries it. */
-export interface IRelyingPartySessionOpening extends IResolvedRelyingPartySession {
+export interface IRelyingPartySessionOpening {
+  session: IRelyingPartySession;
+  csrfToken: string;
   sessionCookie: string;
 }
 
@@ -60,6 +71,27 @@ export interface IRelyingPartyPrincipals {
   isActive(principalIdArg: string): Promise<boolean>;
 }
 
+/**
+ * Principals that answer the principal itself instead of a yes or no, so a
+ * request reads its user once: `resolve` answers the principal when it may act
+ * right now and `null` otherwise, and every live session carries the answer as
+ * `principal`. Give either `isActive` or `resolve`, never both.
+ */
+export interface IRelyingPartyPrincipalResolver<TPrincipal extends object | undefined> {
+  admit(completionArg: IOidcCompletion): 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>;
+}
+
+/**
+ * What `RelyingPartySessions` accepts as its principals: a resolver whose
+ * principal type every live session carries, or — only while that type is
+ * left `undefined` — the `isActive` form.
+ */
+export type TRelyingPartyPrincipals<TPrincipal extends object | undefined> =
+  | IRelyingPartyPrincipalResolver<TPrincipal>
+  | (undefined extends TPrincipal ? IRelyingPartyPrincipals : never);
+
 export type TRelyingPartySessionEndReason =
   /** the application or the user ended it */
   | 'logout'