@supacloud/db 0.5.0 → 0.6.0

package/MIGRATION_BINDINGS.md

@@ -0,0 +1,138 @@
+# Controlled Migration Bindings
+
+This is a deployment-time API for **public environment bindings**, not a general
+SQL template language or another migration engine. Use identical migrations for
+schema, indexes, business functions and state machines. Explicitly register only
+SQL that must bind to a target-specific application ID, HTTPS URL or resource
+name. One-off account transfers and production data cleanup remain separately
+reviewed operations.
+
+## Drizzle v1 Boundary
+
+Reviewed against the Drizzle v1 PostgreSQL documentation on 2026-09-08:
+official documentation repository commit
+`dae09afd99baa6362ece434cfa7bab60ef4b8692`.
+
+- [Upgrade to v1](https://orm.drizzle.team/docs/upgrade-v1):
+  v1 removes the journal file and groups SQL and snapshots in migration folders.
+  Do not run `drizzle-kit up` automatically on an application's existing history.
+- [Custom migrations](https://orm.drizzle.team/docs/kit-custom-migrations):
+  `drizzle-kit generate --custom` is the extension point for custom SQL.
+- [Migrate](https://orm.drizzle.team/docs/drizzle-kit-migrate):
+  migration execution reads applied history and supports separate configuration
+  files for different deployment targets.
+
+Those documents do not define this parameter-rendering API. This is a SupaCloud
+extension, not a claim that Drizzle automatically reconciles account changes.
+The renderer accepts `20260908100000_binding/migration.sql` as well as legacy
+flat SQL filenames. It neither discovers nor changes snapshots, migration
+identities, order, or metadata. Call it on a deployment copy, never write its
+output over generated source SQL. When SupaCloud is the executor, continue using
+its canonical applied-migration ledger; do not additionally execute
+`drizzle-kit migrate` against that same migration stream.
+
+## Usage
+
+Commit a manifest containing explicit target pairs and reviewed source hashes.
+`templateSha256` is the SHA-256 of the exact UTF-8 source, including whitespace.
+An author obtains and reviews it once when adding a template; do not recompute
+and accept a changed source hash automatically during deployment.
+
+```ts
+import { renderMigrationBindings } from '@supacloud/db';
+
+const result = renderMigrationBindings({
+  manifest: {
+    schema: 'supacloud.migration-bindings.v1',
+    targets: [
+      { environment: 'test', projectRef: 'test-project' },
+      { environment: 'production', projectRef: 'production-project' },
+    ],
+    templates: [{
+      file: '20260908100000_binding/migration.sql',
+      templateSha256: reviewedSourceSha256,
+      parameters: [{
+        placeholder: '__SC_BINDING_APPLICATION_ID__',
+        variable: 'APPLICATION_ID',
+        type: 'uuid',
+        occurrences: 1,
+      }],
+    }],
+  },
+  target: selectedTarget,
+  migrations: sourceFiles,
+  values: selectedEnvironment,
+});
+// Send result.migrations to the existing dry-run/apply pipeline.
+// Persist result.attestation in the existing release artifacts.
+```
+
+Example source:
+
+```sql
+SELECT '__SC_BINDING_APPLICATION_ID__'::uuid;
+```
+
+The caller must select and verify the environment before invoking this API.
+Values are explicitly passed; the API does not read `process.env`, env files,
+SSH configuration, or another target's fallback values. The target pair must
+match the manifest. The full set of declared template sources must be supplied.
+Plain SQL sources pass through byte-for-byte.
+
+Only complete single-quoted placeholder literals are supported, including
+literals in dollar-quoted PostgreSQL function bodies. `uuid`, `https-url`, and
+`resource-name` have restricted alphabets excluding quotes, dollar delimiters,
+backslashes and control characters. HTTPS URLs must not contain userinfo.
+Do not put credentials, tokens, secrets or arbitrary text in these bindings.
+Object identifiers, SQL fragments and arbitrary string interpolation are
+intentionally unsupported.
+
+`__SC_BINDING_*__` is reserved. Undeclared reserved tokens, stray declared
+legacy tokens, duplicate definitions, missing inputs, changed source bytes,
+wrong occurrence counts, unknown fields and unknown types fail closed.
+Legacy tokens such as `__FA_SUPAUTH_CLIENT_ID__` can be explicitly declared
+without editing historical SQL.
+
+## Evidence And Changes
+
+The attestation includes the target pair, manifest digest, source digest,
+rendered digest and parameter names/types. It excludes SQL and parameter values.
+The returned `migrations` contain SQL and must not be logged as an attestation.
+This is reproducibility evidence, not a signature or proof of the database's
+current state. Store it in an existing access-controlled release receipt or
+artifact, and separately read back the target's applied migration inventory.
+
+The renderer never marks a migration as applied and has no database access.
+Compare the rendered SQL with the existing executor's inventory. A changed
+environment value is **not** permission to rewrite an applied migration or its
+ledger row. Add a forward binding migration and retain the old release artifact;
+historical reconciliation must use target-specific reviewed evidence.
+
+The CLI does not automatically enable this API. An application deployment
+adapter must supply the selected sources and target, then use its existing
+executor. In particular, this API does not add recursive Drizzle-folder discovery
+to the CLI's legacy flat-directory `push_migrations` command.
+
+## Acceptance
+
+```gherkin
+Scenario: Same template, separate targets
+  Given a reviewed template and explicit test and production project bindings
+  When each target provides its own valid parameters
+  Then source digests match and rendered digests differ without changing source files
+
+Scenario: Missing or unsafe parameter
+  Given a missing value, injected SQL fragment or secret-bearing URL
+  When rendering begins
+  Then it fails without echoing the supplied value or requesting any database mutation
+
+Scenario: Undeclared or changed SQL
+  Given a changed template, unexpected token or unregistered target
+  When rendering begins
+  Then deployment preparation fails before SQL is returned
+
+Scenario: Applied parameter changes
+  Given an already-applied binding migration and a changed parameter
+  When rendering again
+  Then a different digest is produced, not an automatic replay or ledger repair
+```

package/README.md

@@ -1,5 +1,9 @@
 # @supacloud/db
 
+For reviewed deployment-time public SQL parameters, see
+[Controlled Migration Bindings](./MIGRATION_BINDINGS.md). This opt-in API preserves
+Drizzle v1 source/snapshot ownership and the existing executor's migration ledger.
+
 SupaCloud 的数据库治理层：把 RLS 策略、RPC 函数、触发器、授权（grant）作为**一等资源**做声明式管理，并与 PostgreSQL 真实 Catalog 对账。
 
 定位：它是 Drizzle（schema/迁移）之上的治理层 —— Drizzle 负责表结构，本包负责表结构之外的安全与业务对象（策略、函数、权限）的声明、静态检查与漂移检测。**driver 无关**：所有 Catalog 读取都通过注入的 `QueryExecutor` 完成，不依赖任何数据库客户端，也不 import drizzle-orm（仅类型层兼容 drizzle Table 的内部形状）。

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { reconcileModule, splitQualifiedName, type ReconcileIssue, type Reconcil
 export { lintModule, lintSql, type LintIssue } from './lint.js';
 export { planModule, type ModulePlan, type PlanStep } from './plan.js';
 export { applyModulePlan, type ApplyResult } from './apply.js';
+export { migrationBindingSha256, parseMigrationBindingManifest, renderMigrationBindings, type MigrationBindingManifest, type MigrationBindingParameter, type MigrationBindingSource, type MigrationBindingTarget, type MigrationBindingTemplate, type MigrationBindingType, } from './migration-bindings.js';
 export { buildDatabaseManifest, explainObject, type DatabaseManifest, type DatabaseManifestModule, } from './manifest.js';
 export { createDatabaseAccessBoundary, DatabaseAccessError, type AuthenticatedDatabaseIdentity, type DatabaseAccessBoundary, type DatabaseAccessBoundaryOptions, type DatabaseAccessErrorCode, } from './access.js';
 export { createRpcClient, defineRpcContract, RpcContractError, type RpcArgs, type RpcCallResult, type RpcContract, type RpcDecoder, type RpcResult, type RpcTransport, } from './rpc.js';

package/dist/index.js

@@ -531,6 +531,152 @@ async function applyModulePlan(executor, plan) {
   }
   return result;
 }
+// src/migration-bindings.ts
+import { createHash } from "node:crypto";
+var TOKEN = /__[A-Z][A-Z0-9_]*__/g;
+var RESERVED_TOKEN = /__SC_BINDING_[A-Z0-9_]+__/;
+var HASH = /^[a-f0-9]{64}$/;
+function migrationBindingSha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function record(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Invalid migration binding object");
+  }
+  return value;
+}
+function keys(row, expected) {
+  if (Object.keys(row).sort().join(",") !== expected.sort().join(",")) {
+    throw new Error("Unexpected migration binding fields");
+  }
+}
+function validTarget(value) {
+  const target = record(value);
+  keys(target, ["environment", "projectRef"]);
+  if (typeof target.environment !== "string" || !/^[a-z][a-z0-9-]{0,62}$/.test(target.environment) || typeof target.projectRef !== "string" || !/^[a-z0-9][a-z0-9_-]{0,62}$/.test(target.projectRef)) {
+    throw new Error("Invalid migration binding target");
+  }
+  return target;
+}
+function validFile(file) {
+  return typeof file === "string" && /^[a-zA-Z0-9_./-]+\.sql$/.test(file) && !file.startsWith("/") && file.split("/").every((part) => part && part !== "." && part !== "..");
+}
+function parseMigrationBindingManifest(value) {
+  const manifest = record(value);
+  keys(manifest, ["schema", "targets", "templates"]);
+  if (manifest.schema !== "supacloud.migration-bindings.v1" || !Array.isArray(manifest.targets) || !manifest.targets.length || !Array.isArray(manifest.templates)) {
+    throw new Error("Invalid migration binding manifest");
+  }
+  const targets = manifest.targets.map(validTarget);
+  if (new Set(targets.map((target) => target.environment)).size !== targets.length) {
+    throw new Error("Duplicate migration binding environment");
+  }
+  const files = new Set;
+  const templates = manifest.templates.map((value2) => {
+    const template = record(value2);
+    keys(template, ["file", "templateSha256", "parameters"]);
+    if (!validFile(template.file) || files.has(template.file) || typeof template.templateSha256 !== "string" || !HASH.test(template.templateSha256) || !Array.isArray(template.parameters) || !template.parameters.length) {
+      throw new Error("Invalid or duplicate migration binding template");
+    }
+    files.add(template.file);
+    const placeholders = new Set;
+    const parameters = template.parameters.map((value3) => {
+      const parameter = record(value3);
+      keys(parameter, ["placeholder", "variable", "type", "occurrences"]);
+      if (typeof parameter.placeholder !== "string" || !/^__[A-Z][A-Z0-9_]*__$/.test(parameter.placeholder) || placeholders.has(parameter.placeholder) || typeof parameter.variable !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(parameter.variable) || !["uuid", "https-url", "resource-name"].includes(String(parameter.type)) || !Number.isSafeInteger(parameter.occurrences) || Number(parameter.occurrences) < 1) {
+        throw new Error("Invalid or duplicate migration binding parameter");
+      }
+      placeholders.add(parameter.placeholder);
+      return parameter;
+    });
+    return { file: template.file, templateSha256: template.templateSha256, parameters };
+  });
+  return { schema: "supacloud.migration-bindings.v1", targets, templates };
+}
+function bindingValue(parameter, values) {
+  const value = Object.hasOwn(values, parameter.variable) ? values[parameter.variable] : undefined;
+  if (typeof value !== "string" || !value || value.trim() !== value) {
+    throw new Error(`Missing or invalid migration binding variable: ${parameter.variable}`);
+  }
+  let valid = false;
+  if (parameter.type === "uuid") {
+    valid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+  } else if (parameter.type === "resource-name") {
+    valid = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,254}$/.test(value);
+  } else if (/^https:\/\/[A-Za-z0-9._~:/?#[\]@!&()*+,;=%-]+$/.test(value)) {
+    try {
+      const url = new URL(value);
+      valid = url.protocol === "https:" && Boolean(url.hostname) && !url.username && !url.password;
+    } catch {}
+  }
+  if (!valid || value.includes("__"))
+    throw new Error(`Invalid ${parameter.type} migration binding: ${parameter.variable}`);
+  return value;
+}
+function renderMigrationBindings(options) {
+  const manifest = parseMigrationBindingManifest(options.manifest);
+  const target = validTarget(options.target);
+  if (!manifest.targets.some((candidate) => candidate.environment === target.environment && candidate.projectRef === target.projectRef)) {
+    throw new Error("Migration binding target is not registered in the manifest");
+  }
+  const sources = new Map;
+  for (const migration of options.migrations) {
+    if (!validFile(migration.file) || sources.has(migration.file) || typeof migration.sql !== "string" || !migration.sql.trim()) {
+      throw new Error("Invalid, empty, or duplicate migration binding source");
+    }
+    sources.set(migration.file, migration);
+  }
+  if (manifest.templates.some((template) => !sources.has(template.file))) {
+    throw new Error("Migration binding manifest references a missing source");
+  }
+  const templates = new Map(manifest.templates.map((template) => [template.file, template]));
+  const declaredTokens = new Set(manifest.templates.flatMap((template) => template.parameters.map((parameter) => parameter.placeholder)));
+  const files = [];
+  const migrations = options.migrations.map((migration) => {
+    const template = templates.get(migration.file);
+    const templateSha256 = migrationBindingSha256(migration.sql);
+    if (template && templateSha256 !== template.templateSha256) {
+      throw new Error(`Migration binding template checksum mismatch: ${migration.file}`);
+    }
+    const parameters = new Map(template?.parameters.map((parameter) => [parameter.placeholder, parameter]));
+    const counts = new Map;
+    const sql = migration.sql.replace(TOKEN, (token, offset) => {
+      const parameter = parameters.get(token);
+      if (!parameter) {
+        if (RESERVED_TOKEN.test(token) || declaredTokens.has(token)) {
+          throw new Error(`Undeclared migration binding placeholder: ${migration.file}`);
+        }
+        return token;
+      }
+      if (migration.sql[offset - 1] !== "'" || migration.sql[offset + token.length] !== "'") {
+        throw new Error(`Migration bindings must occupy a complete SQL string literal: ${migration.file}`);
+      }
+      counts.set(token, (counts.get(token) || 0) + 1);
+      return bindingValue(parameter, options.values);
+    });
+    for (const parameter of parameters.values()) {
+      if (counts.get(parameter.placeholder) !== parameter.occurrences) {
+        throw new Error(`Migration binding occurrence mismatch: ${migration.file}`);
+      }
+    }
+    files.push({
+      file: migration.file,
+      templateSha256,
+      renderedSqlSha256: migrationBindingSha256(sql),
+      parameters: [...parameters.values()].map(({ variable, type }) => ({ variable, type }))
+    });
+    return { file: migration.file, sql };
+  });
+  return {
+    migrations,
+    attestation: {
+      schema: "supacloud.migration-binding-attestation.v1",
+      ...target,
+      manifestSha256: migrationBindingSha256(JSON.stringify(manifest)),
+      files: files.sort((left, right) => left.file.localeCompare(right.file))
+    }
+  };
+}
 // src/manifest.ts
 function buildDatabaseManifest(modules) {
   return {
@@ -746,8 +892,11 @@ export {
   extractSearchPath,
   lintModule,
   lintSql,
+  migrationBindingSha256,
+  parseMigrationBindingManifest,
   planModule,
   readCatalog,
   reconcileModule,
+  renderMigrationBindings,
   splitQualifiedName
 };

package/dist/migration-bindings.d.ts

@@ -0,0 +1,57 @@
+export type MigrationBindingType = 'uuid' | 'https-url' | 'resource-name';
+export interface MigrationBindingTarget {
+    environment: string;
+    projectRef: string;
+}
+export interface MigrationBindingParameter {
+    placeholder: string;
+    variable: string;
+    type: MigrationBindingType;
+    occurrences: number;
+}
+export interface MigrationBindingTemplate {
+    file: string;
+    templateSha256: string;
+    parameters: MigrationBindingParameter[];
+}
+export interface MigrationBindingManifest {
+    schema: 'supacloud.migration-bindings.v1';
+    targets: MigrationBindingTarget[];
+    templates: MigrationBindingTemplate[];
+}
+export interface MigrationBindingSource {
+    file: string;
+    sql: string;
+}
+export declare function migrationBindingSha256(value: string): string;
+export declare function parseMigrationBindingManifest(value: unknown): MigrationBindingManifest;
+/**
+ * Pure rendering of explicitly declared SQL literals. The caller supplies an
+ * already-selected environment; this module never reads files or process.env.
+ */
+export declare function renderMigrationBindings(options: {
+    manifest: unknown;
+    target: MigrationBindingTarget;
+    migrations: readonly MigrationBindingSource[];
+    values: Readonly<Record<string, string | undefined>>;
+}): {
+    migrations: {
+        file: string;
+        sql: string;
+    }[];
+    attestation: {
+        environment: string;
+        projectRef: string;
+        schema: 'supacloud.migration-binding-attestation.v1';
+        manifestSha256: string;
+        files: {
+            file: string;
+            templateSha256: string;
+            renderedSqlSha256: string;
+            parameters: Array<{
+                variable: string;
+                type: MigrationBindingType;
+            }>;
+        }[];
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/db",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Database governance layer for SupaCloud: RLS policies, RPC functions and grants as first-class resources, with manifest/catalog reconciliation",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "MIGRATION_BINDINGS.md"
   ],
   "scripts": {
     "build": "bun run clean && bun run build:js && bun run build:types",