pgkiln 0.61.0 → 0.63.0

package/src/cli/main.ts

@@ -471,15 +471,18 @@ const COMMANDS: Record<string, Command> = {
   },
   // (sprint 126, SEC-6) lockout recovery on the server, when nobody can sign in to the builder
   admin: {
-    usage: 'pgkiln admin reset-2fa <developer> | set-2fa-policy off|admins|all [options]',
-    summary: 'lockout recovery: reset a developer\'s two-factor sign-in, set the two-factor policy',
+    usage: 'pgkiln admin reset-2fa <developer> | set-2fa-policy off|admins|all | builder-sign-in password [options]',
+    summary: 'lockout recovery: reset a developer\'s two-factor sign-in, set the two-factor policy, allow the password again',
     details:
       'pgkiln admin reset-2fa <developer> [--reason <text>]\n' +
-      'pgkiln admin set-2fa-policy off|admins|all [--grace <days>]\n\n' +
+      'pgkiln admin set-2fa-policy off|admins|all [--grace <days>]\n' +
+      'pgkiln admin builder-sign-in password\n\n' +
       "reset-2fa removes the developer's authenticator apps and recovery codes and ends their builder\n" +
-      'sessions; they sign in with the password and set up an app again. set-2fa-policy off always works;\n' +
-      'admins and all need at least two administrators with two-factor sign-in (or every one, when there\n' +
-      'are fewer). Both are written to the activity log and mailed to the administrators.',
+      'sessions; they sign in with the password and set up an app again. set-2fa-policy off always works\n' +
+      "(and clears the workspaces' own two-factor rules); admins and all need at least two administrators\n" +
+      'with two-factor sign-in (or every one, when there are fewer). builder-sign-in password turns off the\n' +
+      "workspaces' single sign-on rule, for when the identity provider fails and no break-glass administrator\n" +
+      'can sign in. All are written to the activity log and mailed to the administrators.',
     options: { reason: { type: 'string' }, grace: { type: 'string' } },
     optionHelp: [
       ['--reason <text>', 'reset-2fa: why (in the activity log and the mail)'],
@@ -509,12 +512,25 @@ const COMMANDS: Record<string, Command> = {
           const policy = arg as 'off' | 'admins' | 'all';
           if (await mfa.policyProblem(policy)) throw new Error('at least two administrators (or every one, when there are fewer) need two-factor sign-in first');
           await mfa.setPolicy(policy, grace);
-          await logActivity({ event: '2fa_policy', ip: 'cli', detail: `${policy}, grace ${grace} days (${by})` });
+          // (sprint 128) off means off: no workspace requires a second factor either
+          const cleared = policy === 'off' ? await mfa.clearWorkspaceRequirements() : 0;
+          await logActivity({ event: '2fa_policy', ip: 'cli', detail: `${policy}, grace ${grace} days${cleared ? `, ${cleared} workspace rule(s) cleared` : ''} (${by})` });
           const sent = await mfa.notifyMfa(await mfa.adminEmails(), `pgkiln: two-factor sign-in policy is now ${policy}`, `${by} set the two-factor policy to ${policy} on the server.`);
-          out(`Two-factor policy: ${policy}${policy === 'off' ? '' : `, grace ${grace} days`}.${sent ? ` ${sent} administrator(s) told by mail.` : ''}\n`);
+          out(`Two-factor policy: ${policy}${policy === 'off' ? '' : `, grace ${grace} days`}.${cleared ? ` ${cleared} workspace(s) no longer require it.` : ''}${sent ? ` ${sent} administrator(s) told by mail.` : ''}\n`);
           return EXIT.ok;
         }
-        throw new UsageError(`unknown action ${action}: use reset-2fa or set-2fa-policy`);
+        // (sprint 129, SEC-1) every workspace allows the pgkiln password again
+        if (action === 'builder-sign-in') {
+          if (arg !== 'password') throw new UsageError('builder-sign-in takes password');
+          const { clearSsoOnly } = await import('../devsso.ts');
+          const cleared = await clearSsoOnly();
+          await logActivity({ event: 'sso_policy', ip: 'cli', detail: `password sign-in allowed again, ${cleared} workspace rule(s) cleared (${by})` });
+          const sent = await mfa.notifyMfa(await mfa.adminEmails(), 'pgkiln: the builder password works again',
+            `${by} turned off the single sign-on rule of ${cleared} workspace(s) on the server: developers may sign in with the pgkiln password.`);
+          out(`Developers may sign in with the pgkiln password again; ${cleared} workspace(s) no longer require single sign-on.${sent ? ` ${sent} administrator(s) told by mail.` : ''}\n`);
+          return EXIT.ok;
+        }
+        throw new UsageError(`unknown action ${action}: use reset-2fa, set-2fa-policy or builder-sign-in`);
       } finally {
         await closePools();
       }

package/src/devsso.ts

@@ -0,0 +1,149 @@
+import { randomBytes } from 'node:crypto';
+import { owner } from './db.ts';
+import { SsoError } from './sso.ts';
+
+// (sprint 129, SEC-1) Developers sign in to the builder through an identity
+// provider (OpenID Connect, SAML) or an LDAP directory that has "builder"
+// turned on. The rules, as for application accounts (sso.ts, ldap.ts):
+//  * a developer is found by the provider's stable subject
+//    (meta.developer_identity), never by a name the provider sends alone;
+//  * an existing developer with the same username is linked on the first
+//    sign-in only when the source allows it (builder_link_existing), with a
+//    verified e-mail address when that is the username, and never a
+//    break-glass developer; otherwise the developer links the identity
+//    themselves on the Security page, signed in;
+//  * a new developer is created when the source allows it
+//    (builder_auto_create), for members of builder_group when one is set;
+//  * builder_admin_group, when set, decides on every sign-in who is an
+//    instance administrator (break-glass developers and the last
+//    administrator are never demoted).
+// A workspace can require these sign-ins of its developers (sso_only);
+// break-glass developers may still use the pgkiln password.
+
+export interface BuilderSource {
+  kind: 'provider' | 'directory';
+  id: number;
+  name: string;
+  builder_auto_create: boolean;
+  builder_link_existing: boolean;
+  builder_group: string | null;
+  builder_admin_group: string | null;
+}
+
+export interface BuilderIdentity {
+  subject: string;
+  username: string;
+  name?: string | null;
+  email?: string | null;
+  /** false: the username is an unverified e-mail address and links nothing */
+  mayLink: boolean;
+  groups: string[];
+}
+
+const column = (k: BuilderSource['kind']) => (k === 'provider' ? 'provider_id' : 'directory_id');
+const validEmail = (v: unknown): v is string => typeof v === 'string' && /^[^@\s<>"(),;:\\]+@[^@\s<>"(),;:\\]+\.[^@\s<>"(),;:\\]+$/.test(v) && v.length <= 254;
+
+/** The providers and directories developers can sign in with. */
+export async function builderSources() {
+  const providers = (await owner.query<{ name: string; display_name: string }>('select name, display_name from meta.auth_provider where enabled and builder order by display_name')).rows;
+  const directories = (await owner.query<{ name: string; display_name: string }>('select name, display_name from meta.ldap_directory where enabled and builder order by display_name')).rows;
+  return { providers, directories };
+}
+
+export async function builderProvider(name: string) {
+  return owner.one('select * from meta.auth_provider where enabled and builder and name = $1', [name]);
+}
+export async function builderDirectory(name: string) {
+  return owner.one('select * from meta.ldap_directory where enabled and builder and name = $1', [name]);
+}
+
+/** The developer for an identity (see the rules above); throws SsoError when there is none. */
+export async function resolveDeveloper(src: BuilderSource, id: BuilderIdentity): Promise<string> {
+  const col = column(src.kind);
+  return owner.tx(async (c) => {
+    let username: string | undefined = (await c.query(`select username from meta.developer_identity where ${col} = $1 and subject = $2`, [src.id, id.subject])).rows[0]?.username;
+    if (!username) {
+      const existing = (
+        await c.query(
+          `select d.username, d.break_glass, exists (select 1 from meta.developer_identity i where i.username = d.username and i.${col} = $2) as linked
+             from meta.developer d where lower(d.username) = lower($1)`,
+          [id.username, src.id],
+        )
+      ).rows[0];
+      if (existing) {
+        if (existing.linked) throw new SsoError('This developer is already linked to another identity here.');
+        if (!src.builder_link_existing || !id.mayLink || existing.break_glass)
+          throw new SsoError(`A developer "${existing.username}" exists but is not linked to this identity. Sign in with the password and link it on the Security page.`);
+        username = existing.username as string;
+      } else {
+        const member = !src.builder_group || id.groups.includes(src.builder_group) || (!!src.builder_admin_group && id.groups.includes(src.builder_admin_group));
+        if (!src.builder_auto_create || !member) throw new SsoError(`There is no developer "${id.username}". Ask an administrator for access.`);
+        // a password nobody knows: the developer signs in through the provider (an administrator can set one)
+        username = (
+          await c.query(
+            `insert into meta.developer (username, password_hash, is_admin, email) values ($1, crypt($2, gen_salt('bf', 10)), false, $3) returning username`,
+            [id.username, randomBytes(32).toString('base64url'), validEmail(id.email) ? id.email : null],
+          )
+        ).rows[0].username;
+      }
+      await c.query(`insert into meta.developer_identity (${col}, subject, username) values ($1, $2, $3)`, [src.id, id.subject, username]);
+    }
+    if (src.builder_admin_group) {
+      const admin = id.groups.includes(src.builder_admin_group);
+      // never the last administrator either: the instance would have none
+      await c.query(
+        `update meta.developer set is_admin = $2 where username = $1 and is_admin <> $2
+            and ($2 or (not break_glass and (select count(*) from meta.developer where is_admin) > 1))`,
+        [username, admin],
+      );
+    }
+    return username!;
+  });
+}
+
+/** Link an identity to a signed-in developer (Security page). */
+export async function linkDeveloper(src: Pick<BuilderSource, 'kind' | 'id'>, subject: string, username: string) {
+  const col = column(src.kind);
+  const other = await owner.one(`select username from meta.developer_identity where ${col} = $1 and (subject = $2 or username = $3)`, [src.id, subject, username]);
+  if (other) throw new SsoError(other.username === username ? 'You already linked an identity here; unlink it first.' : 'This identity is linked to another developer.');
+  await owner.query(`insert into meta.developer_identity (${col}, subject, username) values ($1, $2, $3)`, [src.id, subject, username]);
+}
+
+/** A developer's linked identities (Security page, provider pages). */
+export async function identitiesOf(username: string) {
+  return (
+    await owner.query<{ id: number; source: string; display_name: string; kind: 'provider' | 'directory'; linked_at: string }>(
+      `select i.id, coalesce(p.name, d.name) as source, coalesce(p.display_name, d.display_name) as display_name,
+              case when i.provider_id is null then 'directory' else 'provider' end as kind, i.linked_at
+         from meta.developer_identity i
+         left join meta.auth_provider p on p.id = i.provider_id
+         left join meta.ldap_directory d on d.id = i.directory_id
+        where i.username = $1 order by 3`,
+      [username],
+    )
+  ).rows;
+}
+
+/**
+ * Must the developer sign in through an identity provider? A member of a workspace that requires it,
+ * unless break-glass.
+ */
+export async function ssoRequired(username: string) {
+  const r = await owner.one(
+    `select not d.break_glass and exists (select 1 from meta.workspace_member m join meta.workspace w on w.id = m.workspace_id
+                                           where m.username = d.username and w.sso_only) as required
+       from meta.developer d where d.username = $1`,
+    [username],
+  );
+  return !!r?.required;
+}
+
+/** Instance administrators who may still sign in with the password. */
+export async function breakGlassAdmins() {
+  return (await owner.query<{ username: string }>('select username from meta.developer where is_admin and break_glass order by username')).rows.map((r) => r.username);
+}
+
+/** `pgkiln admin builder-sign-in password`: every workspace allows the password again. */
+export async function clearSsoOnly() {
+  return (await owner.query('update meta.workspace set sso_only = false where sso_only')).rowCount ?? 0;
+}

package/src/mfa.ts

@@ -11,6 +11,8 @@ import { decryptSecret, encryptSecret } from './secrets.ts';
 // 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).
+// (sprint 128) A passkey the authenticator verified the developer with may stand in for both the password and
+// the second factor (mfa_passkey_signin), and a workspace may require a second factor of its developers.
 
 export const TOTP_STEP = 30;
 export const TOTP_DIGITS = 6;
@@ -139,6 +141,26 @@ export async function passkeysOf(username: string, rpId: string): Promise<Passke
       where username = $1 and kind = 'passkey' and rp_id = $2 order by id`, [username, rpId])).rows;
 }
 
+/** (sprint 128) The passkey with this credential id for this relying party, and whose it is (sign-in without a user name). */
+export async function passkeyByCredential(credentialId: string, rpId: string): Promise<(Passkey & { username: string }) | null> {
+  if (!credentialId || credentialId.length > 1400) return null;
+  return (await owner.one<Passkey & { username: string }>(
+    `select id, username, name, credential_id, public_key, alg, sign_count, transports from meta.developer_factor
+      where kind = 'passkey' and credential_id = $1 and rp_id = $2`, [credentialId, rpId])) ?? null;
+}
+
+/** The user handle a developer's passkeys carry: stable, and not the user name. */
+export const userHandle = (username: string) => createHash('sha256').update(`pgkiln-developer:${username}`).digest().subarray(0, 16).toString('base64url');
+
+/** (sprint 128) Whether a passkey alone (user verified) may sign a developer in. */
+export async function passkeySignin(): Promise<boolean> {
+  return (await owner.one<{ value: string }>(`select value from meta.setting where name = 'mfa_passkey_signin'`))?.value !== 'off';
+}
+
+export async function setPasskeySignin(on: boolean) {
+  await owner.query(`insert into meta.setting (name, value) values ('mfa_passkey_signin', $1) on conflict (name) do update set value = excluded.value`, [on ? 'on' : 'off']);
+}
+
 /** 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(
@@ -284,14 +306,47 @@ export async function setPolicy(policy: MfaPolicy, graceDays: number) {
   });
 }
 
+/**
+ * (sprint 128) Whether a second factor is required of this developer, by the instance's policy or by one of
+ * their workspaces, and since when (the grace period counts from the earliest).
+ */
+export async function requirement(username: string, isAdmin: boolean): Promise<{ required: boolean; since: Date | null; graceDays: number; workspaces: string[] }> {
+  const [{ policy, since, graceDays }, ws] = await Promise.all([
+    mfaPolicy(),
+    owner.query<{ name: string; since: Date }>(
+      `select w.name, w.mfa_required_since as since from meta.workspace w join meta.workspace_member m on m.workspace_id = w.id
+        where m.username = $1 and w.mfa_required_since is not null order by w.mfa_required_since`, [username]),
+  ]);
+  const byInstance = requiredFor(policy, isAdmin);
+  const times = [...(byInstance ? [since ?? new Date()] : []), ...ws.rows.map((r) => new Date(r.since))];
+  return {
+    required: times.length > 0,
+    since: times.length ? new Date(Math.min(...times.map((t) => t.getTime()))) : null,
+    graceDays,
+    workspaces: ws.rows.map((r) => r.name),
+  };
+}
+
+/** (sprint 128) Require a second factor of a workspace's developers (from now), or stop requiring it. */
+export async function setWorkspaceRequired(workspaceId: number, on: boolean): Promise<boolean> {
+  return !!(await owner.query(
+    `update meta.workspace set mfa_required_since = case when $2 then coalesce(mfa_required_since, now()) end where id = $1`,
+    [workspaceId, on])).rowCount;
+}
+
+/** The command line's "off": no workspace requires a second factor either. */
+export async function clearWorkspaceRequirements(): Promise<number> {
+  return (await owner.query('update meta.workspace set mfa_required_since = null where mfa_required_since is not null')).rowCount ?? 0;
+}
+
 /**
  * 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);
+  const r = await requirement(username, isAdmin);
+  if (!r.required || (await hasFactor(username))) return null;
+  const until = new Date((r.since ?? new Date()).getTime() + r.graceDays * 86_400_000);
   return { due: Date.now() < until.getTime() ? 'grace' : 'enrol', until };
 }
 

package/src/runtime/routes.ts

@@ -16,7 +16,7 @@ import { accountRoles, loadApp, loadPage, type App, type Page, type Region } fro
 import { passwordDaysLeft, passwordProblem } from '../accounts.ts';
 import { english, type Translate } from '../i18n.ts';
 import { checksumValid, loginWindowMinutes, urlChecksum } from '../security.ts';
-import { enabledProviders, finishSignIn, loadProvider, ssoAccess, SsoError, startSignIn, type SsoResult } from '../sso.ts';
+import { builderSsoFinish, enabledProviders, finishSignIn, loadProvider, ssoAccess, SsoError, startSignIn, type Provider, type SsoResult } from '../sso.ts';
 import { sessionLimits, clientIp, createSession, destroySession, getSession, loginThrottled, logActivity, saveState, takeFlash, type Session } from '../session.ts';
 import { checkPageAccess, computeVisibility, Forbidden, isAuthorized } from './authz.ts';
 import { bindValues, dbg, publicError, stripSemicolon, timed, toState, writeOut, type PageContext } from './context.ts';
@@ -1350,8 +1350,19 @@ export async function runtimeRoutes(app: FastifyInstance) {
   });
 
   /** The end of a single sign-on (OpenID Connect or SAML): the app's access rules, then the session. */
-  const finishSso = (req: FastifyRequest, reply: FastifyReply, p: { name: string }, result: SsoResult, ip: string) =>
-    withAppDb(result.appId, () => finishSsoForApp(req, reply, p, result, ip));
+  const finishSso = (req: FastifyRequest, reply: FastifyReply, p: Provider, result: SsoResult, ip: string) => {
+    // (sprint 129) a sign-in to the builder
+    if (result.appId === null) {
+      const builder = builderSsoFinish();
+      if (!builder) return simplePage(reply, 404, english('error.not_found'), english('login.method_unavailable'));
+      return builder(req, reply, p, result, ip).catch((e) => {
+        if (!(e instanceof SsoError)) throw e;
+        logActivity({ username: result.link ?? result.username.slice(0, 100), event: 'login_failed', ip, detail: `builder sso:${p.name}: ${e.message}` });
+        return simplePage(reply, 403, english('login.sso_failed'), e.message, result.link ? '/builder/security' : '/builder/login');
+      });
+    }
+    return withAppDb(result.appId, () => finishSsoForApp(req, reply, p, result, ip));
+  };
   const finishSsoForApp = async (req: FastifyRequest, reply: FastifyReply, p: { name: string }, result: SsoResult, ip: string) => {
     const alias = (await runtime.one<{ alias: string }>('select alias from meta.app where id = $1', [result.appId]))?.alias;
     const loaded = alias ? await appWithLocale(req, alias) : undefined;

package/src/saml.ts

@@ -76,7 +76,7 @@ function client(p: Provider, cache: CacheProvider) {
 }
 
 /** Start: the IdP URL with the AuthnRequest, and the browser-binding cookie value. */
-export async function startSamlSignIn(p: Provider, appId: number, next: string | undefined) {
+export async function startSamlSignIn(p: Provider, appId: number | null, next: string | undefined, link?: string) {
   const state = b64url(randomBytes(32));
   const browserKey = b64url(randomBytes(32));
   await owner.query(`delete from meta.sso_pending where created_at < now() - make_interval(mins => $1)`, [PENDING_MINUTES]);
@@ -86,9 +86,9 @@ export async function startSamlSignIn(p: Provider, appId: number, next: string |
   if (!requestId) throw new SsoError('The AuthnRequest has no ID.');
   // code_verifier is unused for SAML; nonce holds the AuthnRequest ID the response must answer
   await owner.query(
-    `insert into meta.sso_pending (state, app_id, provider_id, code_verifier, nonce, browser_hash, next)
-     values ($1, $2, $3, '', $4, $5, $6)`,
-    [state, appId, p.id, requestId, sha256(browserKey), next ?? null],
+    `insert into meta.sso_pending (state, app_id, provider_id, code_verifier, nonce, browser_hash, next, link_username)
+     values ($1, $2, $3, '', $4, $5, $6, $7)`,
+    [state, appId, p.id, requestId, sha256(browserKey), next ?? null, link ?? null],
   );
   return { url, browserKey };
 }
@@ -99,7 +99,7 @@ const values = (v: unknown): string[] => (v === undefined || v === null ? [] : (
 export async function finishSamlSignIn(p: Provider, body: { SAMLResponse?: string; RelayState?: string }, browserKey: string | undefined): Promise<SsoResult> {
   const pending = await owner.one(
     `delete from meta.sso_pending where state = $1 and provider_id = $2 and created_at > now() - make_interval(mins => $3)
-     returning app_id, nonce, browser_hash, next`,
+     returning app_id, nonce, browser_hash, next, link_username`,
     [body.RelayState ?? '', p.id, PENDING_MINUTES],
   );
   if (!pending) throw new SsoError('This sign-in has expired or was already used. Please try again.');
@@ -117,8 +117,14 @@ export async function finishSamlSignIn(p: Provider, body: { SAMLResponse?: strin
   if (!profile?.nameID) throw new SsoError('The SAML response names no user.');
   const username = p.username_claim === 'nameID' ? profile.nameID : values(profile[p.username_claim])[0];
   if (!usableUsername(username)) throw new SsoError(`The SAML response has no usable "${p.username_claim}" attribute.`);
-  const account = await resolveAccount(p, { sub: profile.nameID, name: values(profile.displayName ?? profile.cn)[0], email: profile.email ?? profile.mail }, username);
-  return { appId: pending.app_id, next: pending.next, username: account, groups: values(profile[p.groups_claim]) };
+  const name = values(profile.displayName ?? profile.cn)[0];
+  const email = values(profile.email ?? profile.mail)[0];
+  const groups = values(profile[p.groups_claim]);
+  if (pending.app_id === null)
+    // the builder: devsso.ts finds the developer (sprint 129)
+    return { appId: null, next: pending.next, username, groups, link: pending.link_username, identity: { subject: profile.nameID, name: name ?? null, email: email ?? null, mayLink: true } };
+  const account = await resolveAccount(p, { sub: profile.nameID, name, email: profile.email ?? profile.mail }, username);
+  return { appId: pending.app_id, next: pending.next, username: account, groups };
 }
 
 /** Service provider metadata (entity ID, ACS) to register pgkiln at the IdP. */

package/src/sso.ts

@@ -34,6 +34,12 @@ export interface Provider {
   protocol: 'oidc' | 'saml';
   idp_sso_url: string | null;
   idp_cert: string | null;
+  /** (131) developers sign in to the builder with this provider too (devsso.ts) */
+  builder: boolean;
+  builder_auto_create: boolean;
+  builder_link_existing: boolean;
+  builder_group: string | null;
+  builder_admin_group: string | null;
 }
 
 interface Discovery {
@@ -86,8 +92,11 @@ function jwks(doc: Discovery) {
   return set;
 }
 
-/** Start: returns the provider URL to redirect to, and the browser-binding cookie value. */
-export async function startSignIn(p: Provider, appId: number, next: string | undefined) {
+/**
+ * Start: returns the provider URL to redirect to, and the browser-binding cookie value.
+ * appId null: a sign-in to the builder; link: the signed-in developer linking this identity.
+ */
+export async function startSignIn(p: Provider, appId: number | null, next: string | undefined, link?: string) {
   const doc = await discover(p.issuer);
   const state = b64url(randomBytes(32));
   const nonce = b64url(randomBytes(32));
@@ -95,9 +104,9 @@ export async function startSignIn(p: Provider, appId: number, next: string | und
   const browserKey = b64url(randomBytes(32));
   await owner.query(`delete from meta.sso_pending where created_at < now() - make_interval(mins => $1)`, [PENDING_MINUTES]);
   await owner.query(
-    `insert into meta.sso_pending (state, app_id, provider_id, code_verifier, nonce, browser_hash, next)
-     values ($1, $2, $3, $4, $5, $6, $7)`,
-    [state, appId, p.id, verifier, nonce, sha256(browserKey), next ?? null],
+    `insert into meta.sso_pending (state, app_id, provider_id, code_verifier, nonce, browser_hash, next, link_username)
+     values ($1, $2, $3, $4, $5, $6, $7, $8)`,
+    [state, appId, p.id, verifier, nonce, sha256(browserKey), next ?? null, link ?? null],
   );
   const url = new URL(doc.authorization_endpoint);
   url.search = new URLSearchParams({
@@ -113,16 +122,29 @@ export async function startSignIn(p: Provider, appId: number, next: string | und
   return { url: url.toString(), browserKey };
 }
 
+// (sprint 129) the builder finishes its own sign-ins (app_id null); the callback routes are the runtime's
+type BuilderFinish = (req: any, reply: any, p: Provider, result: SsoResult, ip: string) => Promise<unknown>;
+let builderFinish: BuilderFinish | null = null;
+export const onBuilderSso = (f: BuilderFinish) => {
+  builderFinish = f;
+};
+export const builderSsoFinish = () => builderFinish;
+
 /** Read a claim by name or dot path (e.g. realm_access.roles). */
 function claim(payload: JWTPayload, path: string): unknown {
   return path.split('.').reduce<any>((v, k) => (v && typeof v === 'object' ? v[k] : undefined), payload);
 }
 
 export interface SsoResult {
-  appId: number;
+  /** null: a sign-in to the builder (131); username is then the provider's, not resolved to an account */
+  appId: number | null;
   next: string | null;
   username: string;
   groups: string[];
+  /** builder sign-ins: the identity, for devsso.ts */
+  identity?: { subject: string; name: string | null; email: string | null; mayLink: boolean };
+  /** builder: the signed-in developer who links this identity (Security page) */
+  link?: string | null;
 }
 
 /** Callback: validate state/browser, exchange the code, verify the ID token, resolve the account. */
@@ -132,7 +154,7 @@ export async function finishSignIn(p: Provider, params: URLSearchParams, browser
   const code = params.get('code') ?? '';
   const pending = await owner.one(
     `delete from meta.sso_pending where state = $1 and provider_id = $2 and created_at > now() - make_interval(mins => $3)
-     returning app_id, code_verifier, nonce, browser_hash, next`,
+     returning app_id, code_verifier, nonce, browser_hash, next, link_username`,
     [state, p.id, PENDING_MINUTES],
   );
   if (!pending) throw new SsoError('This sign-in link has expired or was already used. Please try again.');
@@ -181,6 +203,14 @@ export async function finishSignIn(p: Provider, params: URLSearchParams, browser
 
   // an unverified e-mail address never links an existing account
   const verified = p.username_claim !== 'email' || payload.email_verified === true;
+  if (pending.app_id === null) {
+    // the builder: devsso.ts finds the developer (sprint 129)
+    const email = payload.email_verified === false ? null : typeof payload.email === 'string' ? payload.email : null;
+    return {
+      appId: null, next: pending.next, username, groups, link: pending.link_username,
+      identity: { subject: payload.sub, name: typeof payload.name === 'string' ? payload.name : null, email, mayLink: verified },
+    };
+  }
   const account = await resolveAccount(p, payload, username, { mayLink: verified });
   return { appId: pending.app_id, next: pending.next, username: account, groups };
 }