pgkiln 0.59.0 → 0.61.0

package/src/mfa.ts

@@ -0,0 +1,333 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import type pg from 'pg';
+import { owner } from './db.ts';
+import { decryptSecret, encryptSecret } from './secrets.ts';
+
+// (sprint 126, SEC-2 and SEC-6) Two-factor sign-in for developers: authenticator apps (TOTP, RFC 6238:
+// HMAC-SHA1, 30-second steps, 6 digits; one step either side is accepted for clock drift, and a step is
+// accepted only once) and one-time recovery codes. The policy (off, administrators, all developers) is a
+// setting; it can only be required while two administrators (or every administrator, when there are fewer)
+// have a working second factor, so it never locks the instance out. The command line resets a developer's
+// factors and turns the policy off without signing in (src/cli/main.ts, `pgkiln admin`).
+// (sprint 127) Passkeys and security keys (WebAuthn, src/webauthn.ts) are the second kind of factor, and a
+// developer may trust a browser for a number of days (meta.setting mfa_trust_days; 0 = never).
+
+export const TOTP_STEP = 30;
+export const TOTP_DIGITS = 6;
+export const RECOVERY_CODES = 10;
+export type MfaPolicy = 'off' | 'admins' | 'all';
+export const MFA_POLICIES: MfaPolicy[] = ['off', 'admins', 'all'];
+
+const B32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+export function base32(buf: Buffer): string {
+  let bits = 0, value = 0, out = '';
+  for (const b of buf) {
+    value = (value << 8) | b;
+    bits += 8;
+    while (bits >= 5) {
+      out += B32[(value >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += B32[(value << (5 - bits)) & 31];
+  return out;
+}
+export function unbase32(text: string): Buffer {
+  const clean = text.toUpperCase().replace(/[\s=]/g, '');
+  let bits = 0, value = 0;
+  const out: number[] = [];
+  for (const ch of clean) {
+    const i = B32.indexOf(ch);
+    if (i < 0) throw new Error('not base32');
+    value = (value << 5) | i;
+    bits += 5;
+    if (bits >= 8) {
+      out.push((value >>> (bits - 8)) & 255);
+      bits -= 8;
+    }
+  }
+  return Buffer.from(out);
+}
+
+/** A new authenticator secret: 160 random bits, base32 (what apps expect). */
+export const newTotpSecret = () => base32(randomBytes(20));
+
+/** The code of one 30-second step (RFC 4226 dynamic truncation). */
+export function totpAt(secret: Buffer, step: number, digits = TOTP_DIGITS): string {
+  const msg = Buffer.alloc(8);
+  msg.writeBigUInt64BE(BigInt(step));
+  const h = createHmac('sha1', secret).update(msg).digest();
+  const o = h[h.length - 1] & 15;
+  const n = ((h[o] & 127) << 24) | (h[o + 1] << 16) | (h[o + 2] << 8) | h[o + 3];
+  return String(n % 10 ** digits).padStart(digits, '0');
+}
+
+export const stepNow = (ms = Date.now()) => Math.floor(ms / 1000 / TOTP_STEP);
+
+/** The step a code matches (now, or one step either side), newer than `after`; null otherwise. */
+export function matchTotp(secret: Buffer, code: string, after: number | null, now = stepNow()): number | null {
+  if (!/^\d{6}$/.test(code)) return null;
+  const given = Buffer.from(code);
+  let found: number | null = null;
+  for (const step of [now - 1, now, now + 1]) {
+    if (after !== null && step <= after) continue;
+    if (timingSafeEqual(Buffer.from(totpAt(secret, step)), given)) found = step;
+  }
+  return found;
+}
+
+/** The otpauth URI an authenticator app reads from the QR code. */
+export const otpauthUri = (secret: string, account: string, issuer = 'pgkiln') =>
+  `otpauth://totp/${encodeURIComponent(issuer)}:${encodeURIComponent(account)}?secret=${secret}&issuer=${encodeURIComponent(issuer)}&algorithm=SHA1&digits=${TOTP_DIGITS}&period=${TOTP_STEP}`;
+
+// ---------------------------------------------------------------- recovery codes
+
+const CODE_ALPHABET = 'abcdefghjkmnpqrstuvwxyz23456789'; // no 0/o, 1/l/i
+/** A recovery code: ten characters in two groups (xxxxx-xxxxx), about 50 bits. */
+export function newRecoveryCode(): string {
+  const bytes = randomBytes(10);
+  const chars = [...bytes].map((b) => CODE_ALPHABET[b % CODE_ALPHABET.length]).join('');
+  return `${chars.slice(0, 5)}-${chars.slice(5)}`;
+}
+export const normaliseCode = (code: string) => code.toLowerCase().replace(/[^a-z0-9]/g, '');
+export const hashCode = (code: string) => createHash('sha256').update(normaliseCode(code)).digest('hex');
+
+// ---------------------------------------------------------------- the developer's factors
+
+export interface Factor { id: number; kind: 'totp' | 'passkey'; name: string; created_at: string; last_used_at: string | null; rp_id: string | null }
+
+export async function factorsOf(username: string, db: Pick<pg.ClientBase, 'query'> = owner.pool): Promise<Factor[]> {
+  return (await db.query<Factor>('select id, kind, name, created_at, last_used_at, rp_id from meta.developer_factor where username = $1 order by kind desc, id', [username])).rows;
+}
+
+/** Recovery codes left (confirmed, unused). */
+export async function codesLeft(username: string): Promise<number> {
+  return (await owner.one<{ n: number }>('select count(*)::int as n from meta.developer_recovery_code where username = $1 and confirmed and used_at is null', [username]))!.n;
+}
+
+/** Whether the developer has a working second factor (an authenticator app; recovery codes back it up). */
+export async function hasFactor(username: string): Promise<boolean> {
+  return !!(await owner.one('select 1 as ok from meta.developer_factor where username = $1', [username]));
+}
+
+/** Add an authenticator app (after the developer confirmed a code from it). */
+export async function addTotp(username: string, name: string, secret: string, step: number) {
+  await owner.query(
+    `insert into meta.developer_factor (username, kind, name, secret_enc, last_step, last_used_at) values ($1, 'totp', $2, $3, $4, now())`,
+    [username, name.trim().slice(0, 60) || 'Authenticator', encryptSecret(secret), step],
+  );
+}
+
+// ---------------------------------------------------------------- passkeys (sprint 127)
+
+export interface Passkey { id: number; name: string; credential_id: string; public_key: Record<string, string>; alg: number; sign_count: string; transports: string[] }
+
+/** Add a passkey (after src/webauthn.ts checked the browser's answer). */
+export async function addPasskey(username: string, name: string, p: { credentialId: string; jwk: Record<string, string>; alg: number; signCount: number; rpId: string; transports: string[] }) {
+  await owner.query(
+    `insert into meta.developer_factor (username, kind, name, credential_id, public_key, alg, sign_count, rp_id, transports, last_used_at)
+     values ($1, 'passkey', $2, $3, $4, $5, $6, $7, $8, now())`,
+    [username, name.trim().slice(0, 60) || 'Passkey', p.credentialId, JSON.stringify(p.jwk), p.alg, p.signCount, p.rpId,
+     p.transports.filter((t) => /^[a-z-]{1,20}$/.test(t)).slice(0, 8)],
+  );
+}
+
+/** The developer's passkeys for this relying party (a passkey only works on the domain it was made for). */
+export async function passkeysOf(username: string, rpId: string): Promise<Passkey[]> {
+  return (await owner.query<Passkey>(
+    `select id, name, credential_id, public_key, alg, sign_count, transports from meta.developer_factor
+      where username = $1 and kind = 'passkey' and rp_id = $2 order by id`, [username, rpId])).rows;
+}
+
+/** Record a sign-in with a passkey; false when another sign-in moved the counter first (a replay or a clone). */
+export async function usePasskey(id: number, oldCount: string, newCount: number): Promise<boolean> {
+  return !!(await owner.query(
+    'update meta.developer_factor set sign_count = $3, last_used_at = now() where id = $1 and sign_count = $2::bigint',
+    [id, oldCount, newCount])).rowCount;
+}
+
+// ---------------------------------------------------------------- trusted browsers (sprint 127)
+
+/** Days a browser may skip the second step after one (0 = never). */
+export async function trustDays(): Promise<number> {
+  const v = Number((await owner.one<{ value: string }>(`select value from meta.setting where name = 'mfa_trust_days'`))?.value);
+  return Number.isInteger(v) && v >= 0 && v <= 90 ? v : 0;
+}
+
+export async function setTrustDays(days: number) {
+  await owner.query(`insert into meta.setting (name, value) values ('mfa_trust_days', $1) on conflict (name) do update set value = excluded.value`, [String(days)]);
+  if (days === 0) await owner.query('delete from meta.developer_trusted_browser');
+  else await owner.query(`delete from meta.developer_trusted_browser where expires_at > now() + make_interval(days => $1)`, [days]);
+}
+
+const tokenHash = (token: string) => createHash('sha256').update(token).digest('hex');
+
+/** Trust this browser: a random token for the cookie (only its hash is stored). */
+export async function trustBrowser(username: string, days: number, userAgent: string): Promise<string> {
+  const token = randomBytes(32).toString('base64url');
+  await owner.query(
+    `insert into meta.developer_trusted_browser (token_hash, username, expires_at, user_agent) values ($1, $2, now() + make_interval(days => $3), $4)`,
+    [tokenHash(token), username, days, userAgent.slice(0, 200)]);
+  return token;
+}
+
+/** Whether this browser's token is trusted for this developer (and trusting is still on). */
+export async function isTrustedBrowser(username: string, token: string | undefined): Promise<boolean> {
+  if (!token || token.length > 100) return false;
+  return !!(await owner.one(
+    `select 1 as ok from meta.developer_trusted_browser t where token_hash = $1 and username = $2 and expires_at > now()
+        and exists (select 1 from meta.setting where name = 'mfa_trust_days' and value <> '0')`,
+    [tokenHash(token), username]));
+}
+
+export async function trustedBrowsers(username: string): Promise<number> {
+  return (await owner.one<{ n: number }>('select count(*)::int as n from meta.developer_trusted_browser where username = $1 and expires_at > now()', [username]))!.n;
+}
+
+export async function forgetBrowsers(username: string) {
+  await owner.query('delete from meta.developer_trusted_browser where username = $1', [username]);
+}
+
+/** New recovery codes (the old ones stop working); shown once, counted only when confirmed. */
+export async function newRecoveryCodes(username: string): Promise<string[]> {
+  const codes = Array.from({ length: RECOVERY_CODES }, newRecoveryCode);
+  await owner.tx(async (c) => {
+    await c.query('delete from meta.developer_recovery_code where username = $1', [username]);
+    for (const code of codes) await c.query('insert into meta.developer_recovery_code (username, code_hash) values ($1, $2)', [username, hashCode(code)]);
+  });
+  return codes;
+}
+
+export async function confirmRecoveryCodes(username: string) {
+  await owner.query('update meta.developer_recovery_code set confirmed = true where username = $1 and used_at is null', [username]);
+}
+
+/**
+ * Check a second-factor code at sign-in: an authenticator code (each step once) or a confirmed, unused
+ * recovery code (then used up). Returns what matched, or null.
+ */
+export async function checkSecondFactor(username: string, code: string): Promise<{ kind: 'totp' | 'recovery'; name?: string } | null> {
+  const digits = code.replace(/\s/g, '');
+  if (/^\d{6}$/.test(digits)) {
+    const rows = (await owner.query<{ id: number; name: string; secret_enc: string; last_step: string | null }>(
+      'select id, name, secret_enc, last_step from meta.developer_factor where username = $1 and kind = $2', [username, 'totp'])).rows;
+    for (const f of rows) {
+      let secret: Buffer;
+      try {
+        secret = unbase32(decryptSecret(f.secret_enc));
+      } catch {
+        continue; // the instance key changed: recovery codes still work
+      }
+      const step = matchTotp(secret, digits, f.last_step === null ? null : Number(f.last_step));
+      // the update only wins once per step, also with two requests at the same time
+      if (step !== null && (await owner.query('update meta.developer_factor set last_step = $2, last_used_at = now() where id = $1 and (last_step is null or last_step < $2)', [f.id, step])).rowCount)
+        return { kind: 'totp', name: f.name };
+    }
+    return null;
+  }
+  if (normaliseCode(code).length !== 10) return null;
+  const used = await owner.query(
+    'update meta.developer_recovery_code set used_at = now() where username = $1 and code_hash = $2 and confirmed and used_at is null',
+    [username, hashCode(code)]);
+  return used.rowCount ? { kind: 'recovery' } : null;
+}
+
+// ---------------------------------------------------------------- policy
+
+export async function mfaPolicy(): Promise<{ policy: MfaPolicy; since: Date | null; graceDays: number }> {
+  const rows = (await owner.query<{ name: string; value: string }>(`select name, value from meta.setting where name in ('mfa_required', 'mfa_required_since', 'mfa_grace_days')`)).rows;
+  const get = (n: string) => rows.find((r) => r.name === n)?.value;
+  const p = get('mfa_required');
+  const since = get('mfa_required_since');
+  const grace = Number(get('mfa_grace_days'));
+  return { policy: MFA_POLICIES.includes(p as MfaPolicy) ? (p as MfaPolicy) : 'off', since: since ? new Date(since) : null, graceDays: Number.isInteger(grace) && grace >= 0 && grace <= 90 ? grace : 7 };
+}
+
+/** Does the policy require a second factor of this developer? */
+export const requiredFor = (policy: MfaPolicy, isAdmin: boolean) => policy === 'all' || (policy === 'admins' && isAdmin);
+
+/** The administrators, and how many of them have a working second factor. */
+export async function adminFactors(): Promise<{ admins: number; enrolled: number }> {
+  return (await owner.one<{ admins: number; enrolled: number }>(
+    `select count(*)::int as admins,
+            count(*) filter (where exists (select 1 from meta.developer_factor f where f.username = d.username))::int as enrolled
+       from meta.developer d where d.is_admin`))!;
+}
+
+/** Why the policy can't be required now (two administrators with a factor, or every one when fewer), or null. */
+export async function policyProblem(policy: MfaPolicy): Promise<'admins' | null> {
+  if (policy === 'off') return null;
+  const { admins, enrolled } = await adminFactors();
+  return enrolled >= Math.min(2, admins) && enrolled > 0 ? null : 'admins';
+}
+
+/** (SEC-6) Would taking `username` out of the administrators (a role change, removal) break the rule above? */
+export async function leavesTooFewAdmins(username: string): Promise<boolean> {
+  const { policy } = await mfaPolicy();
+  if (policy === 'off') return false;
+  const r = (await owner.one<{ admins: number; enrolled: number }>(
+    `select count(*)::int as admins,
+            count(*) filter (where exists (select 1 from meta.developer_factor f where f.username = d.username))::int as enrolled
+       from meta.developer d where d.is_admin and d.username <> $1`, [username]))!;
+  return !(r.enrolled >= Math.min(2, r.admins) && r.enrolled > 0);
+}
+
+/** Set the policy; `force` skips the two-administrator rule (only the command line uses it, to turn it off). */
+export async function setPolicy(policy: MfaPolicy, graceDays: number) {
+  await owner.tx(async (c) => {
+    const cur = (await c.query<{ value: string }>(`select value from meta.setting where name = 'mfa_required'`)).rows[0]?.value ?? 'off';
+    await c.query(`insert into meta.setting (name, value) values ('mfa_required', $1), ('mfa_grace_days', $2) on conflict (name) do update set value = excluded.value`, [policy, String(graceDays)]);
+    // the grace period counts from when a stricter policy was turned on
+    if (policy !== 'off' && (cur === 'off' || (cur === 'admins' && policy === 'all')))
+      await c.query(`insert into meta.setting (name, value) values ('mfa_required_since', now()::text) on conflict (name) do update set value = excluded.value`);
+    if (policy === 'off') await c.query(`delete from meta.setting where name = 'mfa_required_since'`);
+  });
+}
+
+/**
+ * A developer without a factor while the policy requires one: 'grace' until the grace period ends (a
+ * banner), then 'enrol' (only the Security page and signing out until they enrol); null otherwise.
+ */
+export async function enrolmentDue(username: string, isAdmin: boolean): Promise<{ due: 'grace' | 'enrol'; until: Date } | null> {
+  const { policy, since, graceDays } = await mfaPolicy();
+  if (!requiredFor(policy, isAdmin) || (await hasFactor(username))) return null;
+  const until = new Date((since ?? new Date()).getTime() + graceDays * 86_400_000);
+  return { due: Date.now() < until.getTime() ? 'grace' : 'enrol', until };
+}
+
+/** Remove every second factor of a developer (an administrator, or the command line) and end their sessions. */
+export async function resetFactors(username: string): Promise<boolean> {
+  return owner.tx(async (c) => {
+    const known = (await c.query('select 1 from meta.developer where username = $1', [username])).rowCount;
+    if (!known) return false;
+    await c.query('delete from meta.developer_factor where username = $1', [username]);
+    await c.query('delete from meta.developer_recovery_code where username = $1', [username]);
+    await c.query('delete from meta.developer_trusted_browser where username = $1', [username]);
+    await c.query('delete from meta.session where app_id is null and username = $1', [username]);
+    return true;
+  });
+}
+
+/** The e-mail addresses of the administrators (to tell them about a reset or a policy change). */
+export async function adminEmails(): Promise<string[]> {
+  return (await owner.query<{ email: string }>(`select email from meta.developer where is_admin and email is not null`)).rows.map((r) => r.email);
+}
+
+/** Tell people about a reset or a policy change by mail, when the builder has a mail service (best effort). */
+export async function notifyMfa(to: string[], subject: string, text: string): Promise<number> {
+  const list = [...new Set(to.filter(Boolean))];
+  if (!list.length) return 0;
+  const { builderMail } = await import('./builder/find-workspace.ts');
+  const { sendWith } = await import('./mail/mail.ts');
+  const mail = await builderMail().catch(() => null);
+  if (!mail) return 0;
+  let sent = 0;
+  for (const address of list)
+    try {
+      await sendWith(mail.service, { from: mail.from, to: [address], cc: [], bcc: [], replyTo: null, subject, text, html: null, attachments: [] });
+      sent++;
+    } catch {
+      // the activity log has the event; a mail that fails doesn't undo it
+    }
+  return sent;
+}

package/src/webauthn.ts

@@ -0,0 +1,205 @@
+import { createHash, createPublicKey, randomBytes, timingSafeEqual, verify, type KeyObject } from 'node:crypto';
+
+// (sprint 127, SEC-2) Passkeys and security keys (WebAuthn level 2) for developers, without a library: the
+// server makes a one-time challenge, the browser asks the authenticator (navigator.credentials), and the
+// server checks what comes back. Registration takes attestation "none": pgkiln stores the credential's public
+// key (as a JWK) and trusts the authenticator the developer chose, as most sites do. Sign-in checks the
+// challenge, the origin, the relying party (RP ID hash), user presence, the signature over authenticatorData
+// and the hash of clientDataJSON, and the signature counter (a clone gives itself away when it goes back).
+// Algorithms: ES256 (-7), EdDSA (-8) and RS256 (-257).
+
+export const ALGORITHMS = [-7, -8, -257];
+
+export class WebAuthnError extends Error {}
+
+export const b64url = (b: Buffer | Uint8Array) => Buffer.from(b).toString('base64url');
+export const unb64url = (s: string) => Buffer.from(String(s ?? ''), 'base64url');
+export const newChallenge = () => b64url(randomBytes(32));
+
+// ------------------------------------------------------------------ CBOR (RFC 8949), only what WebAuthn uses
+
+type Cbor = number | bigint | string | Buffer | boolean | null | undefined | Cbor[] | Map<Cbor, Cbor>;
+
+/** Decode one CBOR item from `buf` at `pos`; returns the item and the position after it. */
+export function cborDecode(buf: Buffer, pos = 0, depth = 0): [Cbor, number] {
+  if (depth > 16) throw new WebAuthnError('CBOR nested too deep');
+  if (pos >= buf.length) throw new WebAuthnError('CBOR ends early');
+  const first = buf[pos++];
+  const major = first >> 5;
+  const info = first & 31;
+  let len: number | bigint;
+  if (info < 24) len = info;
+  else if (info === 24) len = buf.readUInt8(pos), pos += 1;
+  else if (info === 25) len = buf.readUInt16BE(pos), pos += 2;
+  else if (info === 26) len = buf.readUInt32BE(pos), pos += 4;
+  else if (info === 27) len = buf.readBigUInt64BE(pos), pos += 8;
+  else throw new WebAuthnError('CBOR: indefinite lengths are not used by WebAuthn');
+  const n = () => {
+    if (typeof len === 'bigint') throw new WebAuthnError('CBOR length too large');
+    if (pos + len > buf.length && (major === 2 || major === 3)) throw new WebAuthnError('CBOR ends early');
+    return len;
+  };
+  switch (major) {
+    case 0: return [typeof len === 'bigint' ? len : len, pos];
+    case 1: return [typeof len === 'bigint' ? -1n - len : -1 - len, pos];
+    case 2: { const l = n(); return [buf.subarray(pos, pos + l), pos + l]; }
+    case 3: { const l = n(); return [buf.subarray(pos, pos + l).toString('utf8'), pos + l]; }
+    case 4: {
+      const l = n();
+      if (l > 1000) throw new WebAuthnError('CBOR array too long');
+      const out: Cbor[] = [];
+      for (let i = 0; i < l; i++) { const [v, p] = cborDecode(buf, pos, depth + 1); out.push(v); pos = p; }
+      return [out, pos];
+    }
+    case 5: {
+      const l = n();
+      if (l > 1000) throw new WebAuthnError('CBOR map too long');
+      const out = new Map<Cbor, Cbor>();
+      for (let i = 0; i < l; i++) {
+        const [k, p1] = cborDecode(buf, pos, depth + 1);
+        const [v, p2] = cborDecode(buf, p1, depth + 1);
+        out.set(k, v); pos = p2;
+      }
+      return [out, pos];
+    }
+    case 7:
+      if (info === 20) return [false, pos];
+      if (info === 21) return [true, pos];
+      if (info === 22) return [null, pos];
+      if (info === 23) return [undefined, pos];
+      throw new WebAuthnError('CBOR: floats are not used by WebAuthn');
+    default:
+      throw new WebAuthnError('CBOR: tags are not used by WebAuthn');
+  }
+}
+
+// ------------------------------------------------------------------ COSE keys (RFC 9053) → Node key objects
+
+/** A credential public key (COSE_Key) as a JWK, with its algorithm. */
+export function coseToJwk(cose: Map<Cbor, Cbor>): { alg: number; jwk: Record<string, string> } {
+  const kty = cose.get(1);
+  const alg = Number(cose.get(3));
+  const bytes = (k: number) => {
+    const v = cose.get(k);
+    if (!Buffer.isBuffer(v)) throw new WebAuthnError('the key is missing a part');
+    return b64url(v);
+  };
+  if (kty === 2 && alg === -7 && cose.get(-1) === 1) return { alg, jwk: { kty: 'EC', crv: 'P-256', x: bytes(-2), y: bytes(-3) } };
+  if (kty === 1 && alg === -8 && cose.get(-1) === 6) return { alg, jwk: { kty: 'OKP', crv: 'Ed25519', x: bytes(-2) } };
+  if (kty === 3 && alg === -257) return { alg, jwk: { kty: 'RSA', n: bytes(-1), e: bytes(-2) } };
+  throw new WebAuthnError(`unsupported key type or algorithm (${String(kty)}, ${alg})`);
+}
+
+const keyOf = (jwk: Record<string, string>): KeyObject => createPublicKey({ key: jwk, format: 'jwk' });
+
+// ------------------------------------------------------------------ authenticator data
+
+interface AuthData {
+  rpIdHash: Buffer;
+  flags: number;
+  signCount: number;
+  credentialId?: Buffer;
+  publicKey?: Map<Cbor, Cbor>;
+}
+
+export const FLAG_UP = 0x01; // user present
+export const FLAG_UV = 0x04; // user verified
+const FLAG_AT = 0x40; // attested credential data included
+
+export function parseAuthData(buf: Buffer): AuthData {
+  if (buf.length < 37) throw new WebAuthnError('authenticator data too short');
+  const out: AuthData = { rpIdHash: buf.subarray(0, 32), flags: buf[32], signCount: buf.readUInt32BE(33) };
+  if (out.flags & FLAG_AT) {
+    if (buf.length < 55) throw new WebAuthnError('authenticator data too short');
+    const idLen = buf.readUInt16BE(53);
+    if (idLen > 1023 || buf.length < 55 + idLen) throw new WebAuthnError('bad credential id');
+    out.credentialId = buf.subarray(55, 55 + idLen);
+    const [key] = cborDecode(buf, 55 + idLen);
+    if (!(key instanceof Map)) throw new WebAuthnError('bad credential public key');
+    out.publicKey = key;
+  }
+  return out;
+}
+
+// ------------------------------------------------------------------ checks
+
+export interface Expected { challenge: string; origin: string; rpId: string }
+
+function checkClientData(clientDataJSON: Buffer, type: string, exp: Expected) {
+  let c: { type?: string; challenge?: string; origin?: string; crossOrigin?: boolean };
+  try {
+    c = JSON.parse(clientDataJSON.toString('utf8'));
+  } catch {
+    throw new WebAuthnError('client data is not JSON');
+  }
+  if (c.type !== type) throw new WebAuthnError(`expected ${type}`);
+  const a = Buffer.from(String(c.challenge ?? ''));
+  const b = Buffer.from(exp.challenge);
+  if (a.length !== b.length || !timingSafeEqual(a, b)) throw new WebAuthnError('the challenge does not match');
+  if (c.origin !== exp.origin) throw new WebAuthnError(`the origin ${c.origin} is not ${exp.origin}`);
+  if (c.crossOrigin) throw new WebAuthnError('cross-origin use is not allowed');
+}
+
+const rpHash = (rpId: string) => createHash('sha256').update(rpId).digest();
+
+/** A new passkey from navigator.credentials.create(): the credential to store. */
+export function verifyRegistration(input: { clientDataJSON: string; attestationObject: string }, exp: Expected) {
+  const clientData = unb64url(input.clientDataJSON);
+  checkClientData(clientData, 'webauthn.create', exp);
+  const [att] = cborDecode(unb64url(input.attestationObject));
+  if (!(att instanceof Map)) throw new WebAuthnError('bad attestation object');
+  const authData = att.get('authData');
+  if (!Buffer.isBuffer(authData)) throw new WebAuthnError('bad attestation object');
+  const a = parseAuthData(authData);
+  if (!a.rpIdHash.equals(rpHash(exp.rpId))) throw new WebAuthnError('the passkey is for another site');
+  if (!(a.flags & FLAG_UP)) throw new WebAuthnError('the user was not present');
+  if (!a.credentialId || !a.publicKey) throw new WebAuthnError('no credential in the response');
+  const { alg, jwk } = coseToJwk(a.publicKey);
+  keyOf(jwk); // a key Node can read
+  return { credentialId: b64url(a.credentialId), alg, jwk, signCount: a.signCount, userVerified: !!(a.flags & FLAG_UV) };
+}
+
+/** A sign-in from navigator.credentials.get(): the new signature counter, or an error. */
+export function verifyAssertion(
+  input: { clientDataJSON: string; authenticatorData: string; signature: string },
+  stored: { alg: number; jwk: Record<string, string>; signCount: number },
+  exp: Expected,
+) {
+  const clientData = unb64url(input.clientDataJSON);
+  checkClientData(clientData, 'webauthn.get', exp);
+  const authData = unb64url(input.authenticatorData);
+  const a = parseAuthData(authData);
+  if (!a.rpIdHash.equals(rpHash(exp.rpId))) throw new WebAuthnError('the passkey is for another site');
+  if (!(a.flags & FLAG_UP)) throw new WebAuthnError('the user was not present');
+  const data = Buffer.concat([authData, createHash('sha256').update(clientData).digest()]);
+  const sig = unb64url(input.signature);
+  const ok = stored.alg === -8 ? verify(null, data, keyOf(stored.jwk), sig) : verify('sha256', data, keyOf(stored.jwk), sig);
+  if (!ok) throw new WebAuthnError('the signature does not match');
+  // counters only go up; 0 and 0 means the authenticator keeps none (synced passkeys)
+  if ((a.signCount !== 0 || stored.signCount !== 0) && a.signCount <= stored.signCount) throw new WebAuthnError('the signature counter went back (a cloned key?)');
+  return { signCount: a.signCount, userVerified: !!(a.flags & FLAG_UV) };
+}
+
+// ------------------------------------------------------------------ the relying party
+
+/**
+ * The relying party a passkey belongs to and the origin the browser must report. With PUBLIC_URL set (a
+ * production server), that address; otherwise the address the browser used (development, tests).
+ * PGKILN_RP_ID may widen the RP ID to a parent domain (builder.example.com → example.com), which must be a
+ * suffix of the origin's host; passkeys made for one RP ID don't work for another, so changing the domain
+ * means adding them again (authenticator apps and recovery codes keep working).
+ */
+export function relyingParty(req: { protocol: string; host: string }): { rpId: string; origin: string } {
+  let origin = `${req.protocol}://${req.host}`;
+  if (process.env.PUBLIC_URL) {
+    try {
+      origin = new URL(process.env.PUBLIC_URL).origin;
+    } catch {
+      // a bad PUBLIC_URL: the browser's address
+    }
+  }
+  const host = new URL(origin).hostname;
+  const wanted = (process.env.PGKILN_RP_ID ?? '').trim().toLowerCase();
+  const rpId = wanted && (host === wanted || host.endsWith(`.${wanted}`)) ? wanted : host;
+  return { rpId, origin };
+}