@byok-sdk/server 0.1.0

package/dist/pairing.d.ts

@@ -0,0 +1,58 @@
+import type { TenantId } from './auth';
+/**
+ * S1: the tenant identity a pairing code carries. Minted out-of-band by the
+ * SaaS's own auth/device-flow UI — the only party that knows which tenant a
+ * human is acting for — and returned by {@link PairingManager.redeemPairingCode}
+ * so `POST /byok/pair` can write it onto the device row in the same
+ * synchronous step that consumes the code.
+ *
+ * Deliberately NOT a wire field: `PairRequest` has no tenant of its own
+ * (docs/protocol.md §6.1), so a device can never name the tenant it lands in.
+ * These claims are the single source of truth for the row, and the row — not
+ * a later token, and never client input — is what every authed surface
+ * checks against.
+ */
+export interface PairingCodeClaims {
+    tenantId: TenantId;
+    productId: string;
+}
+export interface PairingCodeInfo {
+    code: string;
+    expiresAt: string;
+}
+/** Thrown when a pairing code is missing, expired, or already used. */
+export declare class PairingCodeInvalidError extends Error {
+    constructor(reason: string);
+}
+/**
+ * In-memory pairing-code lifecycle: single-use, ~10min TTL codes minted
+ * out-of-band (by the SaaS's own auth/device-flow UI) and redeemed exactly
+ * once by `POST /byok/pair`.
+ *
+ * Device identity (deviceId/deviceName/devicePublicKey/revocation) and
+ * token issuance moved to `auth.ts`'s `DeviceRegistry`/`TokenSigner` as of
+ * Auth v2 (docs/protocol.md §6) — this class knows about devices only to the
+ * extent of carrying the {@link PairingCodeClaims} that decide which tenant
+ * and product the device being paired will belong to (S1).
+ */
+export declare class PairingManager {
+    private readonly codes;
+    /**
+     * Mint a single-use code bound to `claims`. Claims are REQUIRED — a
+     * claimless mint is a compile error, and (for a JS caller, or a claims
+     * object assembled from untyped config) a runtime {@link TypeError}. There
+     * is no default tenant and no default product: a device with no tenant
+     * must be inexpressible, so the failure happens here, at the mint, rather
+     * than being filled in downstream.
+     */
+    createPairingCode(claims: PairingCodeClaims): PairingCodeInfo;
+    /**
+     * Validate and consume a pairing code, returning the {@link PairingCodeClaims}
+     * it was minted with. Throws {@link PairingCodeInvalidError} if the code is
+     * unknown, expired, or already used — callers (the HTTP handler) map that to
+     * a 401. Single-use is what makes the caller's "redeem, then register the
+     * device row with these claims" sequence safe: a second redeem of the same
+     * code can never reach the registration step at all.
+     */
+    redeemPairingCode(code: string): PairingCodeClaims;
+}

package/dist/rate-limiter.d.ts

