@byok-sdk/cloud 0.11.0 → 0.12.0

package/dist/stores/in-memory/blobs.d.ts

@@ -77,6 +77,7 @@ export declare class InMemoryBlobContentProxy implements BlobContentProxy {
     #private;
     constructor(registry: InMemoryBlobRegistry);
     verifySignedUrl(blobId: string, action: 'put' | 'get', sig: string, exp: number): Promise<boolean>;
+    expectedUploadBytes(blobId: string): Promise<bigint | undefined>;
     writeContent(blobId: string, data: Uint8Array): Promise<BlobWriteResult>;
     /**
      * Never returns `{ok:false}`: this composition holds the bytes in the same

package/dist/stores/in-memory/nonces.d.ts

@@ -17,6 +17,5 @@ export declare class InMemoryNonceStore implements NonceStore {
     /** Number of records currently held (post-sweep). Test-facing only. */
     get size(): number;
     issue(tenant: TenantId, deviceId: string): Promise<string>;
-    validate(tenant: TenantId, deviceId: string, nonce: string): Promise<boolean>;
-    markUsed(tenant: TenantId, nonce: string): Promise<void>;
+    consumeIfValid(tenant: TenantId, deviceId: string, nonce: string): Promise<boolean>;
 }

package/dist/stores/in-memory/pairing-codes.d.ts

@@ -2,17 +2,21 @@
  * In-memory {@link PairingCodeStore}: single-use codes bound to the tenant and
  * product they were minted for.
  *
- * `redeem` answers `undefined` for unknown, expired, and already-used alike.
+ * Enrollment answers `undefined` for unknown, expired, and already-used alike.
  * The reference server distinguishes those three in its 401 text; a hosted,
  * multi-tenant surface deliberately does not — the code is a bearer credential
  * addressable across every tenant, and "already used" versus "never existed"
  * is exactly the difference an attacker enumerating codes would pay for.
+ *
+ * Code issuance and enrollment project this one authority into separate ports.
+ * The enrollment path serializes each code through registration and flips
+ * `used` only after its shared device directory has accepted the row.
  */
 import type { Clock, TenantId } from '@byok-sdk/core';
