@byok-sdk/cloud 0.1.0

package/dist/router/registry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The route inventory (sprint I1).
+ *
+ * Isolation review starts by asking "what routes exist, and what does each one
+ * require?" — a question that is only answerable if the answer cannot drift
+ * from what is actually mounted. So mounting goes through {@link
+ * CloudRouteRegistry.register} and nowhere else: the registry owns the Hono
+ * app, hands out no reference to it that could be mounted on directly, and
+ * records a class for every route as it goes.
+ *
+ * `src/__tests__/route-inventory.test.ts` closes that loop in BOTH directions
+ * against Hono's own `app.routes` table: a mounted route missing from the
+ * inventory fails the suite, and an inventoried route that never reached the
+ * router fails it too. A route whose class is not one of {@link ROUTE_CLASSES}
+ * cannot be registered at all.
+ */
+import { type Context } from 'hono';
+/**
+ * What a route requires of its caller. Not a description of the handler's
+ * work — a description of the credential it is authenticated by, which is the
+ * thing an isolation review has to enumerate:
+ *
+ * - `device` — a bearer access token; resolves to a `DevicePrincipal` and a
+ *   tenant-closed facade.
+ * - `proof` — a request-bound Ed25519 device proof; tenant/product/key
+ *   authority comes from the current device row, not protected claims.
+ * - `presigned` — no principal at all; an HMAC signature over the resource id
+ *   plus an expiry IS the credential (§7's two `/content` routes).
+ * - `public` — deliberately unauthenticated; must expose nothing tenant-scoped.
+ */
+export declare const ROUTE_CLASSES: readonly ['device', 'proof', 'presigned', 'public'];
+export type RouteClass = (typeof ROUTE_CLASSES)[number];
+export declare const ROUTE_METHODS: readonly ['GET', 'POST', 'PUT'];
+export type RouteMethod = (typeof ROUTE_METHODS)[number];
+export interface RouteDescriptor {
+    readonly method: RouteMethod;
+    readonly path: string;
+    readonly class: RouteClass;
+}
+export type CloudRouteHandler = (c: Context) => Response | Promise<Response>;
+export declare function routeKey(route: {
+    readonly method: string;
+    readonly path: string;
+}): string;
+export declare class CloudRouteRegistry {
+    #private;
+    register(descriptor: RouteDescriptor, handler: CloudRouteHandler): void;
+    /** The inventory, in registration order. */
+    get routes(): readonly RouteDescriptor[];
+    /** What the router actually mounted, read back off Hono itself — the other half of the I1 comparison. */
+    get mounted(): readonly {
+        readonly method: string;
+        readonly path: string;
+    }[];
+    get fetch(): (request: Request, ...rest: unknown[]) => Response | Promise<Response>;
+}

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

