@idp.global/sdk 18.0.1 → 18.2.0

package/ts_relyingparty/classes.rpmodels.ts

@@ -0,0 +1,170 @@
+import * as plugins from './plugins.js';
+import { RelyingPartyDatabaseUnavailableError } from './classes.errors.js';
+
+/**
+ * One browser session of a relying party. The persisted field names, their
+ * types and the index declarations are the ones nevermind.finance has stored
+ * under `SessionDoc` since before this module existed, so its collection is
+ * read and written unchanged.
+ */
+export class RelyingPartySessionDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartySessionDoc, RelyingPartySessionDoc> {
+  @plugins.nosqldb.unI()
+  public id: string = '';
+
+  /** sha256 of the cookie token; the token itself is never stored */
+  @plugins.nosqldb.unI()
+  public tokenHash: string = '';
+
+  /** the application's principal (user) this session acts as */
+  @plugins.nosqldb.svDb()
+  @plugins.nosqldb.index()
+  public userId: string = '';
+
+  @plugins.nosqldb.svDb()
+  public createdAt: number = 0;
+
+  @plugins.nosqldb.svDb()
+  public lastSeenAt: number = 0;
+
+  @plugins.nosqldb.svDb()
+  public expiresAt: number = 0;
+
+  /** absent while the session is valid */
+  @plugins.nosqldb.svDb()
+  public revokedAt?: number;
+
+  /** the provider subject of a provider login; absent for a session the application opened itself */
+  @plugins.nosqldb.svDb()
+  public idpSubject?: string;
+
+  /** the login attempt this session came out of; finalize matches it */
+  @plugins.nosqldb.svDb()
+  public loginAttemptId?: string;
+
+  /** sealed with the session encryption key; only the server ever sees the tokens */
+  @plugins.nosqldb.svDb()
+  public sealedAccessToken?: string;
+
+  @plugins.nosqldb.svDb()
+  public sealedRefreshToken?: string;
+
+  /** when the sealed access token dies, epoch milliseconds; `0` when the provider named no lifetime */
+  @plugins.nosqldb.svDb()
+  public accessTokenExpiresAt?: number;
+
+  /** until when one replica holds the right to rotate this session's tokens, epoch milliseconds */
+  @plugins.nosqldb.svDb()
+  public refreshLockUntil?: number;
+}
+
+/**
+ * One browser's sign-in transaction: the state hash the callback is matched
+ * against, the binding to the browser that started it, the sealed PKCE
+ * verifier and the return path. Consumed exactly once by a conditional update.
+ * Field names and indexes are the ones nevermind.finance stores under
+ * `LoginAttemptDoc`.
+ */
+export class RelyingPartyLoginAttemptDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartyLoginAttemptDoc, RelyingPartyLoginAttemptDoc> {
+  @plugins.nosqldb.unI()
+  public id: string = '';
+
+  /** sha256 of the `state` parameter; the parameter itself is never stored */
+  @plugins.nosqldb.unI()
+  public stateHash: string = '';
+
+  /** sha256 of the intent cookie value; binds the callback to the browser that started it */
+  @plugins.nosqldb.unI()
+  public bindingTokenHash: string = '';
+
+  @plugins.nosqldb.svDb()
+  public sealedPkceVerifier: string = '';
+
+  @plugins.nosqldb.svDb()
+  public nonce: string = '';
+
+  /** same-origin path the browser returns to */
+  @plugins.nosqldb.svDb()
+  public returnPath: string = '/';
+
+  @plugins.nosqldb.svDb()
+  public createdAt: number = 0;
+
+  @plugins.nosqldb.svDb()
+  public expiresAt: number = 0;
+
+  /** absent until the callback consumes the attempt; `null` matches "not consumed" in a filter */
+  @plugins.nosqldb.svDb()
+  public consumedAt?: number | null;
+
+  /** the session the callback created; finalize releases the return path against it */
+  @plugins.nosqldb.svDb()
+  public createdSessionId?: string | null;
+}
+
+export const RELYING_PARTY_DEFAULT_COLLECTION_NAMES = {
+  sessions: 'IdpRelyingPartySession',
+  loginAttempts: 'IdpRelyingPartyLoginAttempt',
+} as const;
+
+export interface IRelyingPartyModelsOptions {
+  /**
+   * 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.
+   */
+  collectionNames?: {
+    sessions?: string;
+    loginAttempts?: string;
+  };
+}
+
+export interface IRelyingPartyModels {
+  readonly Session: typeof RelyingPartySessionDoc;
+  readonly LoginAttempt: typeof RelyingPartyLoginAttemptDoc;
+}
+
+/**
+ * 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. 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 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(resolveDb, { collectionName: sessions })
+  class BoundSessionDoc extends RelyingPartySessionDoc {}
+
+  @plugins.nosqldb.Collection(resolveDb, { collectionName: loginAttempts })
+  class BoundLoginAttemptDoc extends RelyingPartyLoginAttemptDoc {}
+
+  return { Session: BoundSessionDoc, LoginAttempt: BoundLoginAttemptDoc };
+};

package/ts_relyingparty/classes.secretbox.ts

@@ -0,0 +1,49 @@
+import * as plugins from './plugins.js';
+
+/**
+ * The persisted format tag of a sealed value. It names the stored layout of
+ * values that already exist and is read as it is; it is not an API version.
+ */
+const SEALED_FORMAT = 'v1';
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+
+/**
+ * Seals small secrets at rest — the PKCE verifier of a login attempt and the
+ * provider tokens of a session — with AES-256-GCM under a 32-byte deployment
+ * key. The sealed form is `v1:<base64url iv>:<base64url tag>:<base64url
+ * ciphertext>`, the form nevermind.finance has stored since before this module
+ * existed, so its sealed values open here unchanged.
+ */
+export class SecretBox {
+  readonly #key: Buffer;
+
+  constructor(keyArg: Buffer) {
+    if (!Buffer.isBuffer(keyArg) || keyArg.length !== 32) {
+      throw new Error('SecretBox needs a 32 byte key');
+    }
+    this.#key = Buffer.from(keyArg);
+  }
+
+  public seal(plainArg: string): string {
+    const iv = plugins.crypto.randomBytes(IV_LENGTH);
+    const cipher = plugins.crypto.createCipheriv(ALGORITHM, this.#key, iv, { authTagLength: TAG_LENGTH });
+    const ciphertext = Buffer.concat([cipher.update(plainArg, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return [SEALED_FORMAT, iv.toString('base64url'), tag.toString('base64url'), ciphertext.toString('base64url')].join(':');
+  }
+
+  /** The plain value, or a throw: another format, another key, or a changed byte. */
+  public open(sealedArg: string): string {
+    const [format, ivText, tagText, cipherText] = sealedArg.split(':');
+    if (format !== SEALED_FORMAT || !ivText || !tagText || cipherText === undefined) {
+      throw new Error('Sealed secret has an unknown format');
+    }
+    const decipher = plugins.crypto.createDecipheriv(ALGORITHM, this.#key, Buffer.from(ivText, 'base64url'), {
+      authTagLength: TAG_LENGTH,
+    });
+    decipher.setAuthTag(Buffer.from(tagText, 'base64url'));
+    return Buffer.concat([decipher.update(Buffer.from(cipherText, 'base64url')), decipher.final()]).toString('utf8');
+  }
+}

package/ts_relyingparty/classes.socketbinding.ts

@@ -0,0 +1,156 @@
+import * as plugins from './plugins.js';
+import type { RelyingPartySessions } from './classes.relyingpartysessions.js';
+import { sha256, timingSafeEqualString } from './helpers.crypto.js';
+import type { IRelyingPartySession } from './interfaces.js';
+
+/** The part of a server `TypedSocket` the binding uses. */
+export type TRelyingPartySocketTransport = Pick<
+  plugins.typedsocket.TypedSocket,
+  'setServerTag' | 'findAllTargetConnectionsByTag'
+>;
+
+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;
+  principalId: string;
+  /** SHA-256 of the CSRF token the registration proved */
+  csrfTokenHash: string;
+}
+
+export interface IRelyingPartySocketRefusal {
+  code: 'invalid_input' | 'forbidden' | 'unauthorized';
+  status: number;
+}
+
+export type TRelyingPartySocketRegistration =
+  | { registered: true; pinned: IRelyingPartyPinnedSession; expiresAt: number }
+  | { registered: false; refusal: IRelyingPartySocketRefusal };
+
+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 */
+  tagPrefix?: string;
+}
+
+/**
+ * Binds typed socket connections to relying-party browser sessions. A
+ * connection registers once with the CSRF token of the page; the proof is the
+ * upgrade's own `Origin` and `Cookie` — which only a browser on this origin
+ * sends — plus the token, and the connection is pinned to the session. Every
+ * later request re-validates the session with the same strength as an HTTP
+ * request. Connection limits, rate limits and sweeps belong to the
+ * application's socket gate.
+ */
+export class RelyingPartySocketBinding<TPrincipal extends object | undefined = undefined> {
+  readonly #sessions: RelyingPartySessions<TPrincipal>;
+  readonly #transport: () => TRelyingPartySocketTransport | undefined;
+  public readonly tagPrefix: string;
+
+  constructor(optionsArg: IRelyingPartySocketBindingOptions<TPrincipal>) {
+    this.#sessions = optionsArg.sessions;
+    this.#transport = optionsArg.transport;
+    this.tagPrefix = optionsArg.tagPrefix ?? 'idp_rp_session:';
+  }
+
+  /** 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') };
+  }
+
+  /**
+   * What a registration payload `{ csrfToken }` proves, given the upgrade it
+   * came on. No connection state is touched, so the application decides about
+   * its limits between this answer and `tagConnection`.
+   */
+  public async resolveBrowserRegistration(
+    payloadArg: unknown,
+    upgradeArg: { origin: string | null; cookie: string | null },
+  ): Promise<TRelyingPartySocketRegistration> {
+    if (!payloadArg || typeof payloadArg !== 'object' || !Reflect.has(payloadArg, 'csrfToken')) {
+      return { registered: false, refusal: { code: 'invalid_input', status: 400 } };
+    }
+    if (upgradeArg.origin !== this.#sessions.publicOrigin) {
+      return { registered: false, refusal: { code: 'forbidden', status: 403 } };
+    }
+    const resolved = await this.#sessions.resolveCookieSession(upgradeArg.cookie);
+    if (!resolved) {
+      return { registered: false, refusal: { code: 'unauthorized', status: 401 } };
+    }
+    if (!this.#sessions.validateCsrf(resolved, Reflect.get(payloadArg, 'csrfToken'))) {
+      return { registered: false, refusal: { code: 'forbidden', status: 403 } };
+    }
+    return {
+      registered: true,
+      pinned: {
+        sessionId: resolved.session.id,
+        principalId: resolved.session.principalId,
+        csrfTokenHash: sha256(resolved.csrfToken),
+      },
+      expiresAt: resolved.session.expiresAt,
+    };
+  }
+
+  public tagOf(sessionIdArg: string): string {
+    return this.tagPrefix + sessionIdArg;
+  }
+
+  /**
+   * 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(targetArg, this.tagOf(sessionIdArg));
+  }
+
+  /**
+   * The pinned session as it stands right now: re-read, live, its principal
+   * 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; 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: live.session,
+      principal: live.principal,
+      verifyCsrf: (candidateArg) =>
+        typeof candidateArg === 'string'
+        && expectedHash.length > 0
+        && timingSafeEqualString(expectedHash, sha256(candidateArg)),
+    };
+  }
+
+  /** The live connections of one session, for closing them when it ends. */
+  public async connectionsOfSession(sessionIdArg: string): Promise<readonly TRelyingPartySocketConnection[]> {
+    const transport = this.#transport();
+    if (!transport) {
+      return [];
+    }
+    return transport.findAllTargetConnectionsByTag(this.tagOf(sessionIdArg));
+  }
+}

package/ts_relyingparty/helpers.cookies.ts

@@ -0,0 +1,79 @@
+export interface ICookieOptions {
+  httpOnly?: boolean;
+  maxAgeSeconds?: number;
+  sameSite?: 'Lax' | 'Strict' | 'None';
+  secure?: boolean;
+}
+
+// Control characters, space, DEL and the cookie delimiters are never valid.
+const isInvalidCookieCharacter = (characterArg: string): boolean => {
+  const code = characterArg.charCodeAt(0);
+  return code <= 0x20 || code === 0x7f || characterArg === ';' || characterArg === ',';
+};
+
+const assertCookiePart = (valueArg: string, labelArg: string): void => {
+  if (!valueArg || Array.from(valueArg).some(isInvalidCookieCharacter)) {
+    throw new Error('Invalid cookie ' + labelArg);
+  }
+};
+
+/** The cookies of a `Cookie` header; the first value of a repeated name wins, an undecodable value is skipped. */
+export const parseCookies = (cookieHeaderArg: string | null | undefined): Map<string, string> => {
+  const result = new Map<string, string>();
+  if (!cookieHeaderArg) {
+    return result;
+  }
+  for (const part of cookieHeaderArg.split(';')) {
+    const separatorIndex = part.indexOf('=');
+    if (separatorIndex <= 0) {
+      continue;
+    }
+    const name = part.slice(0, separatorIndex).trim();
+    const encodedValue = part.slice(separatorIndex + 1).trim();
+    if (!name || result.has(name)) {
+      continue;
+    }
+    try {
+      result.set(name, decodeURIComponent(encodedValue));
+    } catch {
+      continue;
+    }
+  }
+  return result;
+};
+
+/** One `Set-Cookie` value, always `Path=/` and never with a `Domain`, so a `__Host-` name stays valid. */
+export const serializeCookie = (
+  nameArg: string,
+  valueArg: string,
+  optionsArg: ICookieOptions = {},
+): string => {
+  assertCookiePart(nameArg, 'name');
+  assertCookiePart(valueArg, 'value');
+  const parts = [nameArg + '=' + encodeURIComponent(valueArg), 'Path=/'];
+  if (optionsArg.httpOnly) {
+    parts.push('HttpOnly');
+  }
+  if (optionsArg.secure) {
+    parts.push('Secure');
+  }
+  if (optionsArg.sameSite) {
+    parts.push('SameSite=' + optionsArg.sameSite);
+  }
+  if (optionsArg.maxAgeSeconds !== undefined) {
+    if (!Number.isSafeInteger(optionsArg.maxAgeSeconds) || optionsArg.maxAgeSeconds < 0) {
+      throw new Error('Invalid cookie max age');
+    }
+    parts.push('Max-Age=' + optionsArg.maxAgeSeconds);
+  }
+  return parts.join('; ');
+};
+
+export const serializeClearedCookie = (
+  nameArg: string,
+  optionsArg: Omit<ICookieOptions, 'maxAgeSeconds'> = {},
+): string =>
+  serializeCookie(nameArg, 'deleted', {
+    ...optionsArg,
+    maxAgeSeconds: 0,
+  }) + '; Expires=Thu, 01 Jan 1970 00:00:00 GMT';

package/ts_relyingparty/helpers.crypto.ts

@@ -0,0 +1,49 @@
+import * as plugins from './plugins.js';
+
+/** A 32-byte key given as base64 or base64url; anything else is refused by `labelArg`, never echoed. */
+export const decodeSecretKey = (valueArg: string, labelArg: string): Buffer => {
+  const normalized = typeof valueArg === 'string' ? valueArg.trim() : '';
+  if (!normalized) {
+    throw new Error(labelArg + ' must not be empty');
+  }
+  const base64Normalized = normalized
+    .replace(/-/gu, '+')
+    .replace(/_/gu, '/')
+    .replace(/=+$/u, '');
+  const decoded = Buffer.from(normalized, 'base64');
+  if (
+    decoded.length !== 32
+    || decoded.toString('base64').replace(/=+$/u, '') !== base64Normalized
+  ) {
+    throw new Error(labelArg + ' must decode to exactly 32 bytes');
+  }
+  return decoded;
+};
+
+export const randomToken = (byteLengthArg: number = 32): string =>
+  plugins.crypto.randomBytes(byteLengthArg).toString('base64url');
+
+/** base64url SHA-256 of a UTF-8 string; how tokens, states and bindings are stored. */
+export const sha256 = (valueArg: string): string =>
+  plugins.crypto.createHash('sha256').update(valueArg, 'utf8').digest('base64url');
+
+export const timingSafeEqualString = (leftArg: string, rightArg: string): boolean => {
+  const left = Buffer.from(leftArg, 'utf8');
+  const right = Buffer.from(rightArg, 'utf8');
+  if (left.length !== right.length) {
+    return false;
+  }
+  return plugins.crypto.timingSafeEqual(left, right);
+};
+
+/**
+ * The CSRF token of a session: an HMAC of the session cookie token under the
+ * deployment's CSRF key, after a label that separates this use of the key from
+ * any other. It is derived again on every request and never stored.
+ */
+export const deriveCsrfToken = (sessionTokenArg: string, csrfKeyArg: Buffer, labelArg: string): string =>
+  plugins.crypto
+    .createHmac('sha256', csrfKeyArg)
+    .update(labelArg, 'utf8')
+    .update(sessionTokenArg, 'utf8')
+    .digest('base64url');

package/ts_relyingparty/helpers.returnpath.ts

@@ -0,0 +1,44 @@
+/** A return path is a location the application produced, not a place to park data. */
+const MAX_RETURN_PATH_LENGTH = 1_024;
+
+/**
+ * The one path a login may return to, judged on the normalized result and
+ * never on the shape of the input: `/.//evil.com` parses on this origin but
+ * normalizes to `//evil.com`, which a browser reads as another host. Everything
+ * that is not a plain same-origin path outside the login routes — a scheme, a
+ * host, a backslash, a control character, an overlong value, a path under
+ * `loginPathPrefixArg` — becomes `/`.
+ */
+export const sanitizeReturnPath = (
+  returnPathArg: unknown,
+  publicOriginArg: string,
+  loginPathPrefixArg: string,
+): string => {
+  const candidate = typeof returnPathArg === 'string' ? returnPathArg.trim() : '';
+  if (
+    !candidate.startsWith('/')
+    || candidate.length > MAX_RETURN_PATH_LENGTH
+    || candidate.includes('\\')
+    // the URL parser drops tabs and newlines silently; such a path is refused instead of mangled
+    || /\p{Cc}/u.test(candidate)
+  ) {
+    return '/';
+  }
+  const loginRoot = loginPathPrefixArg.endsWith('/') ? loginPathPrefixArg.slice(0, -1) : loginPathPrefixArg;
+  try {
+    const parsed = new URL(candidate, publicOriginArg);
+    if (parsed.origin !== publicOriginArg) {
+      return '/';
+    }
+    if (parsed.pathname === loginRoot || parsed.pathname.startsWith(loginRoot + '/')) {
+      return '/';
+    }
+    const normalized = parsed.pathname + parsed.search + parsed.hash;
+    if (!normalized.startsWith('/') || normalized.startsWith('//') || normalized.includes('\\')) {
+      return '/';
+    }
+    return normalized;
+  } catch {
+    return '/';
+  }
+};

package/ts_relyingparty/index.ts

@@ -0,0 +1,13 @@
+export * from './interfaces.js';
+export * from './classes.errors.js';
+export * from './helpers.cookies.js';
+export * from './helpers.crypto.js';
+export * from './helpers.returnpath.js';
+export * from './classes.secretbox.js';
+export * from './classes.idpoidcprovider.js';
+export * from './classes.rpmodels.js';
+export * from './classes.relyingpartysessions.js';
+export * from './classes.authorityobserver.js';
+export * from './classes.relyingpartyroutes.js';
+export * from './classes.actorscope.js';
+export * from './classes.socketbinding.js';