@everystack/server 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -76,6 +76,10 @@
     "./pipeline": {
       "types": "./src/pipeline.ts",
       "default": "./src/pipeline.ts"
+    },
+    "./infra": {
+      "types": "./src/infra.ts",
+      "default": "./src/infra.ts"
     }
   },
   "peerDependencies": {
@@ -87,6 +91,7 @@
     "@aws-sdk/signature-v4a": ">=3.1048.0",
     "@everystack/auth": ">=0.1.0",
     "@everystack/cli": ">=0.1.0",
+    "@everystack/pg-tools": ">=0.4.0",
     "drizzle-orm": "0.41.0",
     "heic-decode": "2.1.0",
     "postgres": "3.4.9",
@@ -106,6 +111,9 @@
     "sst": {
       "optional": true
     },
+    "@everystack/pg-tools": {
+      "optional": true
+    },
     "@everystack/auth": {
       "optional": true
     },
@@ -143,8 +151,9 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
+    "@everystack/pg-tools": "0.4.0",
     "@everystack/auth": "0.4.0",
-    "@everystack/cli": "0.4.5"
+    "@everystack/cli": "0.4.8"
   },
   "scripts": {
     "test": "jest",

package/src/db-doctor.ts

@@ -87,6 +87,20 @@ export interface DoctorProbe {
    * an older probe (the check is then skipped). B4.
    */
   darkRelations?: DarkRelation[];
+  /**
+   * pg_dump layer capability: whether @everystack/pg-tools is attached (pg_dump present) and its
+   * major can dump this server (client >= server). Drives the one-line "backups" lens — a missing
+   * layer blocks db:backup AND the snapshot-first destructive apply. Absent on an older probe (the
+   * check is then skipped). See docs/plans/pgdump-layer.md.
+   */
+  backup?: {
+    /** `pg_dump --version` output, or null when the layer is not attached. */
+    pgDump: string | null;
+    pgDumpMajor: number | null;
+    serverMajor: number | null;
+    /** pgDumpMajor >= serverMajor — a client can dump an older-or-equal server, never a newer one. */
+    compatible: boolean;
+  };
 }
 
 /** A function PUBLIC can EXECUTE, and whether it runs as its owner (the dangerous half). */
@@ -324,8 +338,13 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
       remediation:
         'Run `everystack db:provision --stage <stage>` — it creates the least-privilege role chain on this '
         + 'database (idempotent, creates no database) AND writes the DATABASE_URL secret for you, without ever '
-        + 'printing the credential. Then in sst.config.ts declare `new sst.Secret("DatabaseUrl")`, link it to the '
-        + 'API function, and drop the raw Postgres component from the API link (keep it on ops/worker); redeploy. '
+        + 'printing the credential. PRECONDITION before flipping the API: the handler must escalate per request '
+        + '(pgSettings + SET ROLE / withRole) — the authenticator holds no privileges of its own (NOINHERIT), so a '
+        + 'handler that never escalates cannot even see the schema and every endpoint fails "relation does not exist". '
+        + 'Then flip in TWO deploys: (1) declare `new sst.Secret("DatabaseUrl")` and link it to the API function while '
+        + 'KEEPING the raw Postgres component linked (an explicit DatabaseUrl already outranks it, and the component is '
+        + 'your instant rollback — unlink the secret to revert); verify with real requests and `everystack db:doctor`; '
+        + '(2) then drop the raw Postgres component from the API link (keep it on ops/worker) and redeploy. '
         + 'New apps get all of this automatically from the `everystack.Postgres` construct.',
     });
   } else {
@@ -359,7 +378,7 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
       status: accessible ? 'fail' : 'pass',
       detail: accessible
         ? `the api connection read "${table}" without setting a role — it carries ambient privileges (likely INHERIT + membership in a USING(true) role). A least-privilege role has no grants of its own and must SET ROLE first.`
-        : `the api connection cannot read "${table}" without SET ROLE — correct fail-closed behavior`,
+        : `the api connection cannot read "${table}" without SET ROLE — correct fail-closed behavior. NOTE the runtime requirement this creates: the handler MUST escalate per request (pgSettings + SET ROLE / withRole); a handler that never escalates fails every endpoint with "relation ... does not exist".`,
       remediation: accessible
         ? `Connect the API as a NOINHERIT role with no table grants of its own (e.g. \`authenticator\`), so memberships only apply via SET ROLE: \`ALTER ROLE <api_role> NOINHERIT;\` and revoke any direct table grants. The handler/SSR then escalate per-request via withRole().`
         : undefined,
@@ -539,6 +558,33 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
     }
   }
 
