@byok-sdk/cloud-dataplane 0.4.0

package/dist/stores/r2-blobs.d.ts

@@ -0,0 +1,249 @@
+/**
+ * The R2/S3 {@link CloudBlobStore} — grants, and only grants (§12.7.4, §12.7.7).
+ *
+ * Zero bytes cross this file either, but for the opposite reason to
+ * `stores/core/objects.ts`: the manifest store holds metadata because bytes are
+ * not its job, and this store holds no bytes because the DEVICE talks to the
+ * object store directly. What it mints is a presigned URL; what the device does
+ * with it is between the device and R2. That is why this composition supplies
+ * no `BlobContentProxy` — there is no byte path here to proxy, and the absence
+ * is the honest declaration (`@byok-sdk/cloud`'s `ports.ts`, design §6).
+ *
+ * Manifest and bytes are one transaction authority split across two systems
+ * with no shared transaction, so the protocol is reserve/verify rather than
+ * write/trust:
+ *
+ * 1. `createUpload` writes the `pending` manifest row FIRST, then signs a PUT.
+ *    Row-before-bytes is what makes an abandoned upload a reclaimable
+ *    tombstone instead of an object nobody has a record of.
+ * 2. The device PUTs straight to the object store. `Content-Length` and
+ *    `Content-Type` are in the signed headers, so a body of the wrong size or
+ *    the wrong type is refused by the object store itself — before a byte is
+ *    stored, and without this process being in the path.
+ * 3. The explicit finalize route calls `observeUpload`, which performs an
+ *    unconditional `HEAD`. Unconditional because §12.7.7 step 4 is about what
+ *    the store OBSERVES versus what the client DECLARED, and signing the length
+ *    proves what one client sent, not what is at the key now. The quota
+ *    authority then commits manifest/reservation/usage in one Postgres
+ *    statement; download never performs that transition.
+ * 4. `committed` is terminal for writes. Step 1 is re-runnable while a row is
+ *    `pending` — that is what makes a retried upload idempotent — and refused
+ *    once it is `committed`, because §12.7.4 lets truth reference a committed
+ *    manifest and the reference means nothing if the bytes can still be
+ *    replaced by a same-shaped body under a freshly signed PUT.
+ *
+ * **No checksum header.** `x-amz-checksum-sha256` was probed rather than
+ * assumed (design §3 marked it `[unverified]`): MinIO honors it in a presigned
+ * PUT and rejects mismatched bytes with `XAmzContentChecksumMismatch`, but R2's
+ * S3 compatibility table lists SHA-256 as `COMPOSITE` only — `FULL_OBJECT`, the
+ * type a single-shot PutObject uses, is ❌, and R2's PutObject feature row names
+ * no `x-amz-checksum-*` header at all. Signing one would mint URLs that work
+ * against the test substrate and fail against production, which is worse than
+ * not signing it. The `HEAD` above was never conditional on it.
+ *
+ * The `blobId` this store mints IS the content hash. That is what makes "no
+ * naked object index" constructive rather than disciplinary: there is no
+ * surrogate id to look up, every read is `(tenant, hash)` against the manifest
+ * primary key, and the object key is derived — once, in {@link #objectUrl} —
+ * from a `ContentHash` that core already validated. A non-hex id cannot reach
+ * key construction because it cannot become a `ContentHash`.
+ */
+import { type Clock, type ContentHash, type ObjectStore, type StorageReservation, type TenantId } from '@byok-sdk/core';
+import type { BlobObservation, CloudBlobStore } from '@byok-sdk/cloud';
+/** 15 minutes, matching the in-memory reference's `BLOB_URL_TTL_MS`. */
+export declare const DEFAULT_PRESIGN_TTL_SECONDS: number;
+/** `X-Amz-Expires` floor. Below a second there is no grant, only a signature. */
+export declare const MIN_PRESIGN_TTL_SECONDS = 1;
+/** `X-Amz-Expires` ceiling: seven days, the longest lifetime R2 will honor. */
+export declare const MAX_PRESIGN_TTL_SECONDS = 604800;
+/** Three total attempts: the first plus two retries. */
+export declare const DEFAULT_MAX_ATTEMPTS = 3;
+/** Doubles per retry. Deterministic — no jitter, so a test can assert the sequence. */
+export declare const DEFAULT_RETRY_DELAY_MS = 100;
+/** The subset of `fetch` this store uses. The seam a fault injector replaces. */
+export type ObjectStoreFetch = (request: Request) => Promise<Response>;
+/**
+ * Raised when the object store answered something this adapter cannot act on —
+ * a 4xx that is not "absent", or a transient failure that outlived its retries.
+ *
+ * A local class rather than a core code: core's taxonomy describes the manifest
+ * contract, and "R2 returned 503 three times" is an adapter fault, not a
+ * statement about the object.
+ */
+export declare class ObjectStoreRequestError extends Error {
+    readonly status: number | undefined;
+    readonly attempts: number;
+    constructor(message: string, attempts: number, status?: number, options?: ErrorOptions);
+}
+/**
+ * What this adapter refuses on its own account, before anything is signed.
+ *
+ * A second local class rather than more core codes, for the same reason
+ * {@link ObjectStoreRequestError} is one: core's taxonomy describes the
+ * manifest contract, and "this deployment's tenant ids cannot be key segments"
+ * or "this deployment configured a lifetime R2 will not honor" are facts about
+ * an S3 adapter's configuration and inputs, not about an object. Core's code
+ * union is closed and deliberately so; widening it from an adapter would put
+ * an adapter's vocabulary on a wire contract every composition shares.
+ *
+ * Code-based branching, matching the idiom of every other error type here.
+ */
+export declare const R2_BLOB_ERROR_CODES: {
+    /**
+     * A tenant id that cannot be one safe path segment. Wire-relevant: it is the
+     * only signal a control plane gets that the id it issued cannot address
+     * object storage, and it is raised BEFORE any key is built.
+     */
+    readonly storage_tenant_key_unsafe: 'storage_tenant_key_unsafe';
+    /** A presign lifetime outside `[MIN_PRESIGN_TTL_SECONDS, MAX_PRESIGN_TTL_SECONDS]`. Construction-time only. */
+    readonly storage_presign_ttl_invalid: 'storage_presign_ttl_invalid';
+    /** ListObjectsV2 accepts 1..1000 keys per page. Maintenance input only. */
+    readonly storage_list_limit_invalid: 'storage_list_limit_invalid';
+    /** Continuation tokens are opaque but non-empty. Maintenance input only. */
+    readonly storage_list_cursor_invalid: 'storage_list_cursor_invalid';
+};
+export type R2BlobErrorCode = (typeof R2_BLOB_ERROR_CODES)[keyof typeof R2_BLOB_ERROR_CODES];
+export declare class R2BlobStoreError extends Error {
+    readonly code: R2BlobErrorCode;
+    constructor(code: R2BlobErrorCode, message: string, options?: ErrorOptions);
+}
+export interface R2BlobStoreOptions {
+    /**
+     * The manifest authority. Same `ObjectStore` the core composition supplies —
+     * one row per (tenant, hash), and this store never opens a second one.
+     */
+    readonly objects: ObjectStore;
+    /**
+     * The clock SigV4's `X-Amz-Date` is read from — WALL time, and deliberately
+     * NOT the composition's logical clock.
+     *
+     * Every other instant in this program comes from an injected clock so TTLs
+     * are assertable without sleeping, and a store reaching for wall time is a
+     * bug. A request signature is the exception, and not a soft one: its validity
+     * window is adjudicated by the object store against the object store's own
+     * clock. Signing with a logical instant produces a credential the remote side
+     * rejects as skewed the moment the two disagree — a 403 at upload time, from
+     * a decision made at composition time.
+     *
+     * Separate and required rather than defaulted, so the distinction is a choice
+     * someone makes rather than one they inherit. A test that needs an EXPIRED
+     * grant backdates this clock, which is also the only way to assert expiry
+     * without sleeping through it.
+     */
+    readonly signingClock: Clock;
+    /** Origin only, e.g. `https://<account>.r2.cloudflarestorage.com`. */
+    readonly endpoint: string;
+    readonly bucket: string;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    /**
+     * `auto` for R2. Required rather than defaulted: a signature scoped to the
+     * wrong region fails as a 403 at upload time, which is a terrible place to
+     * discover a config default nobody chose.
+     */
+    readonly region: string;
+    /**
+     * A key namespace for this deployment, e.g. `acme/prod` →
+     * `acme/prod/tenants/<tenant>/objects/sha256/<hex>`. Omit it and the key is
+     * the unprefixed `tenants/...` layout, byte for byte.
+     *
+     * What it is for: one bucket, several deployments. Without it every
+     * deployment owns the bucket root, so a host running two products against
+     * one R2 account has to open a bucket per product.
+     *
+     * **Immutable per deployment, and only for a NEW one.** This value is
+     * spliced into the key at write time and at read time from the same field;
+     * there is no second layout anything falls back to, by design. Change it on
+     * a deployment that has already stored objects and those objects are
+     * stranded — still in the bucket, no longer addressable, and invisible to
+     * this SDK's own maintenance surface. A dual-read across the old and new
+     * prefix is NOT a supported way to switch and will not be added: it would
+     * make two key layouts simultaneously authoritative for the same object.
+     * Moving an existing deployment onto a prefix is a separate, one-shot,
+     * operator-invoked copy of the objects themselves, out of this SDK's scope.
+     *
+     * Validated at construction ({@link ObjectKeyPrefix}): slash-joined segments
+     * of lowercase alphanumerics, `.`, `_`, `-`, each starting with an
+     * alphanumeric, no leading/trailing slash, no empty segment. `''` is a
+     * refusal, not a synonym for "no prefix" — it is what an unset environment
+     * variable looks like, and silently treating it as the default would put a
+     * deployment's objects somewhere nobody chose.
+     */
+    readonly keyPrefix?: string;
+    readonly presignTtlSeconds?: number;
+    /** Injected so a fault injector can sit in front of the real one. */
+    readonly fetch?: ObjectStoreFetch;
+    readonly maxAttempts?: number;
+    readonly retryDelayMs?: number;
+}
+/** One tenant-prefixed R2 key returned by ListObjectsV2. */
+export interface R2ListedObject {
+    readonly key: string;
+    /** Present only when the key is exactly `<tenant>/sha256/<64 lowercase hex>`. */
+    readonly hash?: ContentHash;
+    readonly byteSize: bigint;
+}
+export interface R2ObjectPage {
+    readonly objects: readonly R2ListedObject[];
+    readonly nextContinuationToken?: string;
+}
+export type R2DeleteResult = 'deleted' | 'absent';
+/** Operations used only by the host-owned S4B-c maintenance worker. */
+export interface R2ObjectMaintenance {
+    inspectObject(tenant: TenantId, hash: ContentHash): Promise<BlobObservation | undefined>;
+    deleteObject(tenant: TenantId, hash: ContentHash): Promise<R2DeleteResult>;
+    listTenantObjects(tenant: TenantId, continuationToken?: string, limit?: number): Promise<R2ObjectPage>;
+}
+export declare class R2CloudBlobStore implements CloudBlobStore {
+    #private;
+    constructor(options: R2BlobStoreOptions);
+    /**
+     * Reserve the manifest row, then hand back a PUT bound to this tenant, this
+     * key, this length, this type, and this expiry.
+     *
+     * `putManifest` is idempotent per (tenant, hash), so a device that declares
+     * the same content twice while it is still `pending` gets the same row and
+     * the same key — an interrupted upload is retried, not duplicated. It is
+     * idempotent per TENANT, which is the same reason the key embeds the tenant:
+     * two tenants holding identical bytes hold two independent objects, and
+     * neither can learn of the other's.
+     *
+     * Idempotence stops at `committed`, and that boundary is the point: a
+     * committed object is what a truth record is allowed to reference, so it has
+     * to be immutable, and re-issuing a write grant for one is the only way this
+     * adapter could make it otherwise.
+     */
+    createUpload(tenant: TenantId, reservation: StorageReservation): Promise<{
+        readonly blobId: string;
+        readonly uploadUrl: string;
+    }>;
+    observeUpload(tenant: TenantId, blobId: string, reservation: StorageReservation): Promise<BlobObservation | undefined>;
+    /**
+     * A GET for a committed object this tenant owns; `undefined` otherwise.
+     *
+     * Every miss answers identically — unknown hash, another tenant's object, a
+     * malformed id, bytes that never landed, a tombstoned row. A caller cannot
+     * tell them apart, which is what keeps `getDownloadUrl` from being an
+     * existence oracle across tenants.
+     *
+     * This is a pure committed-manifest gate. Observation and commit belong to
+     * the explicit finalize route; a download must never decide accounting.
+     */
+    getDownloadUrl(tenant: TenantId, blobId: string): Promise<string | undefined>;
+}
+export type R2ObjectMaintenanceOptions = Omit<R2BlobStoreOptions, 'objects' | 'presignTtlSeconds'>;
+/**
+ * R2 maintenance adapter kept deliberately outside `CloudBlobStore`.
+ *
+ * Cloud conformance certifies the device-facing blob port with an exact method
+ * inventory. LIST/HEAD/DELETE are host operations, so putting them on
+ * `R2CloudBlobStore` would over-declare a capability no other cloud composition
+ * implements.
+ */
+export declare class R2ObjectMaintenanceStore implements R2ObjectMaintenance {
+    #private;
+    constructor(options: R2ObjectMaintenanceOptions);
+    inspectObject(tenant: TenantId, hash: ContentHash): Promise<BlobObservation | undefined>;
+    deleteObject(tenant: TenantId, hash: ContentHash): Promise<R2DeleteResult>;
+    listTenantObjects(tenant: TenantId, continuationToken?: string, limit?: number): Promise<R2ObjectPage>;
+}