@@ -0,0 +1,89 @@
+/**
+ * The in-memory blob pair: metadata and bytes in process memory, HMAC-signed
+ * expiring URLs (docs/protocol.md §7).
+ *
+ * TWO objects, one shared record map, because the contract they satisfy is two
+ * things: {@link CloudBlobStore} is the tenant-first port every composition
+ * owes, and {@link BlobContentProxy} is the optional byte-carrying half. The
+ * in-memory composition is the one that supplies both — it has nowhere else to
+ * put bytes — which is why hosted-in-memory behavior is byte-for-byte what it
+ * was before the split.
+ *
+ * They cannot be one object: the port's method inventory is contract data
+ * (`CLOUD_PORT_METHODS`) and `@byok-sdk/conformance` asserts a composition's blob
+ * store implements EXACTLY the two declared methods. An object carrying all
+ * six would fail that assertion, which is the point — the suite is what keeps
+ * the narrowed port narrow.
+ *
+ * The presigned URL form — `/byok/blobs/<id>/content?sig=&exp=` — is the
+ * relative shape the daemon's blob client already resolves against its server
+ * base, so a hosted deployment is indistinguishable from a self-hosted one on
+ * this route too.
+ *
+ * Tenancy: `createUpload` records the owning tenant and reservation while
+ * `observeUpload`/`getDownloadUrl` refuse any other, so the three bearer routes are
+ * tenant-closed. The two `/content` routes are presigned by construction and
+ * have no principal at all — the signature over the blob id IS the credential
+ * (same posture as the reference server, §7).
+ */
+import { type Clock, type ContentHash, type ObjectStore, type StorageReservation, type TenantId } from '@byok-sdk/core';
+import type { CloudCrypto } from '../../crypto/port';
+import type { BlobContent, BlobContentProxy, BlobObservation, BlobWriteResult, CloudBlobStore } from '../ports';
+/** How long a presigned upload/download URL stays valid. */
+export declare const BLOB_URL_TTL_MS: number;
+interface BlobRecord {
+    readonly tenantId: TenantId;
+    readonly reservationId: string;
+    readonly contentHash: ContentHash;
+    readonly byteSize: bigint;
+    readonly contentType: string;
+    uploaded: boolean;
+    data?: Uint8Array;
+}
+export interface InMemoryBlobStoreOptions {
+    readonly urlTtlMs?: number;
+}
+/**
+ * The state both halves read, and the only thing they share.
+ *
+ * Module-private on purpose: it is not a port, and nothing outside this file
+ * should be able to reach a blob record without going through one of the two
+ * contracts above.
+ */
+declare class InMemoryBlobRegistry {
+    readonly blobs: Map<string, BlobRecord>;
+    readonly reservationBlobs: Map<string, string>;
+    readonly clock: Clock;
+    readonly crypto: CloudCrypto;
+    readonly secret: Uint8Array;
+    readonly urlTtlMs: number;
+    constructor(clock: Clock, crypto: CloudCrypto, options: InMemoryBlobStoreOptions);
+    signUrl(blobId: string, action: 'put' | 'get'): Promise<string>;
+    computeSig(blobId: string, action: 'put' | 'get', exp: number): Promise<string>;
+}
+/** The narrowed port: tenant-first grants, no bytes. */
+export declare class InMemoryCloudBlobStore implements CloudBlobStore {
+    #private;
+    constructor(registry: InMemoryBlobRegistry, objects: ObjectStore);
+    createUpload(tenant: TenantId, reservation: StorageReservation): Promise<{
+        blobId: string;
+        uploadUrl: string;
+    }>;
+    observeUpload(tenant: TenantId, blobId: string, reservation: StorageReservation): Promise<BlobObservation | undefined>;
+    getDownloadUrl(tenant: TenantId, blobId: string): Promise<string | undefined>;
+}
+/** The optional half: the bytes this composition has nowhere else to put. */
+export declare class InMemoryBlobContentProxy implements BlobContentProxy {
+    #private;
+    constructor(registry: InMemoryBlobRegistry);
+    verifySignedUrl(blobId: string, action: 'put' | 'get', sig: string, exp: number): Promise<boolean>;
+    writeContent(blobId: string, data: Uint8Array): Promise<BlobWriteResult>;
+    readContent(blobId: string): Promise<BlobContent | undefined>;
+}
+/** Both halves over one registry. The only way to obtain either. */
+export interface InMemoryBlobs {
+    readonly blobs: CloudBlobStore;
+    readonly contentProxy: BlobContentProxy;
+}
+export declare function createInMemoryBlobs(clock: Clock, crypto: CloudCrypto, objects: ObjectStore, options?: InMemoryBlobStoreOptions): InMemoryBlobs;
+export {};

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

@@ -0,0 +1,17 @@
+/**
+ * In-memory {@link InboundDedupStore} (N3).
+ *
+ * A bounded ring per (tenant, device), not an unbounded set: the wire is
+ * at-least-once (§9), so this makes processing at-most-once without letting a
+ * chatty device grow memory without limit. Check-and-record is one call, so a
+ * composition cannot accidentally split it into a racy read-then-write.
+ */
+import { type TenantId } from '@byok-sdk/core';
+import type { InboundDedupStore } from '../ports';
+/** Ids retained per device. Same order of magnitude as the reference server's ring. */
+export declare const DEDUP_RING_CAPACITY = 1024;
+export declare class InMemoryInboundDedupStore implements InboundDedupStore {
+    #private;
+    constructor(capacity?: number);
+    checkAndRecord(tenant: TenantId, deviceId: string, envelopeId: string): Promise<boolean>;
+}

package/dist/stores/in-memory/device-directory.d.ts