+  // Backups lens — the pg_dump layer gates db:backup AND the snapshot-first destructive apply. A
+  // missing layer isn't a security hole (warn, not fail), but it silently blocks the ceremony.
+  if (probe.backup) {
+    const b = probe.backup;
+    if (b.pgDump && b.compatible) {
+      checks.push({
+        name: 'Logical backups available (pg_dump layer)',
+        status: 'pass',
+        detail: `pg_dump major ${b.pgDumpMajor} attached and compatible with server major ${b.serverMajor} — db:backup and the snapshot-first destructive apply are ready`,
+      });
+    } else if (b.pgDump && !b.compatible) {
+      checks.push({
+        name: 'Logical backups available (pg_dump layer)',
+        status: 'warn',
+        detail: `pg_dump major ${b.pgDumpMajor} is older than server major ${b.serverMajor} — it will refuse to dump (no bypass exists)`,
+        remediation: 'Upgrade @everystack/pg-tools to advance the client ceiling to >= the server major, then redeploy.',
+      });
+    } else {
+      checks.push({
+        name: 'Logical backups available (pg_dump layer)',
+        status: 'warn',
+        detail: 'pg_dump layer not attached — db:backup and the snapshot-first destructive apply are unavailable',
+        remediation: 'Install @everystack/pg-tools and redeploy (pgDumpLayer attaches it automatically), or pass a bring-your-own layerArn in sst.config.ts.',
+      });
+    }
+  }
+
   return {
     api,
     admin,

package/src/infra.ts

@@ -0,0 +1,96 @@
+/**
+ * @everystack/server/infra — deploy-time helpers for a consumer's `sst.config.ts`.
+ *
+ * `pgDumpLayer()` attaches the PostgreSQL client-tools Lambda layer that `db:backup`/`db:restore`
+ * (and the snapshot-first apply ceremony) need. It replaces the old `PGDUMP_LAYER_ARN` env-var line
+ * with a zero-config, declarative resource: the framework ships the binaries (@everystack/pg-tools),
+ * and this publishes them as a content-addressed LayerVersion into the CONSUMER's own account.
+ *
+ * Declarative, not imperative: it returns a Pulumi-managed resource's arn (or an escape-hatch
+ * string), so the SST/Pulumi engine owns the layer's lifecycle — no SDK side effects at config-eval,
+ * no untracked state, clean teardown. Same artifact sha => same layer name => redeploys are no-ops.
+ */
+
+import { manifest, layerZipPath } from '@everystack/pg-tools';
+
+/**
+ * SST's ambient config globals, injected so this package typechecks standalone (it must not depend on
+ * SST's per-app generated types). In `sst.config.ts` you already have both — pass `{ aws, $util }`.
+ * Typed loosely on purpose; the shapes are Pulumi's and not worth vendoring here.
+ */
+export interface PgDumpLayerContext {
+  /** SST's global `aws` (@pulumi/aws) — for `aws.lambda.LayerVersion`. */
+  aws: any;
+  /** SST's global `$util` (@pulumi/pulumi) — for `$util.asset.FileArchive`. */
+  $util: any;
+}
+
+export interface PgDumpLayerOptions {
+  /**
+   * The stage's PostgreSQL server major. The shipped client must be >= this (pg_dump/pg_restore are
+   * backward compatible; a client older than the server is refused). Read it from the engine you declare.
+   */
+  pgMajor: number;
+  /**
+   * Escape hatch: attach this exact layer ARN instead of the managed publish. For consumers who build
+   * their own (e.g. x86_64, an exotic major) via tools/pgdump-layer. Outranks everything else.
+   */
+  layerArn?: string;
+}
+
+let warnedEnv = false;
+
+/**
+ * Resolve and attach the pg_dump layer. Returns the ARN to spread into a Function's `layers: []`.
+ *
+ * Precedence: explicit `layerArn` > `PGDUMP_LAYER_ARN` (deprecated alias, warns once) > the managed
+ * content-addressed LayerVersion published into this account.
+ *
+ * @example
+ *   import { pgDumpLayer } from '@everystack/server/infra';
+ *   const ops = new sst.aws.Function('Ops', {
+ *     layers: [pgDumpLayer({ aws, $util }, 'PgDump', { pgMajor: 16 })],
+ *     // ...
+ *   });
+ */
+export function pgDumpLayer(
+  ctx: PgDumpLayerContext,
+  name: string,
+  opts: PgDumpLayerOptions,
+): any /* Input<string> — the layer arn; `any` at the Pulumi interop boundary so it spreads into layers:[] */ {
+  // 1) explicit escape hatch wins.
+  if (opts.layerArn) return opts.layerArn;
+
+  // 2) deprecated env alias — still honored for one minor line, but warned.
+  const envArn = process.env.PGDUMP_LAYER_ARN;
+  if (envArn) {
+    if (!warnedEnv) {
+      warnedEnv = true;
+      console.warn(
+        '[everystack] PGDUMP_LAYER_ARN is deprecated and will be removed in the next minor. ' +
+          'Install @everystack/pg-tools and drop the env var (the layer is published automatically), ' +
+          'or pass pgDumpLayer(ctx, name, { layerArn }) for a bring-your-own layer.',
+      );
+    }
+    return envArn;
+  }
+
+  // 3) the managed publish: a content-addressed LayerVersion in the consumer's own account.
+  if (manifest.major < opts.pgMajor) {
+    throw new Error(
+      `@everystack/pg-tools ships pg${manifest.major} client tools, but this stage's server is ` +
+        `pg${opts.pgMajor}. pg_dump/pg_restore must be >= the server. Upgrade @everystack/pg-tools ` +
+        `to advance the client ceiling, or pass a bring-your-own layerArn.`,
+    );
+  }
+  const sha8 = manifest.sha256.slice(0, 8);
+  const layer = new ctx.aws.lambda.LayerVersion(name, {
+    // content-addressed: same artifact => same name => Pulumi treats redeploys as no-ops.
+    layerName: `everystack-pgdump${manifest.major}-${sha8}`,
+    code: new ctx.$util.asset.FileArchive(layerZipPath()),
+    compatibleRuntimes: ['nodejs20.x'],
+    compatibleArchitectures: [manifest.arch],
+    description: `everystack pg_dump/pg_restore — pg${manifest.postgresql}, sha ${sha8}`,
+  });
+  return layer.arn;
+}

package/src/plugin.ts

@@ -725,8 +725,34 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
         }
       }
 