package/dist/stores/receipts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Postgres {@link RequestReceiptStore}: the first write is the fact.
+ *
+ * `INSERT ... ON CONFLICT DO NOTHING` and nothing else. The terminal a device
+ * reports is a fact, and the retry the at-least-once wire guarantees must not
+ * overwrite it (§12.6.4: 不覆写第一份事实). `created: false` is how the caller
+ * learns it was a replay, which is why an upsert that UPDATED would be wrong in
+ * a way no naive "record it twice" test would catch — it would pass, while
+ * silently rewriting history and restamping `recorded_at`.
+ */
+import type { RequestReceipt, RequestReceiptStore } from '@byok-sdk/cloud';
+import type { Clock, TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export declare class PostgresRequestReceiptStore implements RequestReceiptStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    record(tenant: TenantId, input: {
+        readonly key: string;
+        readonly body: string;
+    }): Promise<{
+        readonly receipt: RequestReceipt;
+        readonly created: boolean;
+    }>;
+    get(tenant: TenantId, key: string): Promise<RequestReceipt | undefined>;
+}

package/dist/stores/task-attempts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Postgres {@link TaskAttemptStore} — the ownership authority the inbound gate
+ * reads (N2).
+ *
+ * `claim` is a single guarded statement: `UPDATE ... WHERE owner_device_id IS
+ * NULL RETURNING ...`. Two devices racing the same offer therefore produce one
+ * owner, not a last writer. When the guard rejects, the row is re-read and
+ * returned as-is, which makes a losing claim (and the winner's own re-claim)
+ * idempotent rather than an error — the caller learns who owns the task either
+ * way. Ownership never transfers: reassigning an owner is the one operation
+ * that would make the gate's cross-device assertion unfalsifiable.
+ *
+ * Two deliberate no-ops, both about not letting a guessed id leave a trace:
+ * `claim` and `recordStatus` on a task this tenant never offered write nothing
+ * and return `undefined`.
+ */
+import type { TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '@byok-sdk/cloud';
+import type { Clock, TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export declare class PostgresTaskAttemptStore implements TaskAttemptStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    open(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+    }): Promise<TaskAttempt>;
+    get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
+    claim(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+    }): Promise<TaskAttempt | undefined>;
+    recordStatus(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly status: TaskAttemptStatus;
+    }): Promise<TaskAttempt | undefined>;
+}