@@ -0,0 +1,19 @@
+/**
+ * In-memory {@link DeviceDirectory}.
+ *
+ * Rows live under a `(tenant, deviceId)` composite key, so a cross-tenant read
+ * is not "denied" — it addresses a different key space and finds nothing
+ * (§12.6.2 layer 3). The pre-tenant index below holds the SAME record objects,
+ * so a revocation applied through the composite key is immediately visible to
+ * `/byok/challenge` and `/byok/token` with no second copy to keep in sync.
+ */
+import { type TenantId } from '@byok-sdk/core';
+import type { DeviceDirectory, DeviceRecord, DeviceRegistration } from '../ports';
+export declare class InMemoryDeviceDirectory implements DeviceDirectory {
+    #private;
+    register(tenant: TenantId, input: DeviceRegistration): Promise<DeviceRecord>;
+    get(tenant: TenantId, deviceId: string): Promise<DeviceRecord | undefined>;
+    revoke(tenant: TenantId, deviceId: string): Promise<void>;
+    list(tenant: TenantId): Promise<readonly DeviceRecord[]>;
+    resolveByDeviceId(deviceId: string): Promise<DeviceRecord | undefined>;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * The in-memory reference implementation of every cloud-local port.
+ *
+ * Same posture as `@byok-sdk/core`'s: a reference, not a production store. What it
+ * guarantees is that the behavior the handler suites assert is achievable
+ * without a database — which is what makes those same assertions meaningful
+ * when a durable composition (S3b's journal, S4A's schema) runs them later.
+ */
+import type { Clock, ObjectStore } from '@byok-sdk/core';
+import type { CloudCrypto } from '../../crypto/port';
+import type { BlobContentProxy, CloudStores } from '../ports';
+export { AllowAllRateLimiter } from './rate-limiter';
+export { BLOB_URL_TTL_MS, InMemoryBlobContentProxy, InMemoryCloudBlobStore, createInMemoryBlobs, } from './blobs';
+export type { InMemoryBlobs, InMemoryBlobStoreOptions } from './blobs';
+export { DEDUP_RING_CAPACITY, InMemoryInboundDedupStore } from './dedup';
+export { InMemoryDeviceDirectory } from './device-directory';
+export { InMemoryDeviceSequenceStore } from './sequence';
+export { InMemoryNonceStore, NONCE_TTL_MS } from './nonces';
+export { InMemoryPairingCodeStore } from './pairing-codes';
+export { InMemoryRequestReceiptStore } from './receipts';
+export { InMemoryProofRequestReceiptStore } from './proof-receipts';
+export { InMemoryTaskAttemptStore } from './task-attempts';
+/**
+ * The port bundle plus the byte proxy, in the shape `createInMemoryCoreStores`
+ * already uses: the composition is an object with a `stores` field, not the
+ * bundle itself.
+ *
+ * `blobContentProxy` sits BESIDE `stores` rather than inside it because it is
+ * not a port — `createByokCloud` takes it as its own optional input, and a
+ * composition that cannot carry bytes simply has none to hand over.
+ */
+export interface InMemoryCloudComposition {
+    readonly stores: CloudStores;
+    readonly blobContentProxy: BlobContentProxy;
+}
+export declare function createInMemoryCloudStores(clock: Clock, crypto: CloudCrypto, objects: ObjectStore): InMemoryCloudComposition;

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

@@ -0,0 +1,22 @@
+/**
+ * In-memory {@link NonceStore}: single-use challenge nonces, ~5min TTL
+ * (docs/protocol.md §6.2).
+ *
+ * A nonce is bound to the (tenant, device) it was issued for, so a nonce
+ * issued to one tenant's device is not validatable by another's even if the
+ * value leaks.
+ */
+import { type Clock, type TenantId } from '@byok-sdk/core';
+import type { CloudCrypto } from '../../crypto/port';
+import type { NonceStore } from '../ports';
+/** ~5min, matching the reference server (docs/protocol.md §6.2). */
+export declare const NONCE_TTL_MS: number;
+export declare class InMemoryNonceStore implements NonceStore {
+    #private;
+    constructor(clock: Clock, crypto: CloudCrypto, ttlMs?: number);
+    /** 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>;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ * 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.
+ */
+import type { Clock, TenantId } from '@byok-sdk/core';
+import type { PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore } from '../ports';
+export declare class InMemoryPairingCodeStore implements PairingCodeStore {
+    #private;
+    constructor(clock: Clock);
+    issue(tenant: TenantId, input: PairingCodeIssueInput): Promise<PairingCodeInfo>;
+    redeem(code: string): Promise<PairingCodeClaims | undefined>;
+}

package/dist/stores/in-memory/proof-receipts.d.ts

@@ -0,0 +1,11 @@
+import { type Clock, type TenantId } from '@byok-sdk/core';
+import type { ProofRequestReceipt, ProofRequestReceiptInput, ProofRequestReceiptStore } from '../ports';
+export declare class InMemoryProofRequestReceiptStore implements ProofRequestReceiptStore {
+    #private;
+    constructor(clock: Clock);
+    record(tenant: TenantId, input: ProofRequestReceiptInput): Promise<{
+        readonly receipt: ProofRequestReceipt;
+        readonly created: boolean;
+    }>;
+    get(tenant: TenantId, deviceId: string, requestId: string): Promise<ProofRequestReceipt | undefined>;
+}

package/dist/stores/in-memory/rate-limiter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The reference {@link InboundRateLimiter}: allow-all.
+ *
+ * S3a's job is to put the seam at gate position 0 — before the type-allow
+ * check — not to invent a limiter policy. A hosted deployment's real budget
+ * lives at its edge; when it arrives it plugs in here and the gate order does
+ * not move.
+ */
+import type { TenantId } from '@byok-sdk/core';
+import type { InboundRateLimiter } from '../ports';
+export declare class AllowAllRateLimiter implements InboundRateLimiter {
+    consume(_tenant: TenantId, _deviceId: string): Promise<boolean>;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * In-memory {@link RequestReceiptStore}: first write wins.
+ *
+ * The terminal a device reports is a fact, and a retry of the same terminal
+ * (the wire is at-least-once) must not overwrite the first one — `created:
+ * false` is how the caller learns it was a replay rather than a new fact.
+ */
+import { type Clock, type TenantId } from '@byok-sdk/core';
+import type { RequestReceipt, RequestReceiptStore } from '../ports';
+export declare class InMemoryRequestReceiptStore implements RequestReceiptStore {
+    #private;
+    constructor(clock: Clock);
+    record(tenant: TenantId, input: {
+        key: string;
+        body: string;
+    }): Promise<{
+        receipt: RequestReceipt;
+        created: boolean;
+    }>;
+    get(tenant: TenantId, key: string): Promise<RequestReceipt | undefined>;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * In-memory {@link DeviceSequenceStore}: a monotonic per-(tenant, device)
+ * delivery counter starting at 1, matching what a mailbox numbers its first
+ * row.
+ */
+import { type TenantId } from '@byok-sdk/core';
+import type { DeviceSequenceStore } from '../ports';
+export declare class InMemoryDeviceSequenceStore implements DeviceSequenceStore {
+    #private;
+    next(tenant: TenantId, deviceId: string): Promise<number>;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * In-memory {@link TaskAttemptStore} — the ownership authority the inbound
+ * gate reads (N2).
+ *
+ * Two deliberate no-ops:
+ *
+ * - `claim` on a task this tenant never offered writes nothing. A device that
+ *   guesses a taskId must not be able to conjure a row (and, cross-tenant,
+ *   must not leave a trace in the tenant it guessed into).
+ * - `recordStatus` on an unknown task writes nothing, mirroring the reference
+ *   server's per-type handlers, whose behavior on a missing record is a no-op
+ *   rather than a rejection.
+ *
+ * Ownership is first-claim-wins and never transfers: reassigning an owner is
+ * the one operation that would make the gate's cross-device assertion
+ * unfalsifiable.
+ */
+import { type Clock, type TenantId } from '@byok-sdk/core';
+import type { TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '../ports';
+export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
+    #private;
+    constructor(clock: Clock);
+    open(tenant: TenantId, input: {
+        taskId: string;
+        deviceId: string;
+    }): Promise<TaskAttempt>;
+    get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
+    claim(tenant: TenantId, input: {
+        taskId: string;
+        deviceId: string;
+    }): Promise<TaskAttempt | undefined>;
+    recordStatus(tenant: TenantId, input: {
+        taskId: string;
+        status: TaskAttemptStatus;
+    }): Promise<TaskAttempt | undefined>;
+}

package/dist/stores/ports-contract.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The declared method inventory of every cloud-local port.
+ *
+ * The exact counterpart of `@byok-sdk/core`'s `ports-contract.ts`, and it exists
+ * for the same reason: the table says what a port IS, so it has to be readable
+ * by every enforcer without any of them owning it. `@byok-sdk/conformance` asserts
+ * live compositions against it; a durable adapter (`@byok-sdk/cloud-postgres`) is
+ * written against it.
+ *
+ * This module adds data and nothing else. It does not re-declare, re-shape, or
+ * re-interpret a single line of `ports.ts` — that file stays the authority for
+ * what the methods mean, and stayed byte-identical through S4A-a.
+ *
+ * Adding a port method means editing this table, which is the point: a port
+ * grows by contract, not by whichever composition needed something.
+ */
+import type { CloudStoreName } from './ports';
+export declare const CLOUD_PORT_METHODS: Readonly<Record<CloudStoreName, readonly string[]>>;
+/** The interface each port name is declared as, for a source-side scan. */
+export declare const CLOUD_PORT_INTERFACES: Readonly<Record<CloudStoreName, string>>;