@@ -0,0 +1,114 @@
+/**
+ * M4 Phase 4 (part A): per-key token bucket, used by `ConnectionHub`
+ * (`hub.ts`) to rate-limit inbound daemon->server envelopes per device.
+ * Framework-agnostic on purpose (no hub/transport types here) so it stays
+ * unit-testable in isolation, mirroring `event-queue.ts`'s own
+ * transport-agnostic split.
+ *
+ * Token bucket, not a fixed window: `burst` tokens are available immediately
+ * (accommodating a legitimate short spike — e.g. a reconnect's redelivery
+ * catch-up), refilling continuously at `messagesPerSecond` tokens/sec up to
+ * that same `burst` ceiling. A bucket is created lazily per key on first use
+ * and persists for as long as it stays active — deliberately NOT reset when
+ * a device disconnects/reconnects (see `ConnectionHub`'s own use of this
+ * class): resetting on reconnect would let a device that just got
+ * disconnected for exceeding its budget immediately burst again on
+ * reconnect, defeating the limit entirely. It IS dropped once idle long
+ * enough that keeping it around would be pointless — see
+ * `evictIdleBucketsIfDue`.
+ *
+ * Construction validates `messagesPerSecond`/`burst` fail-fast (throws
+ * `TypeError` on anything non-finite or <= 0) rather than silently building
+ * a limiter that either divides into `NaN` token math or (an `Infinity`
+ * burst/rate) never actually limits anything.
+ *
+ * Finding R5 (cross-model re-review — F10 residual): `burst` specifically
+ * must be `>= 1`, not merely `> 0`. A `0 < burst < 1` value used to pass
+ * the old `<= 0` check cleanly, but `consume()`'s own debit logic
+ * (`if (bucket.tokens < 1) return false;`) can NEVER succeed once the
+ * bucket's own CEILING (`burst`) is itself below 1 — `Math.min(this.burst,
+ * ...)` caps refill there, so `tokens` can never reach 1 no matter how
+ * long the bucket sits idle. The old validation let this construct
+ * silently — a limiter that rejects every single message, forever, for
+ * every key, is not a rate LIMIT, it's a permanent, total block; that
+ * should be a construction-time error, not a runtime surprise discovered
+ * once real traffic starts getting rejected.
+ */
+export interface RateLimiterOptions {
+    /** Sustained refill rate, tokens (i.e. messages) per second. Must be a finite number > 0. Default 50. */
+    messagesPerSecond?: number;
+    /** Bucket capacity — how many messages may arrive back-to-back before the limit engages. Must be a finite number >= 1 (finding R5 — see the module doc comment for why `< 1` can never let a single message through, ever). Default 100. */
+    burst?: number;
+    /** Hard cap on how many distinct keys (finding R5) this limiter tracks at once — see {@link DEFAULT_MAX_TRACKED_DEVICES}'s own doc comment. Must be a finite number >= 1. Default 10,000. */
+    maxTrackedDevices?: number;
+}
+export declare class RateLimiter {
+    private readonly messagesPerSecond;
+    private readonly burst;
+    private readonly buckets;
+    /**
+     * Wall-clock idle duration (ms) after which a bucket is GUARANTEED to
+     * already be refilled to `burst`, regardless of its actual token count at
+     * last touch — i.e. the time to go from 0 tokens to `burst` at this
+     * instance's configured rate. `evictIdleBucketsIfDue` uses this as the
+     * eviction threshold: dropping an entry idle at least this long and
+     * recreating it fresh (tokens = burst) on the next `consume()` is
+     * therefore behaviorally IDENTICAL to refilling it in place would have
+     * been — both cap at `burst` — so eviction is semantically invisible to
+     * the caller.
+     */
+    private readonly idleEvictionThresholdMs;
+    /** Finding R5: hard cap on `buckets.size` — see {@link DEFAULT_MAX_TRACKED_DEVICES}'s own doc comment. */
+    private readonly maxTrackedDevices;
+    /** Calls to `consume()` since the last sweep — see `EVICTION_SWEEP_EVERY_N_CALLS`. */
+    private callsSinceSweep;
+    constructor(opts?: RateLimiterOptions);
+    /**
+     * Debit one token from `key`'s bucket, refilling first for however much
+     * wall-clock time has elapsed since its last refill. Returns `false`
+     * (and debits nothing) when the bucket is currently empty — the caller is
+     * over budget right now.
+     */
+    consume(key: string): boolean;
+    /**
+     * Every `EVICTION_SWEEP_EVERY_N_CALLS` calls to `consume()`, drops every
+     * bucket idle for at least `idleEvictionThresholdMs` (see that field's doc
+     * comment for why this is safe). Without this, `buckets` would hold one
+     * permanent entry per historical key forever — every device that ever
+     * connected, even long after it disconnected for good — growing without
+     * bound over a long-lived server's lifetime.
+     */
+    private evictIdleBucketsIfDue;
+    /**
+     * Finding R5 (cross-model re-review — F10 residual): called right before
+     * inserting a bucket for a genuinely NEW key, evicting the single
+     * LEAST-RECENTLY-refilled entry if `buckets` is already at
+     * `maxTrackedDevices` — an O(n) scan, but one that only ever runs once
+     * the map is already at its hard ceiling (a rare/bounded event under
+     * ordinary operation, not a per-call cost), mirroring this codebase's own
+     * established "acceptable O(n) for a rare/bounded case" precedent (e.g.
+     * `audit-log.ts`'s `compactPreservingLiveTasks` during rotation).
+     *
+     * Equivalence split (stated explicitly, not left implied):
+     * - For any evicted bucket that was ALREADY idle for at least
+     *   `idleEvictionThresholdMs` (i.e. `evictIdleBucketsIfDue` would have
+     *   reclaimed it anyway, just not yet — sweeps only run every
+     *   `EVICTION_SWEEP_EVERY_N_CALLS` calls, not continuously), eviction is
+     *   PROVABLY equivalent to an in-place refill: both cap at `burst`, so a
+     *   caller can never observe the difference (see `idleEvictionThresholdMs`'s
+     *   own doc comment for the identical reasoning `evictIdleBucketsIfDue`
+     *   already relies on).
+     * - For a bucket evicted EARLY — still within its idle threshold, forced
+     *   out only because `buckets` is at capacity (many thousands of
+     *   genuinely-distinct, actively-used keys, not a quiet one) — this is
+     *   BEST-EFFORT, not equivalence-preserving: whatever partial token debt
+     *   that key had is discarded, and its very next `consume()` call starts
+     *   completely fresh (`tokens: this.burst`), a strictly MORE permissive
+     *   outcome than if it had kept its place. This is an accepted,
+     *   deliberately bounded trade-off — it only ever engages under
+     *   cardinality far beyond any plausible real deployment — favoring
+     *   bounded memory over perfect per-key continuity in that one extreme
+     *   case.
+     */
+    private evictOldestIfAtCapacity;
+}