+      // Backups lens — is the pg_dump layer attached AND version-compatible? Reuse the
+      // db:backup:probe internals; a missing layer leaves pgDump null (the lens warns), never throws.
+      let backup: import('./db-doctor').DoctorProbe['backup'];
+      try {
+        const { pgClientVersion, parsePgDumpMajor, serverMajorFromNum, isDumpCompatible } = await import('./backup');
+        let pgDump: string | null = null;
+        let pgDumpMajor: number | null = null;
+        try {
+          pgDump = await pgClientVersion('pg_dump');
+          pgDumpMajor = parsePgDumpMajor(pgDump);
+        } catch {
+          // layer absent — pgDump stays null, the lens reports "not attached"
+        }
+        const svnRow = rowsOf(await opsDb.execute(sql.raw('SHOW server_version_num')))[0];
+        const svn = Number(svnRow?.server_version_num);
+        const serverMajor = Number.isFinite(svn) ? serverMajorFromNum(svn) : null;
+        backup = {
+          pgDump,
+          pgDumpMajor,
+          serverMajor,
+          compatible: pgDumpMajor != null && Number.isFinite(svn) ? isDumpCompatible(pgDumpMajor, svn) : false,
+        };
+      } catch {
+        // leave backup undefined → the lens is skipped, exactly like the other optional probes
+      }
+
       return buildDoctorReport(
-        { api, admin, forceRls, appGrantedRls, apiAmbientRead, secdefFunctions, publicExecutableFunctions, darkRelations },
+        { api, admin, forceRls, appGrantedRls, apiAmbientRead, secdefFunctions, publicExecutableFunctions, darkRelations, backup },
         { forceRlsCarveouts: options.forceRlsCarveouts, functionSchemas: options.functionSchemas },
       );
     };
