@byok-sdk/cloud-dataplane 0.4.0

package/dist/migrate.d.ts

@@ -0,0 +1,54 @@
+import type { Pool } from 'pg';
+/** One file on disk, already ordered and checksummed. */
+export interface MigrationFile {
+    /** The filename, e.g. `0001_cloud_local.sql`. This is the ledger's `version`. */
+    readonly version: string;
+    /** The four-digit prefix as a number, used for ordering only. */
+    readonly ordinal: number;
+    readonly checksum: string;
+    readonly sql: string;
+}
+/** What a run did. `applied` is empty when the database was already up to date. */
+export interface MigrationResult {
+    readonly applied: readonly string[];
+    readonly alreadyApplied: readonly string[];
+}
+/**
+ * A published migration file changed after it was applied.
+ *
+ * Fail-closed by design: the runner cannot know whether the edit was a harmless
+ * comment or a dropped column, and a deployment that guesses wrong corrupts a
+ * schema. The fix is a NEW migration file, never an edit to an old one.
+ */
+export declare class MigrationChecksumMismatchError extends Error {
+    readonly version: string;
+    readonly expectedChecksum: string;
+    readonly actualChecksum: string;
+    constructor(version: string, expectedChecksum: string, actualChecksum: string);
+}
+/** A file in the migration directory that the naming contract does not admit. */
+export declare class MigrationFilenameError extends Error {
+    readonly filename: string;
+    constructor(filename: string, reason: string);
+}
+/**
+ * Reads and orders the migration files in `directory`.
+ *
+ * Ordering is by the four-digit prefix, not by whatever order the filesystem
+ * hands back — `readdir` makes no promise, and on some filesystems it is
+ * effectively insertion order. A non-conforming filename or a duplicated prefix
+ * is an error rather than a skip: silently ignoring a `.sql` file someone
+ * dropped in this directory is how a migration goes missing.
+ */
+export declare function readMigrationFiles(directory: string): Promise<readonly MigrationFile[]>;
+/**
+ * Applies every pending migration in `directory`, in prefix order.
+ *
+ * @param pool The pool to migrate. One client is checked out for the whole run
+ *   because the advisory lock is session-scoped.
+ * @param directory Absolute path to the migration directory (this repo's
+ *   `deploy/sql/`). Required rather than defaulted: a published package cannot
+ *   guess where its consumer keeps deployment assets, and guessing wrong would
+ *   mean silently migrating nothing.
+ */
+export declare function migrate(pool: Pool, directory: string): Promise<MigrationResult>;

package/dist/migrations-dir.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Absolute path to the migration directory shipped inside this package, ready
+ * to hand to {@link migrate}. The directory exists in an installed package and
+ * in this repository after a build; it does not exist in an unbuilt checkout,
+ * where `deploy/sql/` is the thing to read.
+ */
+export declare function migrationsDir(): string;

package/dist/pool.d.ts

@@ -0,0 +1,39 @@
+import type { Pool, PoolClient, PoolConfig } from 'pg';
+export interface ByokPoolOptions extends Omit<PoolConfig, 'types'> {
+    /** `postgres://user:password@host:port/database`. */
+    readonly connectionString: string;
+    /**
+     * Where an IDLE client's error goes. See {@link createByokPool} — a pool
+     * MUST carry an `'error'` listener or an idle-backend reset crashes the host.
+     * This is where the host takes over that policy (log to its own sink, page,
+     * increment a metric). It is NOT a `PoolConfig` field, so it is stripped
+     * before the config reaches `pg.Pool`, exactly as `types` is kept off the
+     * process-wide registry.
+     *
+     * Left unset, the pool still gets a listener — an observable default, not a
+     * silent swallow.
+     */
+    readonly onPoolError?: (err: Error, client?: PoolClient) => void;
+}
+/**
+ * Creates a pool wired with the int8 parser above.
+ *
+ * The caller owns the pool's lifetime: this package never holds a module-level
+ * pool, because a process that composes two deployments (a migration runner and
+ * a serving path, say) has to be able to close one without breaking the other.
+ *
+ * The `'error'` listener is MANDATORY, not defensive. A `pg.Pool` emits
+ * `'error'` when a client that is sitting IDLE in the pool has its backend
+ * connection reset from under it — a failover, an operator
+ * `pg_terminate_backend`, an idle-timeout on a proxy, a network blip. There is
+ * no `await` in flight to reject at that moment, so `pg` surfaces it on the
+ * pool, and Node's rule for an `EventEmitter` `'error'` with no listener is to
+ * rethrow it as an uncaught exception — which terminates the whole host
+ * process. A bare `new pg.Pool(...)` therefore hands the host a latent crash on
+ * an event it cannot see coming and did not cause. The listener converts that
+ * into a handled, observable event: routed to the host's {@link
+ * ByokPoolOptions.onPoolError} when supplied, or to a labelled `console.error`
+ * so the reset is never invisible. It does not paper over live query errors —
+ * those still reject their own `await`; this is only the idle-client path.
+ */
+export declare function createByokPool(options: ByokPoolOptions): Pool;

