@byok-sdk/cloud 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ancienttwo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @byok-sdk/cloud
+
+Stateless hosted BYOK HTTP handlers and an in-memory reference composition over
+tenant-first `@byok-sdk/core` ports. It owns device-facing protocol/auth/policy
+logic but no durable database or object-storage driver.
+
+Pair it with `@byok-sdk/cloud-postgres` for Postgres + R2 production storage.
+
+MIT licensed. Node.js 20 or newer.

package/dist/auth/bearer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The single bearer check every device-facing route shares.
+ *
+ * S1 shape, reproduced exactly: the token's `(tenantId, deviceId, productId)`
+ * are LOOKUP KEYS, and the ROW that comes back is the authority. A token for a
+ * device that no longer exists, one whose tenant does not own that device, one
+ * whose product disagrees with the row, one for a revoked device, an expired
+ * token, and a malformed tenant id in the claims all fail identically here and
+ * are indistinguishable to the caller. There is deliberately no "which of
+ * those was it" signal to hand back, so no route can turn a 401 into a
+ * cross-tenant existence oracle.
+ *
+ * The returned {@link DevicePrincipal} is core's, carrying a minted
+ * `TenantId` — which is what makes it the only legal input to
+ * `tenantStoresFor` (`../tenant-stores.ts`).
+ */
+import { type DevicePrincipal } from '@byok-sdk/core';
+import type { DeviceDirectory } from '../stores/ports';
+import type { TokenSigner } from './tokens';
+export interface BearerAuthDeps {
+    readonly tokenSigner: TokenSigner;
+    readonly devices: DeviceDirectory;
+}
+export declare function extractBearerToken(header: string | undefined): string | undefined;
+export declare function authenticateBearer(header: string | undefined, deps: BearerAuthDeps): Promise<DevicePrincipal | undefined>;

package/dist/auth/device-proof.d.ts

@@ -0,0 +1,38 @@
+import { type Clock, type DevicePrincipal } from '@byok-sdk/core';
+import type { CloudCrypto } from '../crypto/port';
+import type { DeviceDirectory } from '../stores/ports';
+export declare const DEFAULT_DEVICE_PROOF_CLOCK_SKEW_MS = 60000;
+export declare const MAX_DEVICE_PROOF_CLOCK_SKEW_MS: number;
+export declare const DEFAULT_DEVICE_PROOF_MAX_LIFETIME_MS: number;
+export declare const MAX_DEVICE_PROOF_MAX_LIFETIME_MS: number;
+export interface DeviceProofRequestBinding {
+    readonly method: string;
+    readonly path: string;
+    readonly operation: string;
+    readonly resource: string;
+    readonly body: Uint8Array;
+}
+export interface DeviceProofAuthDeps {
+    readonly devices: DeviceDirectory;
+    readonly crypto: CloudCrypto;
+    readonly clock: Clock;
+    readonly clockSkewMs?: number;
+    readonly maxLifetimeMs?: number;
+}
+export interface AuthenticatedDeviceProof {
+    /** Row-derived principal; no protected claim is re-used as authority. */
+    readonly device: DevicePrincipal;
+    readonly requestId: string;
+    readonly operation: string;
+    readonly resource: string;
+    readonly bodySha256: string;
+    readonly bodySize: bigint;
+    readonly keyId: string;
+    readonly keyEpoch: number;
+}
+/**
+ * Authenticate a request-bound proof. Every rejected state is `undefined`, so
+ * a route has one 401 response for malformed input, row misses, revocation,
+ * stale epochs, binding changes, clock failures and bad signatures.
+ */
+export declare function authenticateDeviceProof(input: unknown, request: DeviceProofRequestBinding, deps: DeviceProofAuthDeps): Promise<AuthenticatedDeviceProof | undefined>;

