@byok-sdk/server 0.11.0 → 0.12.0

package/dist/blob-store.d.ts

@@ -1,3 +1,4 @@
+import type { TenantId } from './auth';
 /**
  * Blob flows (docs/protocol.md §7): `POST /byok/blobs` declares a blob and
  * gets back a presigned upload URL; the caller `PUT`s the bytes there
@@ -8,9 +9,9 @@
  *
  * `BlobStore` is interface-shaped so a SaaS can swap in a real object-store
  * (S3/GCS/R2 presigned URLs) later; {@link LocalDiskBlobStore} is the M1
- * reference implementation (single-process, in-memory metadata + files on
- * disk) — good enough for local dev and the SDK's own tests, not meant to
- * survive a restart or run multi-process.
+ * reference implementation (single-process, persisted metadata + files on
+ * disk) — good enough for local dev and the SDK's own tests, including a
+ * restart of the same directory; it is not multi-process storage.
  */
 export interface CreateUploadInput {
     size: number;
@@ -28,19 +29,25 @@ export interface ReadContentResult {
     data: Buffer;
     contentType: string;
 }
+/** The upload reservation HTTP must resolve before it starts retaining bytes. */
+export interface BlobUploadReservation {
+    size: number;
+}
 export declare class BlobDeclarationConflictError extends Error {
     constructor(blobId: string);
 }
 export interface BlobStore {
     /** Declare a blob before upload; an explicit id makes the declaration idempotent across host restart. */
-    createUpload(input: CreateUploadInput, blobId?: string): Promise<{
+    createUpload(tenantId: TenantId, input: CreateUploadInput, blobId?: string): Promise<{
         blobId: string;
         uploadUrl: string;
     }>;
     /** A presigned GET URL for a blob that has finished uploading, or `undefined` if unknown/not yet uploaded. */
-    getDownloadUrl(blobId: string): Promise<string | undefined>;
+    getDownloadUrl(tenantId: TenantId, blobId: string): Promise<string | undefined>;
     /** Whether `blobId` is known *and* has finished uploading. */
-    exists(blobId: string): Promise<boolean>;
+    exists(tenantId: TenantId, blobId: string): Promise<boolean>;
+    /** Resolve a capability URL's immutable declared size before consuming its body. */
+    getUploadReservation(blobId: string): Promise<BlobUploadReservation | undefined>;
     /** Verify a presigned content URL's `sig`/`exp` query params for `action`. */
     verifySignedUrl(blobId: string, action: 'put' | 'get', sig: string, exp: number): boolean;
     /** Accept uploaded bytes; rejects (without storing) on size/hash mismatch against the `createUpload` declaration. */
@@ -54,24 +61,29 @@ export interface LocalDiskBlobStoreOptions {
     /** How long a presigned upload/download URL stays valid, ms. Default 15 minutes. */
     urlTtlMs?: number;
 }
-/** Local-disk reference {@link BlobStore}: in-memory metadata, content on disk, HMAC-signed expiring URLs. */
+/** Local-disk reference {@link BlobStore}: persisted metadata/content and HMAC-signed expiring URLs. */
 export declare class LocalDiskBlobStore implements BlobStore {
-    private readonly secret;
+    private secret;
     private readonly directory;
+    private readonly metadataPath;
     private readonly urlTtlMs;
     private readonly blobs;
     private readonly ready;
+    private metadataWriteTail;
     constructor(opts?: LocalDiskBlobStoreOptions);
-    createUpload(input: CreateUploadInput, requestedBlobId?: string): Promise<{
+    createUpload(tenantId: TenantId, input: CreateUploadInput, requestedBlobId?: string): Promise<{
         blobId: string;
         uploadUrl: string;
     }>;
-    getDownloadUrl(blobId: string): Promise<string | undefined>;
-    exists(blobId: string): Promise<boolean>;
+    getDownloadUrl(tenantId: TenantId, blobId: string): Promise<string | undefined>;
+    exists(tenantId: TenantId, blobId: string): Promise<boolean>;
+    getUploadReservation(blobId: string): Promise<BlobUploadReservation | undefined>;
     verifySignedUrl(blobId: string, action: 'put' | 'get', sig: string, exp: number): boolean;
     writeContent(blobId: string, data: Buffer): Promise<WriteContentResult>;
     readContent(blobId: string): Promise<ReadContentResult | undefined>;
     private pathFor;
+    private loadMetadata;
+    private persistMetadata;
     private computeSig;
     private signUrl;
 }

package/dist/hub.d.ts

@@ -194,6 +194,12 @@ export declare class AgentHomeProjectionCompletionError extends Error {
     readonly code: AgentHomeProjectionCompletionErrorCode;
     constructor(code: AgentHomeProjectionCompletionErrorCode, message: string);
 }
+/** A requested delivery cursor predates controls this bounded hub can recover. */
+export declare class ReplayGapError extends Error {
+    readonly cursor: number;
+    readonly recoverableFrom: number;
+    constructor(cursor: number, recoverableFrom: number);
+}
 export declare class ConnectionHub {
     private readonly taskStore;
     private readonly devices;
@@ -211,6 +217,7 @@ export declare class ConnectionHub {
     private readonly rateLimiter;
     private readonly agentMessage?;
     private readonly connections;
+    private readonly connectionEpochs;
     private readonly outboxes;
     /** Idempotency window per device (N3) — recent inbound envelope ids, capped at {@link DEDUP_RING_CAPACITY}. */
     private readonly dedupRings;
@@ -302,7 +309,9 @@ export declare class ConnectionHub {
      * connection this hub never learns capabilities for simply reads back
      * `undefined` from {@link getDeviceCapabilities}.
      */
-    registerConnection(deviceId: string, ws: WebSocket, runtimes: RuntimeInfo[] | undefined, capabilities?: readonly string[], configuredToolsets?: readonly ToolsetId[], clientVersion?: string): void;
+    registerConnection(deviceId: string, ws: WebSocket, runtimes: RuntimeInfo[] | undefined, capabilities?: readonly string[], configuredToolsets?: readonly ToolsetId[], clientVersion?: string): number;
+    /** True only while this exact WS registration remains the device authority. */
+    isCurrentConnection(deviceId: string, ws: WebSocket, epoch: number): boolean;
     sendConnAck(deviceId: string, capabilities: string[]): void;
     /**
      * Reconnection procedure step 3 (§9): redeliver, in `seq` order, every
@@ -897,10 +906,17 @@ export declare class ConnectionHub {
      * on any future reconnect/poll.
      */
     private collectRelevant;
+    /**
+     * A caller at `recoverableFrom - 1` can still receive the first retained
+     * control. Anything earlier would be a partial tail and must fail closed.
+     */
+    assertReplayAvailable(deviceId: string, cursor: number, pendingOutbound?: number): void;
+    private isRecoverableEntry;
     private isTaskTerminal;
     /** The highest `seq` assigned to `deviceId` so far — the redelivery cursor to hand back on a poll/reconnect. */
     private currentCursor;
     private getOrCreateOutbox;
+    private nextConnectionEpoch;
     listMachines(): MachineInfo[];
     /**
      * M5 (approval targeting, hello-capability plumbing): the capability flags

package/dist/index.d.ts

@@ -26,8 +26,8 @@ export { SteerRejectedError } from './hub';
 export type { SteerRejectionCode } from './hub';
 export { AgentHomeProjectionCompletionError } from './hub';
 export type { AgentHomeProjectionCompletionErrorCode } from './hub';
-export { PairingCodeInvalidError } from './pairing';
-export type { PairingCodeClaims, PairingCodeInfo } from './pairing';
+export { PairingAttemptConflictError, PairingCodeInvalidError } from './pairing';
+export type { PairingAttemptBinding, PairingCodeClaims, PairingCodeInfo, PairingCompletion } from './pairing';
 export type { AccessTokenClaims, AuthenticatedDevice, DeviceRecord, TenantId, TokenSigner, } from './auth';
 /**
  * S1: `DeviceRegistry` itself is deliberately NOT exported. Its
@@ -38,7 +38,7 @@ export type { AccessTokenClaims, AuthenticatedDevice, DeviceRecord, TenantId, To
  * cross-tenant device oracle for free.
  */
 export { createHmacTokenSigner } from './auth';
-export type { BlobStore, CreateUploadInput, ReadContentResult, WriteContentResult, } from './blob-store';
+export type { BlobStore, BlobUploadReservation, CreateUploadInput, ReadContentResult, WriteContentResult, } from './blob-store';
 export { LocalDiskBlobStore } from './blob-store';
 export type { SqliteTaskStoreOptions } from './sqlite-task-store';
 export { SqliteTaskStore } from './sqlite-task-store';