pgkiln 0.62.0 → 0.63.0

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/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 };
 }