package/dist/auth/plane.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The auth plane: everything the three pre-tenant routes (`/byok/pair`,
+ * `/byok/challenge`, `/byok/token`) need, and nothing else.
+ *
+ * Those three routes cannot take a {@link TenantStores} facade — they run
+ * BEFORE a principal exists, which is exactly why they are the surface where a
+ * tenant boundary is easiest to lose. So instead of handing them naked stores
+ * and trusting each handler to pass the right tenant, this module owns every
+ * tenant-carrying call they make and hands back operations that name no tenant
+ * at all:
+ *
+ * - a pairing code redeems into a REGISTERED device row in one step, so the
+ *   claims never sit in handler scope as a tenant a handler could substitute;
+ * - a device resolves to a row (the pre-tenant lookup, §6.2's pinned wire
+ *   contract), and unknown/revoked collapse to one answer;
+ * - nonce issue/validate/consume and token minting take that ROW, so the
+ *   tenant they act on is the row's, by construction.
+ */
+import type { Clock, TenantId } from '@byok-sdk/core';
+import type { CloudCrypto } from '../crypto/port';
+import type { CloudStores, DeviceRecord, PairingCodeInfo } from '../stores/ports';
+import { type TokenSigner } from './tokens';
+/** ~10min, matching the reference server's pairing-code lifetime. */
+export declare const PAIRING_CODE_TTL_MS: number;
+/** The paired identity key is the first and only proof key in S6. */
+export declare const DEVICE_IDENTITY_PROOF_KEY_ID = "identity";
+export declare const DEVICE_IDENTITY_PROOF_KEY_EPOCH = 0;
+export interface PairInput {
+    readonly pairingCode: string;
+    readonly deviceName: string;
+    readonly devicePublicKey: string;
+}
+export interface MintedAccessToken {
+    readonly accessToken: string;
+    readonly expiresAt: string;
+}
+export interface AuthPlane {
+    /** Host control plane: mint a single-use code carrying the tenant/product a device will land in. */
+    createPairingCode(tenant: TenantId, input: {
+        readonly productId: string;
+        readonly ttlMs?: number;
+    }): Promise<PairingCodeInfo>;
+    /**
+     * Redeem a code and register the device it pairs, in one step. `undefined`
+     * for a code that is unknown, expired, or already used — one answer for all
+     * three. Single-use redemption is what makes this exclusive: a second
+     * redeem never reaches the row write.
+     */
+    redeemAndRegister(input: PairInput): Promise<DeviceRecord | undefined>;
+    /** The pre-tenant device lookup §6.2's wire contract forces. `undefined` for unknown AND revoked alike — no existence oracle. */
+    resolveDevice(deviceId: string): Promise<DeviceRecord | undefined>;
+    issueNonce(device: DeviceRecord): Promise<string>;
+    validateNonce(device: DeviceRecord, nonce: string): Promise<boolean>;
+    /** Burn the nonce. Called only on a fully verified request (§6.2). */
+    consumeNonce(device: DeviceRecord, nonce: string): Promise<void>;
+    /** Domain-separated (`byok-nonce-v1\n`) — see `verify.ts`. A raw signature over the bare nonce is invalid, with no second accepted form. */
+    verifySignature(device: DeviceRecord, nonce: string, signature: string): Promise<boolean>;
+    mintAccessToken(device: DeviceRecord): Promise<MintedAccessToken>;
+}
+export interface AuthPlaneDeps {
+    readonly stores: CloudStores;
+    readonly crypto: CloudCrypto;
+    readonly clock: Clock;
+    readonly tokenSigner: TokenSigner;
+    readonly accessTokenTtlSeconds?: number;
+}
+export declare function createAuthPlane(deps: AuthPlaneDeps): AuthPlane;