package/dist/sqlite-blob-store.d.ts

@@ -0,0 +1,89 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type BlobStore, type CreateUploadInput, type ReadContentResult, type WriteContentResult } from './blob-store';
+export interface SqliteBlobStoreOptions {
+    /**
+     * Database file path. Use `:memory:` to exercise the SQLite code path
+     * without persistence — defeats this store's whole purpose (same caveat
+     * as `SqliteTaskStore`'s `:memory:` option); real restart-safety requires
+     * a real file path.
+     */
+    path: string;
+    /** How long a presigned upload/download URL stays valid, ms. Default 15 minutes — same default as `LocalDiskBlobStore`. */
+    urlTtlMs?: number;
+    /**
+     * HMAC signing key for presigned URLs. Defaults to a key generated once
+     * and persisted in this same database (a `meta` table) — so, unlike
+     * `LocalDiskBlobStore`'s fresh-per-instance `randomBytes(32)` (fine there
+     * only because its metadata doesn't survive a restart either), the
+     * default here is *already* stable across restarts: a URL signed by one
+     * process instance still verifies against a later instance pointed at
+     * the same database file. Pass this explicitly only if the key needs to
+     * live outside the database (e.g. shared across multiple database files,
+     * or rotated independently of the data).
+     */
+    signingKey?: Buffer;
+}
+/** Exported (only) so `sqlite-blob-store.test.ts` can apply the same schema to a raw `DatabaseSync` connection when testing {@link loadOrCreateSigningSecret}'s concurrency behavior directly. */
+export declare const SCHEMA = "\nCREATE TABLE IF NOT EXISTS meta (\n  key   TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS blobs (\n  blob_id      TEXT PRIMARY KEY,\n  size         INTEGER NOT NULL,\n  content_type TEXT NOT NULL,\n  content_hash TEXT NOT NULL,\n  uploaded     INTEGER NOT NULL DEFAULT 0,\n  data         BLOB\n);\n";
+/**
+ * Atomically load the persisted HMAC signing secret from `db`'s `meta`
+ * table, generating and persisting one if none exists yet.
+ *
+ * Safe under two `DatabaseSync` connections racing on the same file — e.g.
+ * two fresh `SqliteBlobStore` instances constructed against a brand-new
+ * database at nearly the same moment. Both may see no existing row (via the
+ * initial `SELECT`) and both generate a candidate secret, but `INSERT OR
+ * IGNORE` guarantees at most one candidate is ever persisted, and —
+ * critically — EVERY caller unconditionally re-reads the row afterward and
+ * returns THAT value, never its own locally-generated candidate. Without
+ * that re-read (the bug this fixes: the previous implementation used
+ * `INSERT OR REPLACE` and returned its own candidate unconditionally), a
+ * caller whose candidate lost the race would keep using its own discarded
+ * value in memory — so a presigned URL it signs would fail to verify
+ * against any other instance, which persisted (and uses) the winning value.
+ *
+ * `generateCandidate` defaults to `randomBytes(32)`; overridable so
+ * `sqlite-blob-store.test.ts` can deterministically force the race window —
+ * real callers never need to pass it.
+ */
+export declare function loadOrCreateSigningSecret(db: DatabaseSync, generateCandidate?: () => Buffer): Buffer;
+/**
+ * Persistent {@link BlobStore} backed by `node:sqlite` — no native
+ * dependency, same rationale as `SqliteTaskStore` (`sqlite-support.ts`).
+ * Metadata AND content bytes both live in the same database file (a `data
+ * BLOB` column), so a fresh instance pointed at the same file recovers
+ * everything: declared blobs, upload state, and the bytes themselves,
+ * byte-for-byte.
+ *
+ * Presigned URLs use the same HMAC-signed-query-param scheme as
+ * `LocalDiskBlobStore` (`/byok/blobs/:id/content?sig=...&exp=...`, verified
+ * generically by `http.ts` via {@link verifySignedUrl} regardless of which
+ * `BlobStore` is plugged in) — the only difference is where the signing
+ * secret comes from; see {@link SqliteBlobStoreOptions.signingKey}.
+ *
+ * Requires Node.js 22.5+ (`node:sqlite`'s minimum); constructing this on an
+ * unsupported runtime throws `SqliteUnavailableError` (`sqlite-support.ts`).
+ */
+export declare class SqliteBlobStore implements BlobStore {
+    private readonly db;
+    private readonly urlTtlMs;
+    private readonly secret;
+    private readonly insertBlobStmt;
+    private readonly selectBlobStmt;
+    private readonly selectUploadedStmt;
+    private readonly writeContentStmt;
+    constructor(opts: SqliteBlobStoreOptions);
+    createUpload(input: CreateUploadInput, requestedBlobId?: string): Promise<{
+        blobId: string;
+        uploadUrl: string;
+    }>;
+    getDownloadUrl(blobId: string): Promise<string | undefined>;
+    exists(blobId: string): Promise<boolean>;
+    verifySignedUrl(blobId: string, action: 'put' | 'get', sig: string, exp: number): boolean;
+    writeContent(blobId: string, data: Buffer): Promise<WriteContentResult>;
+    readContent(blobId: string): Promise<ReadContentResult | undefined>;
+    /** Close the underlying database connection — see `SqliteTaskStore.close`'s doc comment; same rationale. */
+    close(): void;
+    private computeSig;
+    private signUrl;
+}