package/dist/truth-committer.d.ts

@@ -0,0 +1,15 @@
+import { type CloudCrypto, type TruthCommitInput, type TruthCommitResult, type TruthCommitter } from '@byok-sdk/cloud';
+import { type Clock, type TenantId, type TruthRecord } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export interface PostgresTruthCommitterOptions {
+    readonly pool: Pool;
+    readonly clock: Clock;
+    readonly crypto: Pick<CloudCrypto, 'sha256'>;
+}
+export declare class PostgresTruthCommitter implements TruthCommitter {
+    #private;
+    constructor(options: PostgresTruthCommitterOptions);
+    getRecord(tenant: TenantId, selector: Parameters<TruthCommitter['getRecord']>[1]): Promise<TruthRecord | undefined>;
+    listManifest(tenant: TenantId, query: Parameters<TruthCommitter['listManifest']>[1]): Promise<readonly import("@byok-sdk/core").TruthManifestEntry[]>;
+    commit(tenant: TenantId, input: TruthCommitInput): Promise<TruthCommitResult>;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@byok-sdk/cloud-dataplane",
+  "version": "0.4.0",
+  "description": "BYOK SDK hosted data plane: canonical Postgres + R2 stores, migrations, truth transactions, and maintenance",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ancienttwo/byok-sdk.git",
+    "directory": "packages/cloud-dataplane"
+  },
+  "bugs": {
+    "url": "https://github.com/Ancienttwo/byok-sdk/issues"
+  },
+  "homepage": "https://github.com/Ancienttwo/byok-sdk#readme",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "aws4fetch": "1.0.20",
+    "fast-xml-parser": "^5.10.1",
+    "pg": "^8.22.0",
+    "@byok-sdk/cloud": "0.4.0",
+    "@byok-sdk/protocol": "0.4.0",
+    "@byok-sdk/core": "0.4.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.20.4",
+    "undici": "8.9.0",
+    "@byok-sdk/conformance": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json && node scripts/copy-migrations.mjs",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}