@byok-sdk/server 0.1.0

package/dist/ids.d.ts

@@ -0,0 +1,3 @@
+export declare function generatePairingCode(length?: number): string;
+export declare function generateDeviceId(): string;
+export declare function generateTaskId(): string;

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+import type { Server as HttpServer } from 'node:http';
+import type { Hono } from 'hono';
+import { type TenantId } from './auth';
+import { type PairingCodeClaims, type PairingCodeInfo } from './pairing';
+import type { ByokServerEvent, CreateByokServerOptions, DispatchInput, HubStats, MachineInfo, TaskHandle, TaskSnapshot } from './types';
+export type { ByokServerEvent, CreateByokServerOptions, DispatchInput, HubStats, MachineInfo, ServerTaskEvent, TaskHandle, TaskResult, TaskSnapshot, } from './types';
+export type { CreateTaskInput, TaskRecord, TaskStore } from './task-store';
+export { IllegalTaskTransitionError, InMemoryTaskStore } from './task-store';
+/**
+ * M5 (approval targeting, docs/protocol.md §5.3): previously unreachable via
+ * this package's public entry point (only importable from the internal
+ * `./hub` path) — `TaskHandle.approve`/`reject`'s `opts.approvalId` targeting
+ * (`types.ts`) throws this, so a caller needs it exported here to
+ * `instanceof`-check/inspect it. See `hub.ts`'s own doc comment for the full
+ * staleness semantics.
+ */
+export { StaleApprovalError } from './hub';
+/**
+ * S0 (GAP-002): `TaskHandle.steer` (`types.ts`) throws this when the runtime
+ * that claimed the task cannot be steered, when the task isn't running, or
+ * when it's already terminal — a caller needs the class to `instanceof`-check
+ * it and the code union to switch on. See `hub.ts`'s own doc comments for the
+ * full gate order and the fail-closed-on-unknown rationale.
+ */
+export { SteerRejectedError } from './hub';
+export type { SteerRejectionCode } from './hub';
+export { PairingCodeInvalidError } from './pairing';
+export type { PairingCodeClaims, PairingCodeInfo } from './pairing';
+export type { AccessTokenClaims, AuthenticatedDevice, DeviceRecord, TenantId, TokenSigner, } from './auth';
+/**
+ * S1: `DeviceRegistry` itself is deliberately NOT exported. Its
+ * tenant-scoped surface is reachable through `ByokServer.devices` (below),
+ * and the one method that resolves a device without a tenant in scope
+ * (`resolveByDeviceId`, for the two pre-tenant wire endpoints) exists only
+ * inside this package — exporting the class would hand every embedder a
+ * cross-tenant device oracle for free.
+ */
+export { createHmacTokenSigner } from './auth';
+export type { BlobStore, CreateUploadInput, ReadContentResult, WriteContentResult, } from './blob-store';
+export { LocalDiskBlobStore } from './blob-store';
+export type { SqliteTaskStoreOptions } from './sqlite-task-store';
+export { SqliteTaskStore } from './sqlite-task-store';
+export type { SqliteBlobStoreOptions } from './sqlite-blob-store';
+export { SqliteBlobStore } from './sqlite-blob-store';
+export { SqliteUnavailableError } from './sqlite-support';
+export type { RateLimiterOptions } from './rate-limiter';
+/** The object `createByokServer` returns — the SaaS-embedder-facing surface. */
+export interface ByokServer {
+    /** Hono app exposing the pair/challenge/token/blob/events HTTP routes. Mount it, or use its `.fetch` with `@hono/node-server`. */
+    hono: Hono;
+    /** Wire up the `GET /byok/ws` upgrade on the raw Node HTTP server serving `hono`. */
+    attachWebSocket(server: HttpServer): void;
+    pairing: {
+        /**
+         * S1: minting a code REQUIRES the tenant and product the redeeming
+         * device will be paired into (docs/protocol.md §6.1) — the SaaS's own
+         * auth/device-flow UI is the only party that knows them, and the device
+         * never gets to name its own. There is no claimless overload.
+         */
+        createPairingCode(claims: PairingCodeClaims): PairingCodeInfo;
+    };
+    dispatch(input: DispatchInput): Promise<TaskHandle>;
+    tasks: {
+        get(taskId: string): TaskSnapshot | undefined;
+        list(): TaskSnapshot[];
+    };
+    machines: {
+        list(): MachineInfo[];
+    };
+    events: {
+        subscribe(): AsyncIterable<ByokServerEvent>;
+    };
+    /**
+     * Device revocation (§6.3) — server-side only, no wire message. Revoking a
+     * device makes its next `/byok/challenge`, `/byok/token`, WSS connect, or
+     * authed HTTP call get a 401; its only recourse is to re-run `/byok/pair`.
+     *
+     * S1: tenant-first, and a tenant can only revoke a device it owns — a
+     * `(tenantId, deviceId)` pair belonging to someone else resolves to
+     * nothing and this is a silent no-op rather than a cross-tenant write.
+     */
+    devices: {
+        revoke(tenantId: TenantId, deviceId: string): void;
+    };
+    /**
+     * Stop background timers owned by this server instance — currently just
+     * the task-lease reaper (`ConnectionHub.stopLeaseReaper`, `hub.ts`). Call
+     * this on shutdown so nothing keeps the process alive or leaks a handle in
+     * tests; safe to call more than once.
+     */
+    stop(): void;
+    /**
+     * M4 Phase 4 (part B.1): a plain, serializable in-process snapshot of this
+     * hub's current state — connected device count, task counts by state,
+     * envelope in/out totals, dedup drops, rate-limit events, and uptime. See
+     * {@link HubStats} for the full contract. Deliberately in-process only —
+     * never exposed over HTTP by this SDK itself (see
+     * `CreateByokServerOptions.healthzRoute`'s doc comment); an embedder that
+     * wants any of this surfaced remotely builds its own authenticated route
+     * around this method.
+     */
+    stats(): HubStats;
+}
+/**
+ * In-memory reference implementation of the SaaS-side coordinator: Auth v2
+ * device pairing/renewal/revocation, a WS + long-poll connection hub with
+ * at-least-once redelivery, a local-disk blob store, and task dispatch/
+ * lifecycle tracking. See the per-module doc comments (`auth.ts`,
+ * `blob-store.ts`, `hub.ts`, `pairing.ts`, `ws-server.ts`) for what's a
+ * pinned wire/HTTP contract (docs/protocol.md) versus a reference-impl
+ * choice a SaaS embedder might swap out (`tokenSigner`, `blobStore`,
+ * `taskStore` — the latter two default to in-memory/local-disk and lose all
+ * state on restart; see `sqlite-task-store.ts`/`sqlite-blob-store.ts` for
+ * persistent M3 alternatives implementing the same interfaces).
+ */
+export declare function createByokServer(opts: CreateByokServerOptions): ByokServer;