package/dist/sqlite-support.d.ts

@@ -0,0 +1,84 @@
+import type { DatabaseSync, DatabaseSyncOptions } from 'node:sqlite';
+/**
+ * Thrown when `node:sqlite` isn't available in the running Node.js binary.
+ * `node:sqlite` shipped in Node.js 22.5.0 (https://nodejs.org/api/sqlite.html)
+ * and remains marked experimental there (an `ExperimentalWarning` on stderr
+ * is expected and harmless — not an error). The SQLite-backed reference
+ * stores in this package (`SqliteTaskStore`, `SqliteBlobStore`) deliberately
+ * depend on nothing else — no `better-sqlite3` or other native module —
+ * because staying at zero native dependencies is required to keep
+ * `@byok-sdk/server` trivially packageable across platforms. The tradeoff is
+ * that these stores simply don't work below Node 22.5; this error says so
+ * clearly and up front, instead of letting a cryptic `Cannot find module
+ * 'node:sqlite'` surface from deep inside a query.
+ */
+export declare class SqliteUnavailableError extends Error {
+    constructor(cause: unknown);
+}
+/**
+ * Whether `nodeVersion` (a `major.minor.patch` string shaped like
+ * `process.versions.node`) is new enough to have `node:sqlite` at all.
+ * Exported only for this package's own tests to exercise the guard
+ * deterministically (this dev/CI machine is already on a qualifying Node,
+ * so the real "unavailable" path can't be triggered end-to-end here) — not
+ * re-exported from `index.ts`, so not part of the public package API.
+ * Unparsable input returns `true` (don't false-negative on a version string
+ * shape this hasn't seen before): `loadSqliteModule`'s own `require` call is
+ * the real, authoritative gate; this check only exists to turn the common
+ * case (a too-old Node) into a clear message instead of a cryptic one.
+ *
+ * Not a sufficient capability check on its own: `node:sqlite` shipped in
+ * Node 22.5.0 behind the `--experimental-sqlite` flag and only became usable
+ * unflagged in a later 22.x release (https://nodejs.org/api/sqlite.html), so
+ * a runtime that satisfies this version check can still fail to actually
+ * load the module. Use {@link isSqliteAvailable} when the question is "can I
+ * use `node:sqlite` right now", not "is the Node version new enough for it
+ * to exist at all".
+ */
+export declare function isSqliteCapableNodeVersion(nodeVersion: string): boolean;
+/**
+ * Whether `node:sqlite` can ACTUALLY be loaded right now — the authoritative
+ * capability check, in contrast to {@link isSqliteCapableNodeVersion}'s
+ * version-string heuristic. This is what this package's own test suite uses
+ * to decide whether to skip the SQLite-backed reference-store tests (rather
+ * than fail them), and what anything else should call before assuming a
+ * `SqliteTaskStore`/`SqliteBlobStore` can be constructed: it attempts the
+ * real `require('node:sqlite')` (via {@link loadSqliteModule}, memoized) and
+ * reports whether that succeeded, so it agrees with reality regardless of
+ * whether the current runtime is old, too-new-but-flagged, or fully capable.
+ */
+export declare function isSqliteAvailable(): boolean;
+/**
+ * Open (or create) a `node:sqlite` `DatabaseSync` at `path`, applying the
+ * pragmas both reference SQLite stores share: WAL journaling for a
+ * file-backed database (allows a reader and a writer to proceed without
+ * blocking each other, and is what makes "close instance A, open instance B
+ * on the same file" — the restart-safety story — reliable) and a busy
+ * timeout (see {@link DEFAULT_BUSY_TIMEOUT_MS}). WAL is skipped for
+ * `:memory:`, where it's meaningless. For a file-backed path whose parent
+ * directory doesn't exist yet, creates it (recursively) at
+ * {@link SECURE_DIR_MODE} — mirroring the client-side device store's
+ * convention of never leaving a credential directory at a permissive
+ * default mode. Throws {@link SqliteUnavailableError} if `node:sqlite`
+ * itself can't be loaded (Node <22.5, or a flagged intermediate 22.x — see
+ * {@link isSqliteAvailable}) — callers don't need their own guard for that;
+ * this is the single choke point.
+ */
+export declare function openSqliteDatabase(path: string, options?: DatabaseSyncOptions): DatabaseSync;
+/**
+ * Restrict `dbPath` and its WAL/SHM sibling files (`<path>-wal`,
+ * `<path>-shm` — created by SQLite itself once WAL mode is active and a
+ * write has happened) to owner-only read/write ({@link SECURE_FILE_MODE}).
+ * Both SQLite reference stores hold sensitive bytes on disk with no other
+ * access-control layer of their own — `SqliteBlobStore` an HMAC signing
+ * secret plus arbitrary uploaded blob content, `SqliteTaskStore` task
+ * instructions and device/session refs — so a real (non-`:memory:`)
+ * database file must not be left at whatever permissive mode the process'
+ * umask would otherwise give it.
+ *
+ * Call this AFTER the schema has been created against `dbPath` (so the
+ * WAL/SHM files, which SQLite creates lazily on first write, already exist)
+ * — a sibling file that doesn't exist yet is silently skipped rather than
+ * treated as an error. No-op for `:memory:`.
+ */
+export declare function secureSqliteFilePermissions(dbPath: string): void;