package/dist/sql/0001_cloud_local.sql

@@ -0,0 +1,184 @@
+-- 0001_cloud_local.sql — the seven cloud-local port tables.
+--
+-- Frozen at merge. Migrations are forward-only (sprint S4A.6): a correction is
+-- a NEW file, never an edit to this one, and the runner enforces that by
+-- checksumming every applied file against its ledger row
+-- (packages/cloud-postgres/src/migrate.ts).
+--
+-- Key design follows docs/researches/s4a-dataplane-design.md §5 and the
+-- tenant-first discipline in docs/architecture/sdk-architecture.md §12.6.2.
+-- The rule this file is written to obey:
+--
+--   EVERY unique index or constraint on a tenant-owned table starts with
+--   tenant_id.
+--
+-- A naked unique key is what turns "look up by id, then check the tenant" into
+-- a reachable code path; when the first column is tenant_id, a cross-tenant
+-- read addresses a different key space and finds nothing rather than finding a
+-- row it then has to be trusted to reject. Two exceptions are whitelisted
+-- below, each justified at its table, and both of them are single-step
+-- pre-tenant resolutions of a CLOUD-MINTED credential — never a two-step
+-- compare. S4A-b lifts that rule into an executable catalog assertion in
+-- tests/sql/control_plane_invariants.sql with the same two-entry whitelist.
+--
+-- Timestamps are timestamptz. Every instant written here comes from the
+-- composition's injected clock rather than the database's now(), so TTL
+-- behavior is assertable under a test clock instead of requiring the suite to
+-- sleep. The migration ledger's own applied_at is the one exception, and it is
+-- not port state.
+
+-- ---------------------------------------------------------------------------
+-- devices (cloud.devices) — the device directory
+-- ---------------------------------------------------------------------------
+--
+-- UNIQUE (device_id) is the first whitelisted exception. deviceId is minted by
+-- the cloud (`packages/cloud/src/auth/plane.ts` mints `dev_<uuid>`) and is
+-- never a wire field a device can choose, so global uniqueness is
+-- constructive rather than assumed. It backs `resolveByDeviceId`, one of the
+-- three pre-tenant methods `stores/ports.ts` documents: POST /byok/challenge
+-- and POST /byok/token carry only a deviceId, and the row this returns CARRIES
+-- its tenant, so every step after it is tenant-first.
+--
+-- If a future protocol ever let a device choose its own id, this constraint
+-- becomes a cross-tenant denial of service (one tenant claiming another's id)
+-- and would have to go. It is safe only because of the minting rule above.
+CREATE TABLE device (
+  tenant_id         text    NOT NULL,
+  device_id         text    NOT NULL,
+  product_id        text    NOT NULL,
+  device_name       text    NOT NULL,
+  device_public_key text    NOT NULL,
+  revoked           boolean NOT NULL DEFAULT false,
+  PRIMARY KEY (tenant_id, device_id),
+  CONSTRAINT device_device_id_key UNIQUE (device_id)
+);
+
+-- ---------------------------------------------------------------------------
+-- pairing_code (cloud.pairingCodes) — single-use tenant-bearing credentials
+-- ---------------------------------------------------------------------------
+--
+-- PRIMARY KEY (code) is the second whitelisted exception, and here the naked
+-- key is the point: the code IS the tenant lookup. It was minted out-of-band by
+-- the host's control plane, which is the only party that knows which tenant a
+-- human is acting for, and `PairRequest` has no tenant field at all — so a
+-- device can never name the tenant it lands in. The row carries tenant_id, so
+-- redemption resolves the tenant in one step.
+--
+-- redeemed_at doubles as the consumption guard: redemption is a single
+-- `UPDATE ... WHERE redeemed_at IS NULL` whose zero-row result is the typed
+-- rejection. A read-then-write would let two concurrent redemptions both
+-- observe an unused code, and single-use is exactly what makes the caller's
+-- "redeem, then register the device" sequence exclusive.
+CREATE TABLE pairing_code (
+  code        text        PRIMARY KEY,
+  tenant_id   text        NOT NULL,
+  product_id  text        NOT NULL,
+  expires_at  timestamptz NOT NULL,
+  redeemed_at timestamptz
+);
+
+-- ---------------------------------------------------------------------------
+-- auth_nonce (cloud.nonces) — single-use challenge nonces
+-- ---------------------------------------------------------------------------
+--
+-- No index on nonce alone: a nonce is only ever validated for the (tenant,
+-- device) it was issued to, so a global lookup would be a capability nothing
+-- needs and a leaked nonce could otherwise be probed against. `markUsed`
+-- addresses (tenant_id, nonce), which the primary key's leading column already
+-- serves.
+CREATE TABLE auth_nonce (
+  tenant_id  text        NOT NULL,
+  device_id  text        NOT NULL,
+  nonce      text        NOT NULL,
+  expires_at timestamptz NOT NULL,
+  used       boolean     NOT NULL DEFAULT false,
+  PRIMARY KEY (tenant_id, device_id, nonce)
+);
+
+-- ---------------------------------------------------------------------------
+-- inbound_dedup (cloud.dedup) — bounded at-most-once processing
+-- ---------------------------------------------------------------------------
+--
+-- The wire is at-least-once (docs/protocol.md §9), so this table makes
+-- processing at-most-once. recorded_seq exists to make the retention bound
+-- expressible: reclaim deletes everything older than the newest N rows for a
+-- device, oldest first, so the ids most likely to be redelivered are the ones
+-- still remembered. Without an insertion order there is no defensible answer to
+-- "which row do I drop", and an unbounded set lets one chatty device grow the
+-- table without limit.
+CREATE TABLE inbound_dedup (
+  tenant_id    text      NOT NULL,
+  device_id    text      NOT NULL,
+  envelope_id  text      NOT NULL,
+  recorded_seq bigserial NOT NULL,
+  PRIMARY KEY (tenant_id, device_id, envelope_id)
+);
+
+-- Tenant-first, and it is the reclaim's ordering index — not a unique one.
+CREATE INDEX inbound_dedup_reclaim_idx
+  ON inbound_dedup (tenant_id, device_id, recorded_seq);
+
+-- ---------------------------------------------------------------------------
+-- task (cloud.tasks) — the ownership authority the inbound gate reads
+-- ---------------------------------------------------------------------------
+--
+-- owner_device_id is NULL until the first claim, and the claim is a single
+-- `UPDATE ... WHERE owner_device_id IS NULL` so that two devices racing the
+-- same offer produce one owner rather than a last writer. Ownership never
+-- transfers: an owner reassignment is the one operation that would make the
+-- gate's cross-device assertion unfalsifiable.
+--
+-- status carries the values in TASK_ATTEMPT_STATUSES. Deliberately no CHECK
+-- constraint restating that list: the port type is the vocabulary's single
+-- authority, and a copy here could drift from it silently.
+CREATE TABLE task (
+  tenant_id       text        NOT NULL,
+  task_id         text        NOT NULL,
+  device_id       text        NOT NULL,
+  owner_device_id text,
+  status          text        NOT NULL,
+  updated_at      timestamptz NOT NULL,
+  PRIMARY KEY (tenant_id, task_id)
+);
+
+-- ---------------------------------------------------------------------------
+-- device_request_receipts (cloud.receipts) — the terminal idempotency seam
+-- ---------------------------------------------------------------------------
+--
+-- First write wins, expressed as `INSERT ... ON CONFLICT DO NOTHING`. The first
+-- terminal a device reports is the fact (§12.6.4: 不覆写第一份事实), and the
+-- retry that the at-least-once wire guarantees must not restamp it. An upsert
+-- that updated would pass a naive "record twice" check while rewriting history.
+CREATE TABLE device_request_receipts (
+  tenant_id   text        NOT NULL,
+  key         text        NOT NULL,
+  body        text        NOT NULL,
+  recorded_at timestamptz NOT NULL,
+  PRIMARY KEY (tenant_id, key)
+);
+
+-- ---------------------------------------------------------------------------
+-- device_stream (cloud.sequence, and S4A-b's mailbox cursor)
+-- ---------------------------------------------------------------------------
+--
+-- next_seq is the delivery number allocator: `cloud.sequence.next` bumps it in
+-- one statement and returns the pre-bump value, so concurrent allocations
+-- cannot hand out the same number twice. The daemon's redelivery cursor IS this
+-- number, and two envelopes sharing one make the cursor ambiguous.
+--
+-- acked_seq belongs to core.mailbox, which S4A-b implements. It is created HERE
+-- anyway, on purpose: this file is frozen at merge, and a later slice adding a
+-- column would have to either ALTER a frozen file or open 0002 to widen a table
+-- 0001 already owns. Creating the row's full shape once costs one unused column
+-- for one slice and avoids both.
+--
+-- next_seq/acked_seq are bigint, not int: a per-device delivery counter that
+-- wraps is a redelivery bug, and the pool decodes int8 to a JS bigint (see
+-- packages/cloud-postgres/src/pool.ts) rather than to a string.
+CREATE TABLE device_stream (
+  tenant_id  text   NOT NULL,
+  device_id  text   NOT NULL,
+  next_seq   bigint NOT NULL DEFAULT 1,
+  acked_seq  bigint NOT NULL DEFAULT 0,
+  PRIMARY KEY (tenant_id, device_id)
+);