@supacloud/db 0.3.1 → 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 的内部形状）。
@@ -79,6 +83,40 @@ const userDb = await database.forUser(requireTrustedIdentity(requestContext));
 const workerDb = await database.forService("scheduled-worker");
 ```
 
+### Typed RPC boundary
+
+`createRpcClient(transport, contracts)` validates arguments before transport and results
+before returning them. Names, arguments and results are inferred from the registry;
+callers cannot supply an arbitrary result type. It uses the supplied client without
+changing its identity, RLS policy or credentials.
+
+```ts
+import { createRpcClient, defineRpcContract } from '@supacloud/db';
+
+const rpc = createRpcClient(userDb, {
+  case_create: defineRpcContract({
+    args: decodeCreateCaseArgs,
+    result: decodeCreatedCase,
+  }),
+});
+const result = await rpc.call('case_create', { title: 'Investigation' });
+if (result.ok) {
+  console.log(result.data);
+} else {
+  handleDatabaseFailure(result.error);
+}
+```
+
+Decoders must accept `unknown`, validate it at runtime and throw on invalid values.
+They may project extra fields away. Schema libraries such as TypeBox can supply
+these functions; this driver-independent package adds no schema-library dependency.
+Database failures bypass result decoding. Contract failures throw `RpcContractError`
+with a phase and no raw payload or decoder error. Calls are never retried automatically,
+including result-validation failures after a potentially committed command.
+
+This is an explicit contract boundary, not inference of JSONB fields from SQL,
+authorization, migration execution or automatic HTTP client generation.
+
 ## 诊断码
 
 ### 对账（reconcile）

package/dist/index.d.ts

@@ -4,5 +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 {
@@ -682,18 +828,75 @@ function createDatabaseAccessBoundary(options) {
     }
   };
 }
+// src/rpc.ts
+class RpcContractError extends Error {
+  rpcName;
+  phase;
+  code = "RPC_CONTRACT_INVALID";
+  constructor(rpcName, phase) {
+    super(`RPC contract validation failed (${phase})`);
+    this.rpcName = rpcName;
+    this.phase = phase;
+    this.name = "RpcContractError";
+  }
+}
+function defineRpcContract(contract) {
+  return Object.freeze({ ...contract });
+}
+function createRpcClient(transport, contracts) {
+  const registered = new Map(Object.entries(contracts).map(([name, contract]) => [
+    name,
+    defineRpcContract(contract)
+  ]));
+  return {
+    async call(name, args) {
+      const contract = registered.get(name);
+      if (!contract)
+        throw new RpcContractError(name, "registration");
+      let decodedArgs;
+      try {
+        decodedArgs = contract.args(args);
+        if (!decodedArgs || typeof decodedArgs !== "object" || Array.isArray(decodedArgs)) {
+          throw new TypeError("RPC arguments must decode to an object");
+        }
+      } catch {
+        throw new RpcContractError(name, "args");
+      }
+      const response = await transport.rpc(name, decodedArgs);
+      if (!response || typeof response !== "object" || Array.isArray(response) || !Object.hasOwn(response, "error")) {
+        throw new RpcContractError(name, "result");
+      }
+      if (response.error != null)
+        return { ok: false, data: null, error: response.error };
+      if (!Object.hasOwn(response, "data"))
+        throw new RpcContractError(name, "result");
+      try {
+        const data = contract.result(response.data);
+        return { ok: true, data, error: null };
+      } catch {
+        throw new RpcContractError(name, "result");
+      }
+    }
+  };
+}
 export {
   DatabaseAccessError,
+  RpcContractError,
   applyModulePlan,
   buildDatabaseManifest,
   createDatabaseAccessBoundary,
+  createRpcClient,
   defineDatabaseModule,
+  defineRpcContract,
   explainObject,
   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/dist/rpc.d.ts

@@ -0,0 +1,34 @@
+export type RpcDecoder<T> = (value: unknown) => T;
+export interface RpcContract<Args extends Record<string, unknown>, Result> {
+    args: RpcDecoder<Args>;
+    result: RpcDecoder<Result>;
+}
+export type RpcArgs<Contract> = Contract extends RpcContract<infer Args, unknown> ? Args : never;
+export type RpcResult<Contract> = Contract extends RpcContract<Record<string, unknown>, infer Result> ? Result : never;
+export interface RpcTransport {
+    rpc(name: string, args: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: unknown;
+    }>;
+}
+export type RpcCallResult<T> = {
+    ok: true;
+    data: T;
+    error: null;
+} | {
+    ok: false;
+    data: null;
+    error: unknown;
+};
+export declare class RpcContractError extends Error {
+    readonly rpcName: string;
+    readonly phase: 'registration' | 'args' | 'result';
+    readonly code = "RPC_CONTRACT_INVALID";
+    constructor(rpcName: string, phase: 'registration' | 'args' | 'result');
+}
+export declare function defineRpcContract<Args extends Record<string, unknown>, Result>(contract: RpcContract<Args, Result>): Readonly<RpcContract<Args, Result>>;
+type Contracts = Record<string, RpcContract<Record<string, unknown>, unknown>>;
+export declare function createRpcClient<const Registry extends Contracts>(transport: RpcTransport, contracts: Registry): {
+    call<Name extends Extract<keyof Registry, string>>(name: Name, args: RpcArgs<Registry[NoInfer<Name>]>): Promise<RpcCallResult<RpcResult<Registry[Name]>>>;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/db",
-  "version": "0.3.1",
+  "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",