package/dist/sqlite-task-store.d.ts

@@ -0,0 +1,123 @@
+import { type TaskState } from '@byok-sdk/protocol';
+import type { DatabaseSync } from 'node:sqlite';
+import { type CreateTaskInput, type TaskRecord, type TaskStore } from './task-store';
+export interface SqliteTaskStoreOptions {
+    /**
+     * Database file path. Use `:memory:` to exercise the SQLite code path
+     * without a temp file (e.g. schema/query correctness tests) — but note
+     * that defeats the entire point of this store (restart-safety), since an
+     * in-memory SQLite database vanishes with the process exactly like
+     * `InMemoryTaskStore` does. Real persistence requires a real file path.
+     */
+    path: string;
+}
+/**
+ * S5 hardening: two processes (or two `SqliteTaskStore` instances in this
+ * one) can both construct against the same pre-existing file at close to the
+ * same instant, both see a given column missing via the `PRAGMA table_info`
+ * read below, and both attempt the same `ALTER TABLE ... ADD COLUMN` —
+ * SQLite allows only one to actually add it; the loser's `db.exec` throws
+ * `duplicate column name`. That failure means the OTHER writer already won —
+ * the column now genuinely exists, which is exactly the end state this
+ * function is trying to reach — so it's caught here, the column list is
+ * re-inspected fresh, and this function proceeds normally (no throw) once
+ * confirmed. Anything else (a real schema problem, a disk error, a
+ * `duplicate column name` for a DIFFERENT column than expected) is rethrown
+ * unchanged — this only swallows the exact race this is written for.
+ *
+ * Exported only for this package's own tests to exercise the race
+ * deterministically (mirrors `sqlite-support.ts`'s
+ * `isSqliteCapableNodeVersion` convention) — not re-exported from
+ * `index.ts`, so not part of the public package API.
+ */
+export declare function ensureAdditiveColumns(db: DatabaseSync): void;
+/**
+ * Persistent {@link TaskStore} backed by the Node.js built-in `node:sqlite`
+ * module — no native dependency (`sqlite-support.ts`'s doc comment explains
+ * why that's a hard requirement here). A fresh instance pointed at the same
+ * database file recovers every task's full RECORD (instruction, policy,
+ * device/session refs, result) exactly as `InMemoryTaskStore` would have
+ * held it in memory — this is the M3 "task records survive a process
+ * restart" story.
+ *
+ * Scope of that claim, precisely: this is RECORD persistence, not live
+ * active-task recovery. A fresh `ConnectionHub` (`hub.ts`) wired to a
+ * reopened store starts with empty runtimes/result-promises/event-queues/
+ * device-registry/outboxes — so a task that was `Running` at restart comes
+ * back as a `Running` *record* you can read and further `transition()`, not
+ * as a task with its device/runtime connection reattached that will go on
+ * to actually produce more events. Recovering/resuming an in-flight task's
+ * live connection is a larger feature and out of scope here.
+ *
+ * Every write goes through a compare-and-set `UPDATE ... WHERE task_id = ?
+ * AND state = ?` (the state {@link transition} just validated against), not
+ * an unconditional update: two connections racing on the same task (both
+ * reading e.g. `Running`, both independently validating a different target
+ * state) can't both commit, which would otherwise let the later write
+ * silently perform an illegal transition — including terminal -> terminal —
+ * that neither validation call would have allowed had it seen the other's
+ * write first. A lost compare-and-set re-reads the row and either
+ * re-validates the requested move against the state that actually won, or
+ * throws {@link IllegalTaskTransitionError} against it.
+ *
+ * Requires Node.js 22.5+ (`node:sqlite`'s minimum); constructing this on an
+ * older/unsupported runtime throws `SqliteUnavailableError`
+ * (`sqlite-support.ts`) with a clear message rather than a cryptic "Cannot
+ * find module" trace.
+ *
+ * Enforces the exact same `TASK_TRANSITIONS`/`canTransition` state machine
+ * as `InMemoryTaskStore`, via the same {@link IllegalTaskTransitionError}.
+ */
+export declare class SqliteTaskStore implements TaskStore {
+    private readonly db;
+    private readonly insertStmt;
+    private readonly updateStmt;
+    private readonly selectStmt;
+    private readonly selectAllStmt;
+    private readonly updatePendingApprovalIdStmt;
+    constructor(opts: SqliteTaskStoreOptions);
+    create(input: CreateTaskInput): TaskRecord;
+    get(taskId: string): TaskRecord | undefined;
+    list(): TaskRecord[];
+    /**
+     * Apply `taskId`'s state -> `to`, merging `patch` into the record. Throws
+     * {@link IllegalTaskTransitionError} if the move isn't legal per
+     * `TASK_TRANSITIONS`, and if the task doesn't exist at all — identical
+     * contract and error shapes to `InMemoryTaskStore.transition`.
+     *
+     * Implemented as a compare-and-set retry loop rather than a single
+     * read-validate-write, because two separate connections (two processes,
+     * or two `SqliteTaskStore` instances in this one) can both read the same
+     * current state and both validate a move against it before either writes.
+     * An unconditional `UPDATE` would let whichever commits last silently win
+     * — including an illegal terminal -> terminal transition neither
+     * validation call would have allowed with up-to-date information. Each
+     * iteration here reads the CURRENT state fresh, validates `to` against
+     * it, then writes with `WHERE state = <the state just validated>`
+     * (`updateStmt`). If zero rows changed, some other writer committed
+     * between this read and this write, so the loop re-reads and either
+     * re-validates `to` against whatever the state actually is now, or throws
+     * {@link IllegalTaskTransitionError} against it — the same outcome a
+     * caller would get if it happened to run a moment later.
+     */
+    transition(taskId: string, to: TaskState, patch?: Partial<Omit<TaskRecord, 'taskId' | 'state'>>): TaskRecord;
+    /**
+     * See {@link TaskStore.setPendingApprovalId}'s own doc comment for the
+     * full rationale, and `updatePendingApprovalIdStmt`'s own doc comment
+     * (constructor, above) for the S3 CAS-guard rationale. The guarded
+     * statement affecting 0 rows means `taskId` is no longer `AwaitApproval`
+     * (or vanished) as of the write — a legitimate no-op, not an error: this
+     * method never throws for a state mismatch (best-effort bookkeeping, same
+     * as its unconditional pre-S3 form). Returns a FRESH read in that case
+     * rather than the caller's now-stale pre-write snapshot, so a caller sees
+     * what's actually stored.
+     */
+    setPendingApprovalId(taskId: string, pendingApprovalId: string | undefined): TaskRecord | undefined;
+    /**
+     * Close the underlying database connection. Not part of the `TaskStore`
+     * interface (an in-memory store has nothing to close) — call this
+     * explicitly when a store instance is done, e.g. before opening a second
+     * instance against the same file, or on process shutdown.
+     */
+    close(): void;
+}