-import type { PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore } from '../ports';
-export declare class InMemoryPairingCodeStore implements PairingCodeStore {
+import type { DeviceDirectory, DeviceRecord, PairingEnrollment, PairingEnrollmentInput, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore } from '../ports';
+export declare class InMemoryPairingCodeStore implements PairingCodeStore, PairingEnrollment {
     #private;
-    constructor(clock: Clock);
+    constructor(clock: Clock, devices: DeviceDirectory);
     issue(tenant: TenantId, input: PairingCodeIssueInput): Promise<PairingCodeInfo>;
-    redeem(code: string): Promise<PairingCodeClaims | undefined>;
+    redeemAndRegister(input: PairingEnrollmentInput): Promise<DeviceRecord | undefined>;
 }

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

@@ -16,7 +16,7 @@
  * unfalsifiable.
  */
 import { type Clock, type TenantId } from '@byok-sdk/core';
-import type { AgentRef, TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '../ports';
+import { type AgentMessageAdmission, type AgentRef, type TaskAttempt, type TaskAttemptStatus, type TaskAttemptStore } from '../ports';
 export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
     #private;
     constructor(clock: Clock, state?: InMemoryTaskAttemptState);
@@ -33,6 +33,25 @@ export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
         readonly attempt: TaskAttempt;
         readonly created: boolean;
     }>;
+    reserveAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<'reserved' | 'pending' | 'rejected'>;
+    readAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
+    finalizeAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+        readonly terminalBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
     get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
     getMany(tenant: TenantId, taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
     claim(tenant: TenantId, input: {
@@ -50,6 +69,7 @@ export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
 export declare class InMemoryTaskAttemptState {
     #private;
     readonly attempts: Map<string, TaskAttempt>;
+    readonly messageAdmissions: Map<string, AgentMessageAdmission>;
     constructor(clock: Clock);
     now(): string;
     /** Serialize every state-changing operation for one tenant/task key. */

package/dist/stores/ports.d.ts

@@ -13,20 +13,18 @@
  * 1. **Async.** Every method returns a `Promise`, so a SQL or KV composition
  *    can implement the same contract the in-memory reference does.
  * 2. **Tenant-first.** Every method's first parameter is a required
- *    `TenantId` — with exactly two documented exceptions below, each of
- *    which is pre-tenant *by construction* because the credential it is
- *    handed is itself what resolves the tenant.
+ *    `TenantId` — with one documented lookup exception below. Pairing code
+ *    consumption is a separate composition-owned enrollment operation: its
+ *    bearer code resolves the tenant internally and it returns only the
+ *    resulting device row.
  *
- * The two exceptions:
+ * The lookup exception:
  *
  * - {@link DeviceDirectory.resolveByDeviceId} — `POST /byok/challenge` and
  *   `POST /byok/token` carry only a deviceId (the pinned wire contract), and
  *   the row is what tells the deployment which tenant to mint for.
- * - {@link PairingCodeStore.redeem} — the code IS the tenant lookup; it was
- *   minted against a tenant that only the host's control plane knew.
- *
- * Neither is reachable through {@link TenantStores} (see `tenant-stores.ts`),
- * so a device-facing handler cannot call them.
+ * It is not reachable through {@link TenantStores} (see `tenant-stores.ts`),
+ * so a device-facing handler cannot call it.
  *
  * The byte-proxy trio that used to be a third pre-tenant exception is no
  * longer part of this bundle at all: it moved to {@link BlobContentProxy},
@@ -151,21 +149,38 @@ export interface PairingCodeIssueInput {
 }
 export interface PairingCodeStore {
     issue(tenant: TenantId, input: PairingCodeIssueInput): Promise<PairingCodeInfo>;
-    /**
-     * Validate and CONSUME a code, returning the claims it was minted with, or
-     * `undefined` when it is unknown, expired, or already used — one answer for
-     * all three, so a redeem attempt is never an existence oracle. Single-use is
-     * what makes the caller's "redeem, then register the device row" sequence
-     * exclusive: a second redeem can never reach the registration step.
-     */
-    redeem(code: string): Promise<PairingCodeClaims | undefined>;
+}
+/**
+ * The pre-tenant facts a pairing request carries into enrollment. Tenant and
+ * product are deliberately absent: the guarded pairing-code row is their sole
+ * authority, and no caller can choose the registration scope.
+ */
+export interface PairingEnrollmentInput {
+    readonly pairingCode: string;
+    readonly deviceId: string;
+    readonly deviceName: string;
+    readonly devicePublicKey: string;
+    readonly proofKeyId: string;
+    readonly proofKeyEpoch: number;
+    readonly machineId?: string;
+}
+/**
+ * The only pairing-code consumption operation. Implementations atomically
+ * consume a valid code, apply machine supersession/state cleanup, and register
+ * the device; failures leave the code retryable. Unknown, expired, and already
+ * consumed codes all return `undefined`.
+ */
+export interface PairingEnrollment {
+    redeemAndRegister(input: PairingEnrollmentInput): Promise<DeviceRecord | undefined>;
 }
 export interface NonceStore {
     issue(tenant: TenantId, deviceId: string): Promise<string>;
-    /** `true` iff the nonce exists for this (tenant, device), is unexpired, and has not been consumed. Never mutates. */
-    validate(tenant: TenantId, deviceId: string, nonce: string): Promise<boolean>;
-    /** Consume the nonce. Called only after every other check on the request has passed. */
-    markUsed(tenant: TenantId, nonce: string): Promise<void>;
+    /**
+     * Atomically consume a nonce only when it belongs to this exact (tenant,
+     * device), is unexpired, and has not already been consumed. Returns `true`
+     * for the sole winner; every other case returns `false`.
+     */
+    consumeIfValid(tenant: TenantId, deviceId: string, nonce: string): Promise<boolean>;
 }
 export interface InboundDedupStore {
     /**
@@ -178,6 +193,12 @@ export interface InboundDedupStore {
 }
 export declare const TASK_ATTEMPT_STATUSES: readonly ['offered', 'claimed', 'running', 'cancel_requested', 'complete', 'failed', 'cancelled'];
 export type TaskAttemptStatus = (typeof TASK_ATTEMPT_STATUSES)[number];
+/** The durable first-message reservation and, once present, its terminal disposition. */
+export interface AgentMessageAdmission {
+    readonly messageId: string;
+    readonly payloadBody: string;
+    readonly terminalBody?: string;
+}
 export interface TaskAttempt {
     readonly tenantId: TenantId;
     readonly taskId: string;
@@ -216,6 +237,33 @@ export interface TaskAttemptStore {
         readonly attempt: TaskAttempt;
         readonly created: boolean;
     }>;
+    /**
+     * Atomically binds one message payload to a live task before an external
+     * consumer can run. `pending` is an existing exact reservation whose terminal
+     * receipt has not been recorded yet; callers must fail closed rather than
+     * invoke the consumer again.
+     */
+    reserveAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<'reserved' | 'pending' | 'rejected'>;
+    /** Read only an exact reservation; conflicting task/message bindings are not observable. */
+    readAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
+    /** CAS the exact reservation to one immutable terminal disposition body. */
+    finalizeAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+        readonly terminalBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
     get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
     /** Batch lookup used by mailbox projection; implementations must not turn one poll into N queries. */
     getMany(tenant: TenantId, taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
@@ -411,6 +459,8 @@ export interface CloudBlobStore {
  */
 export interface BlobContentProxy {
     verifySignedUrl(blobId: string, action: 'put' | 'get', sig: string, exp: number): Promise<boolean>;
+    /** Authoritative declared size for a signed PUT; no byte buffering precedes this lookup. */
+    expectedUploadBytes(blobId: string): Promise<bigint | undefined>;
     writeContent(blobId: string, data: Uint8Array): Promise<BlobWriteResult>;
     /** `undefined` = no such blob (404); a `{ok:false}` result = the blob exists but its bytes could not be proxied (502, distinguished by {@link BlobReadErrorCode}). */
     readContent(blobId: string): Promise<BlobReadResult | undefined>;
@@ -436,6 +486,7 @@ export interface CloudStores {
     readonly approvals: ApprovalTimelineStore;
     readonly devices: DeviceDirectory;
     readonly pairingCodes: PairingCodeStore;
+    readonly pairing: PairingEnrollment;
     readonly nonces: NonceStore;
     readonly dedup: InboundDedupStore;
     readonly tasks: TaskAttemptStore;
@@ -447,5 +498,5 @@ export interface CloudStores {
     readonly rateLimiter: InboundRateLimiter;
 }
 /** Names of every port in {@link CloudStores}, in contract order. */
-export declare const CLOUD_STORE_NAMES: readonly ['activity', 'approvals', 'devices', 'pairingCodes', 'nonces', 'dedup', 'tasks', 'cancellations', 'receipts', 'egress', 'proofReceipts', 'blobs', 'rateLimiter'];
+export declare const CLOUD_STORE_NAMES: readonly ['activity', 'approvals', 'devices', 'pairingCodes', 'pairing', 'nonces', 'dedup', 'tasks', 'cancellations', 'receipts', 'egress', 'proofReceipts', 'blobs', 'rateLimiter'];
 export type CloudStoreName = (typeof CLOUD_STORE_NAMES)[number];

package/dist/tenant-stores.d.ts

@@ -21,7 +21,7 @@
  * presigned blob calls) are deliberately absent from this surface: a
  * device-facing handler must not be able to reach them.
  */
-import { type BoardClaimInput, type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type BoardStatusUpdateInput, type BoardUnclaimInput, type CoreStores, type MailboxAdvanceCursorInput, type MailboxAppendInput, type MailboxCursorState, type MailboxMessage, type MailboxPage, type MailboxReadQuery, type Principal, type PresenceHint, type PresenceHintInput, type TenantReadiness, type StorageFinalizeInput, type StorageFinalizeResult, type StorageReservation, type StorageReservationInput, type TenantId } from '@byok-sdk/core';
+import { type BoardClaimInput, type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type BoardStatusUpdateInput, type BoardUnclaimInput, type CoreStores, type MailboxAdvanceCursorInput, type MailboxAppendInput, type MailboxCursorState, type MailboxMessage, type MailboxPage, type MailboxReadQuery, type MailboxRecordDeliveryInput, type Principal, type PresenceHint, type PresenceHintInput, type TenantReadiness, type StorageFinalizeInput, type StorageFinalizeResult, type StorageReservation, type StorageReservationInput, type TenantId } from '@byok-sdk/core';
 import type { ActivityAppendInput, ActivityTail } from './activity';
 import type { ApprovalTimelineAppendInput, ApprovalTimelineTail } from './approval-timeline';
 import type { BlobObservation, CloudStores, DeviceRecord, AgentEgressRecord, RequestReceipt, TaskCancellationMutation, TaskCancellationRequest, TaskAttempt, TaskAttemptStatus } from './stores/ports';
@@ -29,6 +29,7 @@ export interface TenantBoundMailbox {
     append(input: MailboxAppendInput): Promise<MailboxMessage>;
     /** Pure read. Never advances the cursor — the daemon's next poll is the only ack. */
     readAfter(query: MailboxReadQuery): Promise<MailboxPage>;
+    recordDelivery(input: MailboxRecordDeliveryInput): Promise<MailboxCursorState>;
     advanceCursor(input: MailboxAdvanceCursorInput): Promise<MailboxCursorState>;
     readCursor(deviceId: string): Promise<MailboxCursorState>;
 }
@@ -77,6 +78,25 @@ export interface TenantBoundTaskAttempts {
         readonly attempt: TaskAttempt;
         readonly created: boolean;
     }>;
+    reserveAgentMessage(input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<'reserved' | 'pending' | 'rejected'>;
+    readAgentMessage(input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<import('./stores/ports').AgentMessageAdmission | undefined>;
+    finalizeAgentMessage(input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+        readonly terminalBody: string;
+    }): Promise<import('./stores/ports').AgentMessageAdmission | undefined>;
     get(taskId: string): Promise<TaskAttempt | undefined>;
     getMany(taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
     claim(input: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/cloud",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "BYOK SDK hosted device surface: stateless frozen-v1 HTTP handlers over tenant-first @byok-sdk/core ports",
   "type": "module",
   "license": "MIT",
@@ -44,8 +44,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@byok-sdk/core": "0.11.0",
-    "@byok-sdk/protocol": "0.11.0",
+    "@byok-sdk/core": "0.12.0",
+    "@byok-sdk/protocol": "0.12.0",
     "hono": "^4.12.30",
     "zod": "^4.4.3"
   }