@everystack/server 0.2.21 → 0.2.24

package/src/role-chain.ts

@@ -0,0 +1,75 @@
+/**
+ * The role chain — generated, idempotent SQL for the least-privilege login role and the
+ * application roles it switches between.
+ *
+ * This is what the `db:provision` action runs (as the operator/owner) at deploy time so a
+ * fresh database comes up with the credential split already in place — no hand-written
+ * `CREATE ROLE`, no `ALTER ROLE … PASSWORD` in a console. The password is set separately
+ * by `db:provision` from a deploy-generated value; this module only shapes the roles and
+ * their membership graph. Table grants and RLS policies stay in the app's migrations
+ * (they're schema-specific); this is the part that must exist before those grants resolve.
+ *
+ * See docs/plans/secure-by-default-database.md.
+ */
+
+const IDENT = /^[a-z_][a-z0-9_]*$/;
+
+export interface RoleChainOptions {
+  /**
+   * The LOGIN role the API connects as — least-privilege: LOGIN, NOINHERIT (memberships
+   * are SET ROLE-only, never ambient), NOBYPASSRLS, and no grants of its own.
+   * Default 'authenticator'.
+   */
+  loginRole?: string;
+  /**
+   * The NOLOGIN application roles the login role may `SET ROLE` to, in order of privilege.
+   * Default ['anon', 'authenticated', 'admin'].
+   */
+  appRoles?: string[];
+}
+
+function assertIdent(name: string, what: string): void {
+  if (!IDENT.test(name)) {
+    throw new Error(`Invalid ${what}: ${JSON.stringify(name)} — must match ${IDENT}`);
+  }
+}
+
+/**
+ * Generate idempotent DDL that creates the application roles and the least-privilege login
+ * role, and wires the membership chain so the login role can `SET ROLE` to each. Safe to
+ * run on every deploy: each `CREATE ROLE` is `IF NOT EXISTS`-guarded, and the login role's
+ * attributes are re-asserted with `ALTER ROLE` so a role created the old way (e.g. without
+ * an explicit NOBYPASSRLS) is corrected. Does NOT set passwords — that's `db:provision`'s
+ * job, from a deploy-generated value.
+ */
+export function generateRoleChainSQL(options: RoleChainOptions = {}): string {
+  const loginRole = options.loginRole ?? 'authenticator';
+  const appRoles = options.appRoles ?? ['anon', 'authenticated', 'admin'];
+
+  assertIdent(loginRole, 'loginRole');
+  appRoles.forEach((r) => assertIdent(r, 'app role'));
+
+  const lines: string[] = [];
+
+  // Application roles — NOLOGIN; reached only via SET ROLE.
+  for (const role of appRoles) {
+    lines.push(
+      `DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '${role}') THEN CREATE ROLE ${role} NOLOGIN; END IF; END $$;`,
+    );
+  }
+
+  // The least-privilege login role. Create if absent, then re-assert attributes so an
+  // existing role is brought into compliance (LOGIN, NOINHERIT, NOBYPASSRLS).
+  lines.push(
+    `DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '${loginRole}') THEN CREATE ROLE ${loginRole} LOGIN NOINHERIT NOBYPASSRLS; END IF; END $$;`,
+  );
+  lines.push(`ALTER ROLE ${loginRole} WITH LOGIN NOINHERIT NOBYPASSRLS;`);
+
+  // Membership chain — the login role may SET ROLE to each app role. NOINHERIT means it
+  // gains their privileges only when it explicitly switches, never ambiently.
+  for (const role of appRoles) {
+    lines.push(`GRANT ${role} TO ${loginRole};`);
+  }
+
+  return lines.join('\n') + '\n';
+}