package/dist/task-store.d.ts

@@ -0,0 +1,125 @@
+import { type PermissionPolicy, type RuntimeId, type TaskState } from '@byok-sdk/protocol';
+import type { TaskSnapshot } from './types';
+/** Thrown by a {@link TaskStore}'s `transition` when `from -> to` is not in TASK_TRANSITIONS. Every implementation (in-memory, SQLite, or otherwise) must throw this rather than silently applying an invalid move. */
+export declare class IllegalTaskTransitionError extends Error {
+    readonly taskId: string;
+    readonly from: TaskState;
+    readonly to: TaskState;
+    constructor(taskId: string, from: TaskState, to: TaskState);
+}
+export interface CreateTaskInput {
+    taskId: string;
+    instruction: string;
+    runtime?: RuntimeId;
+    policy: PermissionPolicy;
+    deviceId?: string;
+    sessionRef?: string;
+}
+/** A task's full persisted state, as tracked by any {@link TaskStore} implementation. Same shape as {@link TaskSnapshot} — kept as its own (structurally identical) type so this storage-layer contract can evolve independently of the SDK-facing `TaskSnapshot` if a future need arises. */
+export interface TaskRecord extends TaskSnapshot {
+}
+/**
+ * Storage contract for task records — the M3 injection point, mirroring how
+ * {@link BlobStore} (`blob-store.ts`) is injectable: `createByokServer`
+ * (`index.ts`) accepts `opts.taskStore`, defaulting to {@link InMemoryTaskStore}
+ * so nothing breaks for an embedder that doesn't override it. `ConnectionHub`
+ * (`hub.ts`) is written against this interface only — it never references
+ * {@link InMemoryTaskStore} (or any other concrete implementation) directly —
+ * so a persistent implementation such as `sqlite-task-store.ts`'s
+ * `SqliteTaskStore` (M3) drops in with zero changes anywhere else.
+ *
+ * Every implementation MUST enforce the protocol's `TASK_TRANSITIONS` state
+ * machine (via `canTransition`) inside `transition`, throwing
+ * {@link IllegalTaskTransitionError} rather than silently applying an
+ * invalid move — this is part of the interface's contract, not just an
+ * `InMemoryTaskStore` implementation detail. `ConnectionHub`'s `applyOrFail`
+ * (`hub.ts`) relies on that exception type to decide "illegal transition ->
+ * force `Failed` if possible, else drop".
+ */
+export interface TaskStore {
+    /** Create a new task record in the `Offered` state. */
+    create(input: CreateTaskInput): TaskRecord;
+    /** Look up a task by id, or `undefined` if unknown. */
+    get(taskId: string): TaskRecord | undefined;
+    /** All known tasks. */
+    list(): TaskRecord[];
+    /**
+     * Apply `taskId`'s state -> `to`, merging `patch` into the record. Must
+     * throw {@link IllegalTaskTransitionError} if the move isn't legal per
+     * `TASK_TRANSITIONS`, and a plain `Error` (message: `` `unknown taskId:
+     * ${taskId}` ``) if the task doesn't exist at all —
+     * {@link InMemoryTaskStore.transition}'s existing message format, which
+     * some tests match on.
+     */
+    transition(taskId: string, to: TaskState, patch?: Partial<Omit<TaskRecord, 'taskId' | 'state'>>): TaskRecord;
+    /**
+     * M5 (approval targeting): update `taskId`'s `pendingApprovalId` WITHOUT a
+     * state transition. Needed because `AwaitApproval -> AwaitApproval` is
+     * deliberately not a legal `TASK_TRANSITIONS` edge (`@byok-sdk/protocol`'s
+     * `task-state.ts`) — self-transitions aren't part of the frozen wire state
+     * machine, so `transition` above cannot be used to update this field while
+     * the record STAYS in `AwaitApproval` — yet a re-sent/updated
+     * `task.await_approval` carrying a NEWER id while the record is ALREADY
+     * `AwaitApproval` must still be reflected (see `ConnectionHub.
+     * onAwaitApproval`, `hub.ts`). Every state-CHANGING write still goes
+     * through `transition`; this is the one narrow exception for a same-state
+     * field update. Returns `undefined` for an unknown `taskId` rather than
+     * throwing — this is a best-effort bookkeeping update, not a
+     * state-machine-enforced operation like `transition`.
+     *
+     * OPTIONAL: a `TaskStore` implementation predating M5 (a custom embedder
+     * store written against the pre-M5 interface) doesn't have this method at
+     * all — every call site in `hub.ts` guards its absence with `?.()`. A
+     * store that omits it simply never records a superseding
+     * `pendingApprovalId` on the same-state redelivery path (the first entry
+     * into `AwaitApproval` still records one via `transition`'s own patch,
+     * same as ever); an operator-supplied `opts.approvalId` on
+     * `approveTask`/`rejectTask` then has nothing recorded to compare against
+     * and proceeds untargeted, exactly like a legacy daemon that never
+     * reported an id at all — a graceful degrade, not a broken embedder.
+     * Every CURRENT implementation in this package ({@link InMemoryTaskStore},
+     * `sqlite-task-store.ts`'s `SqliteTaskStore`) still implements it as a
+     * required, always-present method — optionality is a concession to
+     * EXISTING third-party implementations of this interface, not a hint that
+     * a new one should skip it.
+     */
+    setPendingApprovalId?(taskId: string, pendingApprovalId: string | undefined): TaskRecord | undefined;
+}
+/**
+ * Plain, framework-agnostic in-memory {@link TaskStore}. Enforces the
+ * protocol's `TASK_TRANSITIONS` state machine via `canTransition` — every
+ * state change must go through {@link transition}, which throws
+ * {@link IllegalTaskTransitionError} rather than silently applying an invalid
+ * move. Callers (the connection hub) decide what to do with that error; see
+ * `hub.ts`'s `applyOrFail` for the "illegal transition -> force Failed if
+ * possible, else drop" policy.
+ *
+ * M0/M1/M2 reference default — loses all state on process restart. See
+ * `sqlite-task-store.ts`'s `SqliteTaskStore` (M3) for a persistent
+ * alternative implementing the same {@link TaskStore} contract.
+ */
+export declare class InMemoryTaskStore implements TaskStore {
+    private readonly tasks;
+    create(input: CreateTaskInput): TaskRecord;
+    get(taskId: string): TaskRecord | undefined;
+    list(): TaskRecord[];
+    /**
+     * Apply `taskId`'s state -> `to`, merging `patch` into the record. Throws
+     * {@link IllegalTaskTransitionError} if the move isn't legal per
+     * `TASK_TRANSITIONS`, and if the task doesn't exist at all.
+     */
+    transition(taskId: string, to: TaskState, patch?: Partial<Omit<TaskRecord, 'taskId' | 'state'>>): TaskRecord;
+    /**
+     * See {@link TaskStore.setPendingApprovalId}'s own doc comment for the
+     * full rationale. State-guarded (S3 hardening): a write only applies while
+     * `taskId` is still `AwaitApproval` — mirrors `SqliteTaskStore`'s own `AND
+     * state = 'AwaitApproval'` CAS predicate (`sqlite-task-store.ts`) for
+     * symmetry between the two reference implementations, guarding against a
+     * laggard caller resurrecting a pending id after the task already left
+     * `AwaitApproval` (e.g. a queued/delayed `task.await_approval` processed
+     * after a real `approveTask`/`rejectTask` already transitioned it
+     * elsewhere). A non-matching call is a no-op: returns the record exactly
+     * as it currently stands, not the caller's requested (rejected) value.
+     */
+    setPendingApprovalId(taskId: string, pendingApprovalId: string | undefined): TaskRecord | undefined;
+}