@everystack/server 0.4.31 → 0.4.33

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@everystack/server` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.33] - 2026-09-24
+
+### BREAKING CHANGES
+
+- a declared owner needs USAGE on its schema; db:apply refuses without it, db:provision (server 0.4.33) grants it
+
+### Fixed
+
+- name USAGE with CREATE for a missing schema; review follow-ups
+- reject offset-less datetime strings (ambiguous: server-local, not UTC)
+
+## [0.4.32] - 2026-09-21
+
+### Fixed
+
+- db:provision detects PUBLIC's CREATE on schema public, revokes it under --confirm
+
 ## [0.4.31] - 2026-09-16
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.31",
+  "version": "0.4.33",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -187,8 +187,8 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/cli": "0.4.85",
-    "@everystack/auth": "0.4.5"
+    "@everystack/auth": "0.4.6",
+    "@everystack/cli": "0.4.93"
   },
   "scripts": {
     "test": "jest",

package/src/owner-enactment.ts

@@ -11,6 +11,9 @@
  *      explicit SET ROLE, never inheriting the owner's privileges ambiently.
  *   2. `GRANT CREATE ON SCHEMA <schema> TO <owner>` — so the CREATE, which runs AS the owner,
  *      can place the object.
+ *   3. `GRANT USAGE ON SCHEMA <schema> TO <owner>` — so the owner's GRANT/REVOKE on that object,
+ *      which name it as `schema.object`, can resolve it. CREATE alone let the CREATE through and
+ *      then failed the object's own `REVOKE ALL … FROM PUBLIC` with `permission denied for schema`.
  *
  * These are privileged, idempotent SETUP — the same category as the role chain — so they belong
  * in db:provision, not in the least-privilege reconcile lane (which structurally cannot run them).
@@ -75,6 +78,8 @@ export interface OwnerFactRow {
   canSetRole: boolean;
   /** The owner already holds `CREATE` on the schema — no create grant needed. */
   ownerCanCreate: boolean;
+  /** The owner already holds `USAGE` on the schema — no usage grant needed. */
+  ownerCanUse: boolean;
 }
 
 /**
@@ -88,6 +93,8 @@ export interface GranterCapabilityRow {
   schema: string;
   canGrantMembership: boolean;
   canGrantCreate: boolean;
+  /** Can `GRANT USAGE ON SCHEMA` — owns the schema, holds USAGE WITH GRANT OPTION, or is a superuser. */
+  canGrantUsage: boolean;
 }
 
 /** Which connection runs a unit's statements. */
@@ -175,7 +182,8 @@ function assertIdent(name: string, what: string): void {
 
 /**
  * The connection-independent probe: for each (owner, schema), does the owner exist, does the
- * schema exist, can `operator` already SET ROLE the owner, and does the owner already hold CREATE.
+ * schema exist, can `operator` already SET ROLE the owner, and does the owner already hold CREATE
+ * and USAGE.
  * `has_schema_privilege` throws on an absent schema, so the schema is LEFT JOINed and the privilege
  * is evaluated only when the schema is really there. Run once, on either connection.
  */
@@ -195,7 +203,9 @@ SELECT
   (n.oid IS NOT NULL) AS schema_exists,
   CASE WHEN r.oid IS NULL THEN false ELSE pg_has_role('${operator}', r.oid, 'SET') END AS can_set_role,
   CASE WHEN r.oid IS NULL OR n.oid IS NULL THEN false
-       ELSE has_schema_privilege(r.oid, n.oid, 'CREATE') END AS owner_can_create
+       ELSE has_schema_privilege(r.oid, n.oid, 'CREATE') END AS owner_can_create,
+  CASE WHEN r.oid IS NULL OR n.oid IS NULL THEN false
+       ELSE has_schema_privilege(r.oid, n.oid, 'USAGE') END AS owner_can_use
 FROM declared d
 LEFT JOIN pg_roles r ON r.rolname = d.owner_name
 LEFT JOIN pg_namespace n ON n.nspname = d.schema_name
@@ -207,7 +217,8 @@ ORDER BY d.owner_name, d.schema_name
  * The connection-DEPENDENT probe: run on a connection to learn what CURRENT_USER can grant.
  * Can it `GRANT <owner> TO <operator>` — it holds ADMIN OPTION on the owner, directly or through a
  * group. Can it `GRANT CREATE ON SCHEMA <schema>` — it owns the schema or holds CREATE WITH GRANT
- * OPTION. A REAL superuser can do both unconditionally. Run on the operator's connection and, when
+ * OPTION, and `GRANT USAGE ON SCHEMA` — it owns the schema or holds USAGE WITH GRANT OPTION. A REAL
+ * superuser can do all three unconditionally. Run on the operator's connection and, when
  * present, on the master's; the router merges the two.
  *
  * MEMBERSHIP IN `rds_superuser` IS NOT SUPERUSER, and this probe no longer pretends it is. RDS's
@@ -238,7 +249,9 @@ SELECT
   d.schema_name AS schema,
   COALESCE(me.is_super OR pg_has_role(me.oid, r.oid, 'MEMBER WITH ADMIN OPTION'), false) AS can_grant_membership,
   COALESCE(me.is_super OR n.nspowner = me.oid
-     OR has_schema_privilege(me.oid, n.oid, 'CREATE WITH GRANT OPTION'), false) AS can_grant_create
+     OR has_schema_privilege(me.oid, n.oid, 'CREATE WITH GRANT OPTION'), false) AS can_grant_create,
+  COALESCE(me.is_super OR n.nspowner = me.oid
+     OR has_schema_privilege(me.oid, n.oid, 'USAGE WITH GRANT OPTION'), false) AS can_grant_usage
 FROM declared d
 CROSS JOIN me
 LEFT JOIN pg_roles r ON r.rolname = d.owner_name
@@ -250,7 +263,8 @@ ORDER BY d.owner_name, d.schema_name
 const keyOf = (owner: string, schema: string) => `${owner}\u0000${schema}`;
 
 /**
- * Route the two grants each (owner, schema) may need onto the connection that can run them.
+ * Route the three grants each (owner, schema) may need — membership, CREATE, USAGE — onto the
+ * connection that can run them.
  *
  * `operator` is the least-privilege role (`migrator`). `masterCaps` is null when no master
  * connection is available — then anything the operator cannot do is a refusal, never an
@@ -305,6 +319,16 @@ export function planOwnerEnactment(
         `Run as the schema owner:  ${stmt};`,
       );
     }
+    // 3. Usage: the owner's GRANT/REVOKE on the object name `schema.object` — resolving it needs USAGE.
+    if (f.schemaExists && !f.ownerCanUse) {
+      const stmt = `GRANT USAGE ON SCHEMA ${f.schema} TO ${f.owner}`;
+      if (op?.canGrantUsage) addUnit(b, subject, 'operator', [stmt]);
+      else if (master?.canGrantUsage) addUnit(b, subject, 'master', [stmt]);
+      else plan.refusals.push(
+        `cannot GRANT USAGE ON SCHEMA ${f.schema} TO ${f.owner}: neither connection owns the schema or holds USAGE WITH GRANT OPTION. ` +
+        `Run as the schema owner:  ${stmt};`,
+      );
+    }
     // An absent schema is not enacted here — it is created by the reconcile builder, whose own
     // preflight then names the owner's missing CREATE. Enactment acts only on what exists.
   }

package/src/provision.ts

@@ -196,9 +196,25 @@ export interface ProvisionResult {
    * anything and never throw — a reader that cannot read is loud, recoverable, and reported.
    */
   readerGrants?: { granted: number; refusals: string[] };
+  /**
+   * The PUBLIC-on-schema-`public` posture, and what (if anything) was done about it. Always present
+   * once convergence has run — `publicCanCreate: false` is the already-clean answer, and the CLI
+   * says nothing about it. Same non-fatal contract as ENACT: never throws, never aborts.
+   */
+  publicSchemaPosture?: PublicSchemaPosture;
   error?: string;
 }
 
+/** The result of the PUBLIC-on-`public` posture step. See `convergePublicSchemaPosture`. */
+export interface PublicSchemaPosture {
+  /** Does the PUBLIC pseudo-role hold CREATE on schema `public`? (The pre-PG15 default.) */
+  publicCanCreate: boolean;
+  /** Was the REVOKE applied AND verified? Only ever true when `publicCanCreate` was true. */
+  revoked: boolean;
+  /** Why it was not applied — the missing `--confirm`, a connection that cannot, a server refusal. */
+  refusals: string[];
+}
+
 const ALNUM = /^[A-Za-z0-9]+$/;
 
 export async function runProvision(
@@ -384,8 +400,8 @@ export async function runProvision(
 export async function convergeOwnership(
   payload: Pick<ProvisionPayload, 'declaredOwners' | 'declaredObjects' | 'confirm' | 'adminRole' | 'readerRole' | 'searchPath'>,
   deps: ProvisionDeps,
-): Promise<Pick<ProvisionResult, 'ownerEnactment' | 'ownerAdoption' | 'readerGrants'>> {
-  const out: Pick<ProvisionResult, 'ownerEnactment' | 'ownerAdoption' | 'readerGrants'> = {};
+): Promise<Pick<ProvisionResult, 'ownerEnactment' | 'ownerAdoption' | 'readerGrants' | 'publicSchemaPosture'>> {
+  const out: Pick<ProvisionResult, 'ownerEnactment' | 'ownerAdoption' | 'readerGrants' | 'publicSchemaPosture'> = {};
   if (!deps.query) return out;
   const operator = payload.adminRole ?? 'migrator';
 
@@ -416,11 +432,143 @@ export async function convergeOwnership(
       out.readerGrants = { granted: 0, refusals: [`reader grants failed (credentials are already saved; nothing is stranded): ${err?.message ?? String(err)}`] };
     }
   }
+
+  // The PUBLIC-on-`public` posture — LAST, and UNCONDITIONAL. It is a property of the DATABASE, not
+  // of what the Models declare, so it must not hide behind the declared-ownership guards above: the
+  // brownfield app with nothing declared is precisely the one most likely to carry the pre-PG15
+  // grant. One catalog read on a converged database, one statement when the operator has confirmed.
+  try {
+    out.publicSchemaPosture = await convergePublicSchemaPosture(deps, !!payload.confirm);
+  } catch (err: any) {
+    out.publicSchemaPosture = { publicCanCreate: false, revoked: false, refusals: [
+      `the schema "public" posture check failed (credentials are already saved; nothing is stranded): ${err?.message ?? String(err)}`,
+    ] };
+  }
   return out;
 }
 
 const truthy = (v: unknown): boolean => v === true || v === 't' || v === 'true';
 
+/** The one statement this step ever sends. Also the fix SQL every refusal below hands back. */
+export const REVOKE_PUBLIC_CREATE_SQL = 'REVOKE CREATE ON SCHEMA public FROM PUBLIC';
+
+/**
+ * The posture probe: does the PUBLIC pseudo-role hold CREATE on schema `public`, and can THIS
+ * connection take it away?
+ *
+ * `public_can_create` reads the ACL directly rather than asking `has_schema_privilege('public', …)`.
+ * Both answer correctly on a live server (measured, PG16), but the ACL read is the idiom the rest of
+ * this file already uses (`toFacts`/`toCaps` over `aclexplode`) and it is unambiguous: grantee 0 IS
+ * the PUBLIC pseudo-role, whereas the literal `'public'` in `has_schema_privilege` is a special-cased
+ * NAME that resolves to no row in `pg_roles`. A NULL `nspacl` (owner-only defaults, and what a
+ * hand-recreated `public` schema carries on every version) explodes to zero rows — correctly, no grant.
+ *
+ * This is deliberately NOT `server_version_num`. PG15 removed the grant as a DEFAULT; it says nothing
+ * about the database in front of us. A PG16 database restored from a pre-15 dump still carries it, and
+ * an operator can re-add it on any version with one legal statement. The catalog is the only truth.
+ *
+ * `can_revoke` is the capability half, and it is load-bearing for a reason PostgreSQL makes easy to
+ * miss: a REVOKE run by a role that does not administer the schema DOES NOT FAIL. It emits
+ * `WARNING: no privileges could be revoked for "public"` and returns success with the grant still in
+ * place. `pg_has_role(current_user, nspowner, 'USAGE')` is true for the schema's owner, for a member
+ * of it, and for a superuser — exactly the set that can actually revoke.
+ */
+export const PUBLIC_SCHEMA_POSTURE_SQL = `SELECT
+  EXISTS (
+    SELECT 1 FROM pg_namespace n, aclexplode(n.nspacl) a
+    WHERE n.nspname = 'public' AND a.grantee = 0 AND a.privilege_type = 'CREATE'
+  ) AS public_can_create,
+  EXISTS (
+    SELECT 1 FROM pg_namespace n
+    WHERE n.nspname = 'public' AND pg_has_role(current_user, n.nspowner, 'USAGE')
+  ) AS can_revoke`;
+
+/**
+ * Converge the PUBLIC-on-schema-`public` posture — detect always, act only under `confirm`.
+ *
+ * THE GAP. Before PG15, `CREATE ON SCHEMA public` was granted to the PUBLIC pseudo-role by default.
+ * PG15 removed that default. Where it is still in place, every login this file provisions —
+ * authenticator, migrator, reader — can create objects in `public` through an ambient grant none of
+ * them was given, whatever its own privileges say. A schema anyone can write is also a search_path
+ * hijack surface: plant a shadow object there and a privileged session resolving through `public`
+ * runs it (the same chain `security-audit` reds on).
+ *
+ * WHY THIS IS GATED, when db:build revokes the same grant unconditionally. db:build refuses a
+ * non-empty target, so there is nothing in `public` to strand and no app to surprise. db:provision
+ * has no such guarantee: it runs against a LIVE, often long-running database, and some legacy apps
+ * genuinely create objects in `public` at runtime. Taking that away silently, mid-deploy, is a
+ * behaviour change no one asked for. So this reports by default and acts only when the operator has
+ * seen the report and re-run with `--confirm` — the same shape ADOPT uses for its runtime-changing
+ * reassignments.
+ *
+ * ROUTED like ENACT's grants: the operator's own connection when it administers `public`, the master
+ * when it does not, and a refusal carrying the runnable SQL when neither can. VERIFIED after the
+ * fact, because — see PUBLIC_SCHEMA_POSTURE_SQL — an under-privileged REVOKE reports success while
+ * changing nothing, so "the statement ran" would have printed `revoked` over a wide-open database.
+ *
+ * Non-fatal by construction: it never throws. It runs strictly after the credential is in the secret
+ * store, so anything it fails to do is recoverable by a re-run and strands nothing.
+ */
+export async function convergePublicSchemaPosture(
+  deps: ProvisionDeps,
+  confirm: boolean,
+): Promise<PublicSchemaPosture> {
+  const query = deps.query;
+  if (!query) return { publicCanCreate: false, revoked: false, refusals: [] };
+
+  const [row] = await query(PUBLIC_SCHEMA_POSTURE_SQL);
+  if (!truthy(row?.public_can_create)) return { publicCanCreate: false, revoked: false, refusals: [] };
+
+  if (!confirm) {
+    return { publicCanCreate: true, revoked: false, refusals: [
+      'the PUBLIC pseudo-role holds CREATE on schema "public" — the pre-PG15 default, which PG15 ' +
+      'removed. Every login this provision created can place objects there through that ambient ' +
+      'grant, and a writable schema on a search path is a hijack surface for every privileged ' +
+      'session resolving through it. Taking it away can break an app that creates objects in ' +
+      '"public" at runtime, so it is NOT done silently: review, then re-run with --confirm. ' +
+      `The statement it would send:  ${REVOKE_PUBLIC_CREATE_SQL};`,
+    ] };
+  }
+
+  // Route to a connection that can actually revoke. The operator usually does not own `public`
+  // (postgres or pg_database_owner does), so the master is the normal venue.
+  let execute: ((sql: string) => Promise<unknown>) | null = null;
+  if (truthy(row?.can_revoke)) {
+    execute = deps.execute;
+  } else if (deps.master) {
+    const [masterRow] = await deps.master.query(PUBLIC_SCHEMA_POSTURE_SQL);
+    if (truthy(masterRow?.can_revoke)) execute = (s: string) => deps.master!.execute(s);
+  }
+  if (!execute) {
+    return { publicCanCreate: true, revoked: false, refusals: [
+      'cannot revoke PUBLIC\'s CREATE on schema "public": neither the operator connection nor the ' +
+      'master is the owner of schema "public" (nor a member of its owner). PostgreSQL would accept ' +
+      'the statement from them and change NOTHING — it warns "no privileges could be revoked" and ' +
+      `returns success. Run it as the schema's owner:  ${REVOKE_PUBLIC_CREATE_SQL};`,
+    ] };
+  }
+
+  try {
+    await execute(`${REVOKE_PUBLIC_CREATE_SQL};`);
+  } catch (err: any) {
+    return { publicCanCreate: true, revoked: false, refusals: [
+      `revoking PUBLIC's CREATE on schema "public" failed: ${err?.message ?? String(err)}. ` +
+      `Nothing else is affected — credentials are already saved. Fix:  ${REVOKE_PUBLIC_CREATE_SQL};`,
+    ] };
+  }
+
+  // VERIFY. The statement completing is not evidence (see above), so re-read the catalog.
+  const [after] = await query(PUBLIC_SCHEMA_POSTURE_SQL);
+  if (truthy(after?.public_can_create)) {
+    return { publicCanCreate: true, revoked: false, refusals: [
+      'the REVOKE was accepted but PUBLIC still holds CREATE on schema "public". PostgreSQL does ' +
+      'not error when a role that does not administer the schema revokes — it warns and changes ' +
+      `nothing. Run it as the schema's owner:  ${REVOKE_PUBLIC_CREATE_SQL};`,
+    ] };
+  }
+  return { publicCanCreate: true, revoked: true, refusals: [] };
+}
+
 /**
  * Run `statements` as ONE transaction on `execute`, and leave the SESSION usable whatever happens.
  *
@@ -458,6 +606,7 @@ function toFacts(rows: any[]): OwnerFactRow[] {
     schemaExists: truthy(r.schema_exists),
     canSetRole: truthy(r.can_set_role),
     ownerCanCreate: truthy(r.owner_can_create),
+    ownerCanUse: truthy(r.owner_can_use),
   }));
 }
 
@@ -467,6 +616,7 @@ function toCaps(rows: any[]): GranterCapabilityRow[] {
     schema: String(r.schema),
     canGrantMembership: truthy(r.can_grant_membership),
     canGrantCreate: truthy(r.can_grant_create),
+    canGrantUsage: truthy(r.can_grant_usage),
   }));
 }