package/dist/auth/tokens.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Access tokens for the hosted device surface (docs/protocol.md §6).
+ *
+ * The token carries the identity TRIPLE — `(deviceId, tenantId, productId)` —
+ * and all three legs are lookup keys, never authority: `authenticateBearer`
+ * (`bearer.ts`) resolves them against the device directory and answers with
+ * the ROW's identity. A token missing a leg is not a partially usable token;
+ * it is not a token this deployment minted.
+ *
+ * {@link TokenSigner} is a port for the same reason `@byok-sdk/server` made it
+ * one: a SaaS with an org-wide asymmetric signer or a KMS swaps its own in.
+ * The reference implementation below is HS256 over a caller-supplied secret,
+ * built on WebCrypto so the package stays runtime-neutral (no `jose`, no
+ * `node:crypto`).
+ */
+import type { Clock } from '@byok-sdk/core';
+/** Access tokens are ~1h, matching the reference server (docs/protocol.md §6.1/§6.2). */
+export declare const ACCESS_TOKEN_TTL_SECONDS: number;
+export interface AccessTokenClaims {
+    readonly deviceId: string;
+    /** Unbranded on the wire: the value is only a lookup key until a device row vouches for it. */
+    readonly tenantId: string;
+    readonly productId: string;
+}
+export interface TokenSigner {
+    sign(claims: AccessTokenClaims, expiresInSeconds: number): Promise<string>;
+    /** Claims for a valid, unexpired token, or `undefined` for invalid/expired/malformed — no reason is ever reported. */
+    verify(token: string): Promise<AccessTokenClaims | undefined>;
+}
+/**
+ * HS256 JWT signer over `secret`.
+ *
+ * `clock` is injected rather than read off `Date.now()` so expiry is testable
+ * and so the whole package keeps a single notion of "now" (the same one the
+ * stores use for TTLs).
+ */
+export declare function createHmacTokenSigner(secret: Uint8Array, clock: Clock): TokenSigner;

package/dist/auth/verify.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The one nonce-signature check on the hosted surface (docs/protocol.md §6.2).
+ *
+ * S1 (GAP-004): a device signs `byok-nonce-v1\n` + nonce, never the bare
+ * nonce. The device key is a long-lived identity key that later planes (S6
+ * device proof) also sign structured messages with; without a domain tag, a
+ * signature produced for one purpose is a valid signature for another.
+ *
+ * Applying the domain HERE rather than at the call site is the point: there
+ * is exactly one place that decides what a device signature over a nonce
+ * means, so no route can be written that accepts the undomained form. There
+ * is deliberately no dual mode and no grace window — a device on the old
+ * encoding re-pairs.
+ *
+ * The literal is byte-identical to `@byok-sdk/server`'s `NONCE_SIGNING_DOMAIN`
+ * and to what the daemon signs (`packages/client/src/daemon/device-keys.ts`),
+ * because the daemon must not be able to tell self-hosted from hosted. Parity
+ * is asserted by behavior tests, never by importing the server.
+ */
+import type { CloudCrypto } from '../crypto/port';
+export declare const NONCE_SIGNING_DOMAIN = "byok-nonce-v1\n";
+export declare function verifyNonceSignature(crypto: CloudCrypto, devicePublicKey: string, nonce: string, signature: string): Promise<boolean>;

package/dist/board-projection.d.ts

@@ -0,0 +1,9 @@
+import type { TenantBoundBoard } from './tenant-stores';
+/**
+ * One-way projection from an already accepted terminal fact into coordination.
+ *
+ * This module deliberately knows no wire message type or execution-state
+ * vocabulary. It can only CAS an existing coordination row one step toward
+ * review, and a concurrent board decision wins without retry or overwrite.
+ */
+export declare function projectTerminalToReview(board: TenantBoundBoard, taskId: string): Promise<void>;

