@supatype/cli 0.1.11 → 0.1.12

package/src/cli-version-embedded.ts

@@ -9,4 +9,4 @@
 // Annotated `string`, not left to inference: once a release stamps a value here, the
 // inferred literal type makes the `!== ""` test in cliPackageVersion() a compile error
 // (TS2367, no overlap), so the build would only fail during a release.
-export const EMBEDDED_CLI_VERSION: string = "0.1.11"
+export const EMBEDDED_CLI_VERSION: string = "0.1.12"

package/src/db-preflight.ts

@@ -113,6 +113,16 @@ async function probeLogicalDecoding(q: QueryFn): Promise<CheckResult> {
 
 const REQUIRED_ROLES = ["anon", "authenticated", "service_role", "authenticator"] as const
 
+/** The three roles PostgREST switches to per request. `authenticator` only connects and switches. */
+const API_ROLES = ["anon", "authenticated", "service_role"] as const
+
+/** One row per API role that exists, for the schema named in the query. */
+export interface AuthSchemaUsageRow {
+  rolname: string | null
+  has_usage: boolean | null
+  owner: string
+}
+
 /**
  * Stands in for the `authenticator` password when the operator has not supplied one.
  *
@@ -309,7 +319,7 @@ export async function runPreflight(
         WHERE g.rolname = 'authenticator'`,
     )
     const held = new Set(memberships.map((m) => m.rolname))
-    const needed = ["anon", "authenticated", "service_role"].filter((r) => !held.has(r))
+    const needed = API_ROLES.filter((r) => !held.has(r))
     results.push({
       id: "authenticator-memberships",
       title: "authenticator can reach the three API roles",
@@ -322,6 +332,19 @@ export async function runPreflight(
     })
   }
 
+  // USAGE on the auth schema, asked by OID so a role that does not exist cannot raise
+  // `role "x" does not exist` the way the name-taking overload would.
+  const authUsage = await q<AuthSchemaUsageRow>(
+    `SELECT r.rolname,
+            has_schema_privilege(r.oid, n.oid, 'USAGE') AS has_usage,
+            pg_get_userbyid(n.nspowner) AS owner
+       FROM pg_namespace n
+       LEFT JOIN pg_roles r ON r.rolname = ANY($1)
+      WHERE n.nspname = 'auth'`,
+    [API_ROLES as unknown as string[]],
+  )
+  results.push(authSchemaUsageCheck(authUsage, privs))
+
   // ── Extensions ─────────────────────────────────────────────────────────────
   const installed = new Set(
     (await q<{ extname: string }>("SELECT extname FROM pg_extension")).map((r) => r.extname),
@@ -456,6 +479,71 @@ export async function runPreflight(
   return { results, worst: worstOf(results) }
 }
 
+/**
+ * Can the API roles reach the auth helpers when a query calls them?
+ *
+ * Postgres evaluates a policy's `USING` clause with the table owner's privileges, so row-level
+ * security works without this grant and looks like proof the schema is fine. Field masking does
+ * not: `supatype_mask` rewrites a masked column into `CASE WHEN can_read_t__c(t) …` in the target
+ * list, which runs as the caller and reaches `auth.role()` directly. Studio's per-record
+ * `can_<op>_<table>` calls have the same shape.
+ *
+ * `supatype/postgres` grants this at initdb, so a missing grant means a database Supatype did not
+ * bootstrap. Kept a `degrade` rather than a `fail`: two named features stop working and the rest
+ * of the stack is unaffected.
+ */
+export function authSchemaUsageCheck(
+  rows: AuthSchemaUsageRow[],
+  privs: { current_user: string; is_super: boolean },
+): CheckResult {
+  const base = { id: "auth-schema-usage", title: "USAGE on schema auth (API roles)" }
+
+  // No auth schema yet: the first push creates it and grants on it, so there is nothing to fix.
+  if (rows.length === 0) {
+    return {
+      ...base,
+      severity: "pass",
+      detail: "schema auth does not exist yet; the first push creates it and grants usage",
+    }
+  }
+
+  const owner = rows[0]!.owner
+  const present = rows.filter((r) => r.rolname !== null)
+
+  // The roles check above owns this finding; repeating it here as a privilege problem would send
+  // the operator after the wrong fix.
+  if (present.length === 0) {
+    return { ...base, severity: "pass", detail: "no API roles exist on this server yet" }
+  }
+
+  const lacking = present.filter((r) => !r.has_usage).map((r) => r.rolname!)
+  if (lacking.length === 0) {
+    return {
+      ...base,
+      severity: "pass",
+      detail: `granted to ${present.map((r) => r.rolname).join(", ")} (schema owned by "${owner}")`,
+    }
+  }
+
+  // A grant from a role that owns neither the schema nor the server is discarded with a WARNING
+  // rather than an error, so `--fix` would report "Applied" having changed nothing. That is the
+  // same fault as a privilege generated and never applied, so hand it to the operator instead.
+  const canGrant = owner === privs.current_user || privs.is_super
+
+  return {
+    ...base,
+    severity: "degrade",
+    detail: `not granted to ${lacking.join(", ")} (schema owned by "${owner}")`,
+    impact:
+      "Field-level access is unavailable: a push declaring `access.fields` refuses rather than " +
+      "applying, and a masked column read by one of these roles fails with 42501 instead of " +
+      "masking. Studio's per-record permission checks fail the same way. Row-level security is " +
+      "unaffected, because Postgres evaluates policies with the table owner's privileges.",
+    remedy: `GRANT USAGE ON SCHEMA auth TO ${lacking.map(ident).join(", ")};`,
+    ...(!canGrant && { remedyNeedsOperator: true }),
+  }
+}
+
 function extensionCheck(
   name: string,
   installed: Set<string>,

package/tests/db-preflight.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest"
 import {
   PASSWORD_PLACEHOLDER,
+  authSchemaUsageCheck,
+  type AuthSchemaUsageRow,
   needsOperatorPassword,
   operatorRemedies,
   transactionalRemedies,
@@ -70,3 +72,81 @@ describe("the authenticator password guard", () => {
     expect(PASSWORD_PLACEHOLDER).toMatch(/^<.*>$/)
   })
 })
+
+describe("USAGE on the auth schema", () => {
+  const row = (rolname: string, has_usage: boolean, owner = "supatype_admin"): AuthSchemaUsageRow => ({
+    rolname,
+    has_usage,
+    owner,
+  })
+  const asOwner = { current_user: "supatype_admin", is_super: false }
+  const asStranger = { current_user: "app_migrator", is_super: false }
+
+  // Before the first push there is no auth schema, and the push creates it and grants on it.
+  // Reporting that as a problem would send the operator to fix something that fixes itself.
+  it("says nothing when the schema does not exist", () => {
+    const check = authSchemaUsageCheck([], asOwner)
+    expect(check.severity).toBe("pass")
+    expect(check.remedy).toBeUndefined()
+  })
+
+  it("passes when all three roles hold usage, and names the owner", () => {
+    const check = authSchemaUsageCheck(
+      [row("anon", true), row("authenticated", true), row("service_role", true)],
+      asOwner,
+    )
+    expect(check.severity).toBe("pass")
+    expect(check.detail).toContain("supatype_admin")
+    expect(check.remedy).toBeUndefined()
+  })
+
+  // Degrade, not fail: REST and RLS keep working because policies run with the table owner's
+  // privileges. Calling it a failure would exit non-zero on databases using neither feature.
+  it("degrades when a role lacks usage, and grants exactly that role", () => {
+    const check = authSchemaUsageCheck(
+      [row("anon", true), row("authenticated", false), row("service_role", true)],
+      asOwner,
+    )
+    expect(check.severity).toBe("degrade")
+    expect(check.remedy).toBe('GRANT USAGE ON SCHEMA auth TO "authenticated";')
+    expect(check.impact).toContain("access.fields")
+    expect(check.impact).toContain("42501")
+  })
+
+  it("grants every lacking role in one statement", () => {
+    const check = authSchemaUsageCheck(
+      [row("anon", false), row("authenticated", false), row("service_role", true)],
+      asOwner,
+    )
+    expect(check.remedy).toBe('GRANT USAGE ON SCHEMA auth TO "anon", "authenticated";')
+  })
+
+  // `--fix` applies remedies in a transaction and reports "Applied". Postgres discards a grant
+  // from a non-owner with a WARNING rather than an error, so without this flag `--fix` would
+  // report success having changed nothing.
+  it("hands the remedy to the operator when the caller cannot grant it", () => {
+    const check = authSchemaUsageCheck([row("authenticated", false)], asStranger)
+    expect(check.remedyNeedsOperator).toBe(true)
+  })
+
+  it("applies it itself when the caller owns the schema", () => {
+    const check = authSchemaUsageCheck([row("authenticated", false)], asOwner)
+    expect(check.remedyNeedsOperator).toBeUndefined()
+  })
+
+  it("applies it itself when the caller is a superuser on someone else's schema", () => {
+    const check = authSchemaUsageCheck(
+      [row("authenticated", false, "someone_else")],
+      { current_user: "postgres", is_super: true },
+    )
+    expect(check.remedyNeedsOperator).toBeUndefined()
+  })
+
+  // A LEFT JOIN against a server with none of the API roles yields one all-null row. The roles
+  // check owns that finding; reporting it here as a privilege problem points at the wrong fix.
+  it("defers to the roles check when no API role exists", () => {
+    const check = authSchemaUsageCheck([{ rolname: null, has_usage: null, owner: "postgres" }], asOwner)
+    expect(check.severity).toBe("pass")
+    expect(check.detail).toContain("no API roles")
+  })
+})