@@ -794,7 +820,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       try {
         pgDump = await pgClientVersion('pg_dump');
       } catch (err: any) {
-        return { error: `pg_dump not available — is the pg_dump layer attached to this function? (${err?.message || String(err)})` };
+        return { error: `pg_dump not available — the pg_dump layer is not attached. Install @everystack/pg-tools and redeploy (pgDumpLayer() attaches it automatically), or pass a bring-your-own layerArn in sst.config.ts. (${err?.message || String(err)})` };
       }
       const pgDumpMajor = parsePgDumpMajor(pgDump);
 

package/src/role-chain.ts

@@ -85,13 +85,18 @@ export interface AdminRoleOptions {
 }
 
 /**
- * Generate idempotent DDL for the operator (admin) login role. Membership is granted BOTH
- * ways with the CURRENT user (the master/owner running the provision): owner → admin gives
- * the admin ownership rights over every owner-created object (no REASSIGN OWNED), and
- * admin → owner keeps the owner able to manage objects the admin creates later. The grants
- * are guarded so a RE-provision running AS the admin role (post-split, the ops connection
- * is this role) never attempts the self-grant Postgres hard-errors on. Does NOT set a
- * password — that's `db:provision`'s job, from a deploy-generated value.
+ * Generate idempotent DDL for the operator (admin) login role. Membership is granted ONE
+ * way — owner → admin — giving the admin ownership rights over every owner-created object
+ * (no REASSIGN OWNED). Never the reverse: Postgres forbids circular role membership, and
+ * the 0.4.0 reciprocal grant broke the SECOND stage on a shared RDS instance (roles are
+ * INSTANCE-level; the first stage's `migrator ∈ owner` membership made the reciprocal a
+ * cycle — 'role "migrator" is a member of role "postgres"').
+ *
+ * Adoption over creation: the grant is skipped when the membership already exists (a
+ * prior stage or a manual setup made it) and when granting would FORM a cycle (the owner
+ * is already a member of the admin role in some prior topology). A re-provision running
+ * AS the admin role (post-split, the ops connection is this role) skips the self-grant
+ * Postgres hard-errors on. Does NOT set a password — that's `db:provision`'s job.
  */
 export function generateAdminRoleSQL(options: AdminRoleOptions = {}): string {
   const adminRole = options.adminRole ?? 'migrator';
@@ -100,7 +105,7 @@ export function generateAdminRoleSQL(options: AdminRoleOptions = {}): string {
   const lines: string[] = [
     `DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '${adminRole}') THEN CREATE ROLE ${adminRole} LOGIN INHERIT NOBYPASSRLS; END IF; END $$;`,
     `ALTER ROLE ${adminRole} WITH LOGIN INHERIT NOBYPASSRLS;`,
-    `DO $$ BEGIN IF current_user <> '${adminRole}' THEN EXECUTE format('GRANT %I TO ${adminRole}', current_user); EXECUTE format('GRANT ${adminRole} TO %I', current_user); END IF; END $$;`,
+    `DO $$ BEGIN IF current_user <> '${adminRole}' AND NOT pg_has_role('${adminRole}', current_user, 'MEMBER') AND NOT pg_has_role(current_user, '${adminRole}', 'MEMBER') THEN EXECUTE format('GRANT %I TO ${adminRole}', current_user); END IF; END $$;`,
   ];
 
   return lines.join('\n') + '\n';