package/dist/capabilities.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The hosted capability declaration (ADR-010).
+ *
+ * A client learns what a deployment supports by READING a declaration, never
+ * by probing an endpoint and interpreting 404/405/501. `@byok-sdk/core` owns the
+ * declaration shape and the `hasCapability`/`assertCapability` enforcement
+ * point; what lives here is the hosted vocabulary and the mapping from a
+ * capability name to the routes that provide it.
+ *
+ * `GET /byok/capabilities` is a hosted-only route: it is not part of the
+ * frozen device wire contract, `@byok-sdk/protocol` is untouched by it, and the
+ * daemon does not consume it yet (that lands in a later slice). What it
+ * already does here is drive route selection — a deployment that does not
+ * declare `blobs.presigned` does not mount the grant routes at all, and one
+ * that does not declare `blobs.contentproxy` does not mount the two `/content`
+ * routes, so the declaration and the surface cannot disagree.
+ */
+import { type CapabilityDeclaration } from '@byok-sdk/core';
+/** The hosted capability vocabulary this package knows how to serve. */
+export declare const CLOUD_CAPABILITIES: {
+    /** `GET /byok/events` long-poll receive (§8). */
+    readonly eventsLongPoll: 'events.longpoll';
+    /** `POST /byok/messages` batched send (§8.2). */
+    readonly messagesBatch: 'messages.batch';
+    /** The three bearer-authed blob routes: reserve/grant, explicit finalize, committed-only download (§7). */
+    readonly blobsPresigned: 'blobs.presigned';
+    /**
+     * The two presigned `/byok/blobs/:id/content` routes — cloud carrying the
+     * bytes itself.
+     *
+     * Split out of `blobs.presigned` because it was one capability describing two
+     * separable facts. A composition whose bytes live in object storage mints
+     * grants (`blobs.presigned`) but has no byte-proxy path at all, and saying so
+     * by declaration is ADR-010's whole posture: a client reads what a deployment
+     * serves, it never probes a `/content` route and interprets the status code.
+     *
+     * Spelled all-lowercase because core's declaration schema pins capability
+     * names to `/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/` — the same reason the sibling
+     * above reads `events.longpoll` and not `events.longPoll`.
+     */
+    readonly blobsContentProxy: 'blobs.contentproxy';
+    /** Board list/claim/unclaim/status routes. Polling is first-class under this declaration. */
+    readonly boardCoordination: 'board.coordination';
+    /** Additional SSE transport for the same board read model. */
+    readonly boardSse: 'board.sse';
+    /** Device-scoped five-level presence publication. */
+    readonly presenceHints: 'presence.hints';
+    /** Bounded task activity batch publication. */
+    readonly activityTail: 'activity.tail';
+    /** Request-bound device proof record manifest/read/write surface (S6). */
+    readonly truthRecords: 'truth.records';
+};
+export type CloudCapability = (typeof CLOUD_CAPABILITIES)[keyof typeof CLOUD_CAPABILITIES];
+/** The wire DTO for `GET /byok/capabilities` — core's shape, bound to a cloud-owned route. */
+export declare const CapabilitiesResponseSchema: import("zod").ZodObject<{
+    schema: import("zod").ZodLiteral<"byok-capabilities-v1">;
+    version: import("zod").ZodNumber;
+    capabilities: import("zod").ZodArray<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+export type CapabilitiesResponse = CapabilityDeclaration;
+export interface FullCapabilityDeclarationOptions {
+    /**
+     * Composition-bound capabilities require an explicit application authority.
+     * `truth.records` is omitted by default because the standard in-memory
+     * composition cannot truthfully promise a cross-store atomic commit.
+     */
+    readonly includeTruthRecords?: boolean;
+}
+/** Every capability the standard composition can serve, plus explicitly wired composition-bound ones. */
+export declare function fullCapabilityDeclaration(version?: number, options?: FullCapabilityDeclarationOptions): CapabilityDeclaration;
+export declare function declares(declaration: CapabilityDeclaration, capability: CloudCapability): boolean;

package/dist/cloud.d.ts

@@ -0,0 +1,123 @@
+/**
+ * `createByokCloud` — the hosted device surface, assembled.
+ *
+ * What this is NOT: an embedded coordinator. There is no `TaskHandle`, no
+ * connection registry, no per-task object that a host holds onto. Sprint 0.1's
+ * non-goal is explicit about that — the embedded `TaskHandle` must not become
+ * the hosted API — so the host's control-plane input is a function
+ * ({@link ByokCloud.enqueueOffer}) and its read model is a store query
+ * ({@link ByokCloud.readTaskAttempt}).
+ *
+ * Every route is stateless in the strict sense: it resolves a principal from
+ * the request, binds stores to that principal's tenant, and returns. Nothing
+ * survives the response but what a store wrote. The one shape that would
+ * quietly undo that — a Running/session map — is asserted absent by
+ * `src/__tests__/constraints.test.ts`.
+ */
+import { type ActivityTail, type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type CapabilityDeclaration, type Clock, type CoreStores, type PresenceHint, type TenantId } from '@byok-sdk/core';
+import { type Envelope, type TaskOfferPayload } from '@byok-sdk/protocol';
+import type { TokenSigner } from './auth/tokens';
+import type { CloudCrypto } from './crypto/port';
+import { type RouteDescriptor } from './router/registry';
+import type { BlobContentProxy, CloudStores, DeviceRecord, PairingCodeInfo, RequestReceipt, TaskAttempt } from './stores/ports';
+import type { TruthCommitter, TruthObjectDownloads } from './truth/contract';
+/** Matches the reference server's ceiling (§7). */
+export declare const DEFAULT_MAX_BLOB_SIZE_BYTES: number;
+/** Matches the reference server's hold (§8). */
+export declare const DEFAULT_LONG_POLL_HOLD_MS = 50000;
+/** How often a held poll re-reads the mailbox. */
+export declare const DEFAULT_LONG_POLL_INTERVAL_MS = 250;
+/** Rows per `GET /byok/events` response. */
+export declare const DEFAULT_EVENTS_PAGE_LIMIT = 50;
+export interface ByokCloudOptions {
+    readonly core: CoreStores;
+    readonly cloud: CloudStores;
+    /**
+     * Byte proxying for the two `/byok/blobs/:id/content` routes. OPTIONAL, and
+     * absent is a first-class answer: a composition backed by object storage
+     * hands the device a presigned URL to the object store and never carries a
+     * byte, so it has nothing to supply here. Supplying it is necessary but not
+     * sufficient for the routes to exist — the deployment must also declare
+     * `blobs.contentproxy` (ADR-010).
+     */
+    readonly blobContentProxy?: BlobContentProxy;
+    /** Atomic proof receipt + truth/reference/accounting authority for S6 routes. */
+    readonly truthCommitter?: TruthCommitter;
+    /** Content-hash keyed object GET grants for object-backed truth bodies. */
+    readonly truthObjectDownloads?: TruthObjectDownloads;
+    readonly crypto: CloudCrypto;
+    readonly tokenSigner: TokenSigner;
+    readonly clock: Clock;
+    /** What this deployment serves (ADR-010). Routes are mounted from it, so it can never over-declare. */
+    readonly capabilities: CapabilityDeclaration;
+    /** Recorded on the control-plane principal every host-side call is made under. */
+    readonly operatorId?: string;
+    readonly maxBlobSizeBytes?: number;
+    readonly longPollHoldMs?: number;
+    readonly longPollIntervalMs?: number;
+    readonly eventsPageLimit?: number;
+    readonly accessTokenTtlSeconds?: number;
+    readonly boardPageLimit?: number;
+    readonly boardStreamQueryIntervalMs?: number;
+    readonly boardStreamHeartbeatIntervalMs?: number;
+    readonly boardStreamReconciliationIntervalMs?: number;
+    readonly boardChannelMaxBytes?: number;
+    readonly boardTitleMaxBytes?: number;
+    readonly presenceTtlMs?: number;
+    readonly presenceMinimumIntervalMs?: number;
+    readonly presenceDetailMaxBytes?: number;
+    readonly activityMaxEvents?: number;
+    readonly activityMaxBytes?: number;
+    readonly activityCapacity?: number;
+    readonly activityTtlMs?: number;
+    readonly maxTruthRequestBytes?: number;
+}
+export interface EnqueueOfferInput {
+    /** Supply one to make the enqueue addressable by the host's own id; otherwise cloud mints one. */
+    readonly taskId?: string;
+    readonly payload: TaskOfferPayload;
+}
+export interface EnqueuedOffer {
+    readonly taskId: string;
+    /** The per-(tenant, device) delivery seq — the daemon's redelivery cursor position for this envelope. */
+    readonly seq: number;
+    readonly envelope: Envelope;
+    readonly attempt: TaskAttempt;
+}
+export interface ByokCloud {
+    /** WHATWG fetch handler — mount on `@hono/node-server`, a Worker, or Deno. */
+    readonly fetch: (request: Request, ...rest: unknown[]) => Response | Promise<Response>;
+    /** The I1 route inventory: every mounted route and the credential class it requires. */
+    readonly routes: readonly RouteDescriptor[];
+    /**
+     * What the router ACTUALLY holds, read back off the router itself. Exposed
+     * so the I1 matrix can close in both directions: an inventory is only
+     * evidence if a route mounted some other way would show up here without a
+     * matching entry in {@link routes}.
+     */
+    readonly mountedRoutes: readonly {
+        readonly method: string;
+        readonly path: string;
+    }[];
+    readonly capabilities: CapabilityDeclaration;
+    /** Host control plane: mint a single-use pairing code for a tenant/product. */
+    createPairingCode(tenant: TenantId, input: {
+        readonly productId: string;
+        readonly ttlMs?: number;
+    }): Promise<PairingCodeInfo>;
+    /** Host control plane: hand a device a frozen-v1 `task.offer`. The hosted replacement for `dispatch()` — a function, not a handle. */
+    enqueueOffer(tenant: TenantId, deviceId: string, input: EnqueueOfferInput): Promise<EnqueuedOffer>;
+    readTaskAttempt(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
+    /** The recorded terminal for a task — the first one, re-encoded canonically under the frozen v1 codec (see `recordTerminal`, `inbound.ts`: the stored body is `encodeEnvelope` of the zod-parsed envelope, not the device's original byte sequence). */
+    readTerminalReceipt(tenant: TenantId, taskId: string): Promise<RequestReceipt | undefined>;
+    listDevices(tenant: TenantId): Promise<readonly DeviceRecord[]>;
+    revokeDevice(tenant: TenantId, deviceId: string): Promise<void>;
+    /** Host control plane: create a board row from explicit producer labels. */
+    createBoardItem(tenant: TenantId, input: BoardItemInput): Promise<BoardItem>;
+    listBoardItems(tenant: TenantId, query: BoardListQuery): Promise<BoardPage>;
+    /** Human review authority. Device routes cannot produce `done`. */
+    acceptBoardItem(tenant: TenantId, itemId: string): Promise<BoardItem>;
+    listPresence(tenant: TenantId): Promise<readonly PresenceHint[]>;
+    readActivity(tenant: TenantId, taskId: string): Promise<ActivityTail | undefined>;
+}
+export declare function createByokCloud(options: ByokCloudOptions): ByokCloud;

package/dist/composition/in-memory.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The in-memory composition: core's reference stores plus cloud's, wired into
+ * a working {@link ByokCloud}.
+ *
+ * This is what the handler suites and the client-side end-to-end test run
+ * against, and it is the honest demonstration of the S3 claim — the daemon
+ * cannot tell this from `@byok-sdk/server`, and nothing in the path needs a
+ * database to prove it.
+ */
+import { type Clock, type CapabilityDeclaration, type CoreStores } from '@byok-sdk/core';
+import { type TokenSigner } from '../auth/tokens';
+import type { CloudCrypto } from '../crypto/port';
+import { type ByokCloud } from '../cloud';
+import type { BlobContentProxy, CloudStores } from '../stores/ports';
+import type { TruthCommitter, TruthObjectDownloads } from '../truth/contract';
+export interface InMemoryByokCloudOptions {
+    readonly clock?: Clock;
+    readonly crypto?: CloudCrypto;
+    readonly tokenSigner?: TokenSigner;
+    readonly capabilities?: CapabilityDeclaration;
+    readonly operatorId?: string;
+    readonly maxBlobSizeBytes?: number;
+    readonly longPollHoldMs?: number;
+    readonly longPollIntervalMs?: number;
+    readonly eventsPageLimit?: number;
+    readonly accessTokenTtlSeconds?: number;
+    readonly boardPageLimit?: number;
+    readonly boardStreamQueryIntervalMs?: number;
+    readonly boardStreamHeartbeatIntervalMs?: number;
+    readonly boardStreamReconciliationIntervalMs?: number;
+    readonly boardChannelMaxBytes?: number;
+    readonly boardTitleMaxBytes?: number;
+    readonly presenceTtlMs?: number;
+    readonly presenceMinimumIntervalMs?: number;
+    readonly presenceDetailMaxBytes?: number;
+    readonly activityMaxEvents?: number;
+    readonly activityMaxBytes?: number;
+    readonly activityCapacity?: number;
+    readonly activityTtlMs?: number;
+    /** Test/host supplied atomic truth authority; never synthesized from sequential stores. */
+    readonly truthCommitter?: TruthCommitter;
+    readonly truthObjectDownloads?: TruthObjectDownloads;
+    readonly maxTruthRequestBytes?: number;
+}
+export interface InMemoryByokCloud {
+    readonly cloud: ByokCloud;
+    /** The naked stores, for a host that wants to inspect or seed state directly. */
+    readonly core: CoreStores;
+    readonly stores: CloudStores;
+    /** The byte proxy the two `/content` routes were mounted on. */
+    readonly blobContentProxy: BlobContentProxy;
+    readonly clock: Clock;
+    readonly crypto: CloudCrypto;
+}
+export declare function createInMemoryByokCloud(options?: InMemoryByokCloudOptions): InMemoryByokCloud;

package/dist/coordination-client.d.ts

@@ -0,0 +1,87 @@
+import { type CapabilityDeclaration } from '@byok-sdk/core';
+import { z } from 'zod';
+declare const BoardFeedItemSchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    itemId: z.ZodString;
+    channel: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        closed: "closed";
+        done: "done";
+        in_progress: "in_progress";
+        in_review: "in_review";
+        todo: "todo";
+    }>;
+    assignee: z.ZodOptional<z.ZodObject<{
+        holderId: z.ZodString;
+        heldSince: z.ZodString;
+    }, z.core.$strip>>;
+    boardSeq: z.ZodNumber;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+declare const BoardFeedPageSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        tenantId: z.ZodString;
+        itemId: z.ZodString;
+        channel: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            closed: "closed";
+            done: "done";
+            in_progress: "in_progress";
+            in_review: "in_review";
+            todo: "todo";
+        }>;
+        assignee: z.ZodOptional<z.ZodObject<{
+            holderId: z.ZodString;
+            heldSince: z.ZodString;
+        }, z.core.$strip>>;
+        boardSeq: z.ZodNumber;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+    nextSeq: z.ZodNumber;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;
+export type BoardFeedItem = z.infer<typeof BoardFeedItemSchema>;
+export type BoardFeedPage = z.infer<typeof BoardFeedPageSchema>;
+export type BoardFeedMode = 'sse' | 'poll';
+export type BoardFeedRead = {
+    readonly type: 'board';
+    readonly item: BoardFeedItem;
+} | {
+    readonly type: 'reconcile';
+} | {
+    readonly type: 'poll';
+    readonly page: BoardFeedPage;
+};
+export declare class BoardFeedRetryableError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class BoardFeedStoppedError extends Error {
+    constructor(message: string);
+}
+export interface BoardFeedClientOptions {
+    readonly baseUrl: string | URL;
+    readonly accessToken: string;
+    readonly capabilities: CapabilityDeclaration;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly idleWatchdogMs?: number;
+}
+/**
+ * One board feed consumer with a declaration-fixed transport.
+ *
+ * The mode is selected once from ADR-010 data. A temporary SSE 5xx or idle
+ * watchdog expiry raises {@link BoardFeedRetryableError}; it never mutates the
+ * mode to polling. A caller retries the same instance and therefore the same
+ * declared transport. Polling exists only when `board.sse` was absent from the
+ * declaration in the first place.
+ */
+export declare class BoardFeedClient {
+    #private;
+    readonly mode: BoardFeedMode;
+    constructor(options: BoardFeedClientOptions);
+    readOnce(afterSeq: number, signal?: AbortSignal): Promise<BoardFeedRead>;
+}
+export {};

package/dist/coordination.d.ts

@@ -0,0 +1,29 @@
+import type { ActivityTail } from '@byok-sdk/core';
+import type { AgentEventOrUnknown } from '@byok-sdk/protocol';
+import type { TenantBoundActivity } from './tenant-stores';
+export declare const DEFAULT_BOARD_CHANNEL_MAX_BYTES = 128;
+export declare const DEFAULT_BOARD_TITLE_MAX_BYTES = 512;
+export declare const DEFAULT_ACTIVITY_MAX_EVENTS = 50;
+export declare const DEFAULT_ACTIVITY_MAX_BYTES: number;
+export declare const DEFAULT_ACTIVITY_CAPACITY = 50;
+export declare const DEFAULT_ACTIVITY_TTL_MS: number;
+export declare const DEFAULT_PRESENCE_TTL_MS = 90000;
+export declare const DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS = 5000;
+export declare const DEFAULT_PRESENCE_DETAIL_MAX_BYTES = 512;
+export interface ActivityBounds {
+    readonly maxEvents: number;
+    readonly maxBytes: number;
+    readonly capacity: number;
+    readonly ttlMs: number;
+}
+export declare const DEFAULT_ACTIVITY_BOUNDS: ActivityBounds;
+export declare function assertBoardLabels(channel: string, title: string, limits: {
+    readonly channelMaxBytes: number;
+    readonly titleMaxBytes: number;
+}): void;
+export declare function activityDetails(events: readonly AgentEventOrUnknown[], dropped: number, bounds: ActivityBounds): readonly string[];
+export declare function appendActivityEvents(activity: TenantBoundActivity, input: {
+    readonly taskId: string;
+    readonly events: readonly AgentEventOrUnknown[];
+    readonly dropped: number;
+}, bounds: ActivityBounds): Promise<ActivityTail>;

package/dist/crypto/port.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The crypto seam.
+ *
+ * `@byok-sdk/server` reaches straight for `node:crypto`. Cloud cannot: a hosted
+ * composition has to load on Workers and Deno too, and `src/__tests__/
+ * constraints.test.ts` asserts this package never imports a `node:` module.
+ * So every primitive the device surface needs — random identifiers, Ed25519
+ * verification of a challenge signature, HMAC for presigned blob URLs,
+ * SHA-256 for content addressing — arrives through this port.
+ *
+ * `web-crypto.ts` in this directory is the reference implementation, built on
+ * the WebCrypto API that Node >=20, Workers, and Deno all expose as
+ * `globalThis.crypto`. A composition backed by a KMS or an HSM supplies its
+ * own instead.
+ */
+export interface CloudCrypto {
+    /** A fresh UUID v4 — envelope ids, device ids, blob ids, task ids. */
+    randomUuid(): string;
+    /** `byteLength` random bytes, base64url-encoded — nonces and opaque tokens. */
+    randomToken(byteLength: number): string;
+    /** A short, human-typeable pairing code (uppercase, unambiguous alphabet). */
+    randomPairingCode(length: number): string;
+    /**
+     * Verify `signature` (base64url) over `message` against
+     * `publicKeyBase64Url` — a raw 32-byte Ed25519 public key in the same
+     * base64url encoding a JWK's `x` field uses, which is what a device
+     * registers at pairing time. String input is encoded as UTF-8; byte input is
+     * used verbatim so core's frozen device-proof signing bytes are not decoded
+     * and re-encoded by the adapter.
+     *
+     * Never throws: a malformed key or signature is a failed verification, not
+     * an exception a route has to translate.
+     */
+    verifyEd25519(publicKeyBase64Url: string, message: string | Uint8Array, signature: string): Promise<boolean>;
+    /** HMAC-SHA-256 over `message`, base64url-encoded. Used for presigned blob URLs. */
+    hmacSha256(secret: Uint8Array, message: string): Promise<string>;
+    /** SHA-256 of `data`, in core's canonical `sha256:<64 lowercase hex>` form. */
+    sha256(data: Uint8Array): Promise<string>;
+    /**
+     * Length-independent equality for two base64url strings. Signature
+     * comparison must not leak a prefix through timing.
+     */
+    timingSafeEqual(left: string, right: string): boolean;
+}