@byok-sdk/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ancienttwo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# @byok-sdk/server
+
+The self-hosted SaaS-side reference coordinator: pairing, authenticated device
+HTTP/WebSocket/long-poll transport, task leasing, approvals, and in-memory
+stores over the frozen v1 protocol.
+
+Use `@byok-sdk/cloud` plus `@byok-sdk/cloud-postgres` for the durable hosted
+composition.
+
+MIT licensed. Node.js 20 or newer.

package/dist/auth.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Auth v2 (docs/protocol.md §6): device identity (Ed25519 keypair, public
+ * half registered at pairing time), single-use nonce challenge/response for
+ * token renewal, and JWT access tokens. Kept separate from `pairing.ts`
+ * (which now only owns the one-time pairing-code lifecycle) because these
+ * concerns span every authed surface (WSS upgrade, blob routes, events
+ * long-poll), not just `POST /byok/pair`.
+ */
+/** Access tokens are JWTs with a ~1h lifetime (docs/protocol.md §6.1/§6.2). */
+export declare const ACCESS_TOKEN_TTL_SECONDS: number;
+/**
+ * S1 (GAP-004): the domain-separation prefix a device signs along with a
+ * challenge nonce. The device key is a long-lived identity key that later
+ * planes (S6 device proof) will also sign structured messages with; without a
+ * domain tag, a signature produced for one purpose is a valid signature for
+ * another, and an attacker who can get a device to sign anything shaped like
+ * a nonce holds a token-renewal credential.
+ *
+ * The client signs the same literal (`packages/client/src/daemon/device-keys.ts`).
+ * There is deliberately no dual mode: a raw, unprefixed nonce signature is
+ * simply invalid here, with no flag, fallback, or grace window that would
+ * make the old encoding acceptable again. Because the four packages have no
+ * published compatibility contract yet, the recovery path for a device on
+ * the old encoding is a re-pair, not a server-side shim.
+ */
+export declare const NONCE_SIGNING_DOMAIN = "byok-nonce-v1\n";
+/**
+ * S1: server-local tenant identifier. A plain string alias for now — S2 moves
+ * the branded/shared form into `@byok-sdk/core`, which does not exist yet, and
+ * depending on an unbuilt package would be worse than naming the concept
+ * here. What matters at this stage is that every identity-carrying shape in
+ * this package names the tenant explicitly and required, never optional.
+ */
+export type TenantId = string;
+/**
+ * S1: an access token binds a device to the tenant AND product its row was
+ * paired into. All three are required — there is no tenant-less token shape.
+ * These are LOOKUP KEYS, not authority: `authenticateBearer` resolves them
+ * against the device registry and answers with the ROW's identity (see
+ * {@link AuthenticatedDevice}).
+ */
+export interface AccessTokenClaims {
+    deviceId: string;
+    tenantId: TenantId;
+    productId: string;
+}
+export interface TokenSigner {
+    sign(claims: AccessTokenClaims, expiresInSeconds: number): Promise<string>;
+    /** Returns the claims for a valid, unexpired token, or `undefined` if invalid/expired/malformed. */
+    verify(token: string): Promise<AccessTokenClaims | undefined>;
+}
+/** Default {@link TokenSigner}: HS256 over a random 32-byte secret held in memory for this process's lifetime. */
+export declare function createHmacTokenSigner(secret?: Uint8Array): TokenSigner;
+/** Mint a fresh access token + its ISO-8601 expiry, per {@link ACCESS_TOKEN_TTL_SECONDS}. */
+export declare function mintAccessToken(signer: TokenSigner, claims: AccessTokenClaims): Promise<{
+    accessToken: string;
+    expiresAt: string;
+}>;
+export interface DeviceRecord {
+    /** S1: the tenant this device was paired into. Comes from the pairing-code claims and is never client-supplied. */
+    tenantId: TenantId;
+    /** S1: the product this device was paired into — checked against `conn.hello.productId` and against every token's claims. */
+    productId: string;
+    deviceId: string;
+    deviceName: string;
+    /** Ed25519 public key, base64url-encoded (JWK `x` form — see {@link verifyEd25519Signature}). */
+    devicePublicKey: string;
+    revoked: boolean;
+}
+/** Everything `POST /byok/pair` knows at registration time; `revoked` is the registry's own to set. */
+export type DeviceRegistration = Omit<DeviceRecord, 'revoked'>;
+export declare class DeviceRegistry {
+    /** Keyed by {@link DeviceRegistry.key} — `(tenantId, deviceId)`. */
+    private readonly devices;
+    /**
+     * Secondary index over the SAME record objects, for the two pre-tenant
+     * endpoints only (see {@link resolveByDeviceId}). Holding the same object
+     * reference means a revocation applied through the composite key is
+     * immediately visible here too — there is no second copy to keep in sync.
+     */
+    private readonly byDeviceId;
+    private static key;
+    /**
+     * Write a device row. Every identity field is required by
+     * {@link DeviceRegistration}, so a row with no tenant cannot be constructed
+     * — which is the whole point of S1.
+     */
+    register(device: DeviceRegistration): void;
+    /** The row `tenantId` owns under `deviceId`, or `undefined` — including when the device exists under a DIFFERENT tenant. */
+    get(tenantId: TenantId, deviceId: string): DeviceRecord | undefined;
+    /**
+     * Revoke a device (public API via `createByokServer(...).devices.revoke`).
+     * Its next `/byok/challenge`, `/byok/token`, WSS connect, or authed HTTP
+     * call gets a 401; the daemon's only recourse is to re-run `/byok/pair`
+     * (docs/protocol.md §6.3). A tenant can only revoke its own devices: a
+     * (tenantId, deviceId) pair it does not own resolves to nothing and this is
+     * a no-op.
+     */
+    revoke(tenantId: TenantId, deviceId: string): void;
+    /** Every known device row, across tenants — the in-process read model behind `ByokServer.machines.list()`. */
+    list(): DeviceRecord[];
+    /**
+     * Resolve a device by its globally-unique id alone, WITHOUT a tenant in
+     * scope. Exists for exactly two callers — `POST /byok/challenge` and
+     * `POST /byok/token` — because those two carry no tenant at all: their
+     * request DTOs are the pinned wire contract (docs/protocol.md §6.2), the
+     * device authenticates by key possession, and the row itself is what tells
+     * the server which tenant to mint the next token for. Everything with a
+     * token (and therefore a tenant) in scope goes through {@link get}.
+     *
+     * Deliberately NOT re-exported from this package's entry point (`index.ts`
+     * exports no naked-lookup surface at all), so no embedder can turn it into
+     * a cross-tenant device oracle: the only reachable public device surface is
+     * tenant-first.
+     */
+    resolveByDeviceId(deviceId: string): DeviceRecord | undefined;
+}
+export declare class NonceStore {
+    private readonly nonces;
+    /** Number of nonce records currently held (post-sweep). Exposed for tests only. */
+    get size(): number;
+    /**
+     * Drop every used or expired record. A long-lived server never calls this
+     * on a timer, so `issue()` sweeps inline — a full-Map scan is fine at
+     * reference-impl scale (single-digit nonces per device, ~5min TTL).
+     */
+    private sweep;
+    issue(deviceId: string): string;
+    /** `true` iff `nonce` exists, belongs to `deviceId`, is unexpired, and hasn't been consumed yet. Does not mutate. */
+    validate(deviceId: string, nonce: string): boolean;
+    /** Mark `nonce` consumed so a replay of the same (deviceId, nonce, signature) is rejected. */
+    markUsed(nonce: string): void;
+}
+/**
+ * The ONLY nonce-signature check on this server (§6.2): the signed message is
+ * {@link NONCE_SIGNING_DOMAIN} followed by the nonce. Applying the domain here
+ * rather than at the call site is the point — there is one place that decides
+ * what a device signature over a nonce means, so no route can be written that
+ * accepts the undomained form.
+ */
+export declare function verifyNonceSignature(devicePublicKey: string, nonce: string, signature: string): boolean;
+export declare function extractBearerToken(header: string | undefined): string | undefined;
+export interface AuthDeps {
+    tokenSigner: TokenSigner;
+    devices: DeviceRegistry;
+}
+/**
+ * S1: the authenticated principal every authed surface works with. Built from
+ * the DEVICE ROW, never from the token payload — the token's claims are only
+ * the keys used to find that row (see {@link authenticateBearer}). A caller
+ * holding one of these is holding identity the registry vouched for.
+ */
+export interface AuthenticatedDevice {
+    deviceId: string;
+    tenantId: TenantId;
+    productId: string;
+}
+/**
+ * Resolve an `Authorization: Bearer <jwt>` header to an {@link AuthenticatedDevice},
+ * or `undefined` — the single check every authed HTTP route and the WSS
+ * upgrade share.
+ *
+ * S1 shape: the token's `(tenantId, deviceId)` are LOOKUP KEYS into the
+ * registry, and the row that comes back is the authority. A token for a
+ * device that no longer exists, one whose tenant does not own that device,
+ * one whose product disagrees with the row, and one for a revoked device all
+ * fail identically here and are indistinguishable to the caller — there is
+ * deliberately no "which of those was it" signal to hand back, so no route
+ * can turn a 401 into a cross-tenant existence oracle.
+ */
+export declare function authenticateBearer(header: string | undefined, deps: AuthDeps): Promise<AuthenticatedDevice | undefined>;

package/dist/blob-store.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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
+ * directly (no bearer auth on that URL — the HMAC signature + expiry *is*
+ * the auth); `GET /byok/blobs/:id/url` mints a presigned download URL the
+ * same way. `BlobRef` itself (`@byok-sdk/protocol`'s `blob.ts`) is unchanged;
+ * this module is what produces the URLs a `BlobRef` points at.
+ *
+ * `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.
+ */
+export interface CreateUploadInput {
+    size: number;
+    contentType: string;
+    /** Content-addressed hash the server verifies the uploaded bytes against (§7). Reference impl assumes hex-encoded SHA-256. */
+    contentHash: string;
+}
+export type WriteContentResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface ReadContentResult {
+    data: Buffer;
+    contentType: string;
+}
+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<{
+        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>;
+    /** Whether `blobId` is known *and* has finished uploading. */
+    exists(blobId: string): Promise<boolean>;
+    /** 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. */
+    writeContent(blobId: string, data: Buffer): Promise<WriteContentResult>;
+    /** Read back previously-uploaded bytes, or `undefined` if unknown/not yet uploaded. */
+    readContent(blobId: string): Promise<ReadContentResult | undefined>;
+}
+export interface LocalDiskBlobStoreOptions {
+    /** Directory blob content is written under. Defaults to a fresh OS temp dir. */
+    directory?: string;
+    /** 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. */
+export declare class LocalDiskBlobStore implements BlobStore {
+    private readonly secret;
+    private readonly directory;
+    private readonly urlTtlMs;
+    private readonly blobs;
+    private readonly ready;
+    constructor(opts?: LocalDiskBlobStoreOptions);
+    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>;
+    private pathFor;
+    private computeSig;
+    private signUrl;
+}

package/dist/event-queue.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A tiny append-only, multi-reader async queue. `push` never blocks; `close`
+ * marks the queue done. `subscribe()` returns a fresh async iterator that
+ * always replays from the beginning of the buffer, so a consumer that calls
+ * `events()` at any point still "sees everything" for that task's lifetime.
+ *
+ * Framework-agnostic on purpose (no Node/WS/Hono types here) so it can be
+ * unit-tested and reused regardless of transport.
+ */
+export declare class AsyncEventQueue<T> {
+    private readonly buffer;
+    private closed;
+    private waiters;
+    push(value: T): void;
+    close(): void;
+    private wake;
+    private waitForMore;
+    /** Async-iterate the buffer from index 0, waiting for new pushes until closed. */
+    subscribe(): AsyncIterable<T>;
+}

package/dist/heartbeat.d.ts

@@ -0,0 +1,30 @@
+/**
+ * WS-native ping/pong liveness check (pinned here per the M1-2 task brief,
+ * not in docs/protocol.md — this is a server implementation detail, not a
+ * wire message). The server pings every `intervalMs` (default 30s);
+ * `ws`'s WebSocket automatically replies to a protocol-level ping with a
+ * protocol-level pong on any spec-compliant peer, so a healthy connection
+ * just keeps ticking. After `maxMissedPongs` (default 2) consecutive
+ * unanswered pings, the connection is terminated.
+ *
+ * Deliberately decoupled from the real `ws` package's `WebSocket` type (only
+ * the four methods below are used) so the scheduling logic can be unit
+ * tested with a plain stub + fake timers instead of a real socket — a real
+ * peer auto-pongs, so there's no way to exercise "missed pong" through an
+ * actual WS round-trip in a test.
+ */
+export interface HeartbeatSocket {
+    ping(): void;
+    terminate(): void;
+    on(event: 'pong', listener: () => void): unknown;
+    off(event: 'pong', listener: () => void): unknown;
+}
+export interface HeartbeatOptions {
+    intervalMs?: number;
+    maxMissedPongs?: number;
+}
+export interface Heartbeat {
+    /** Stop the ping timer and detach the pong listener (e.g. on normal connection close). */
+    stop(): void;
+}
+export declare function startHeartbeat(ws: HeartbeatSocket, opts?: HeartbeatOptions): Heartbeat;

package/dist/http.d.ts

@@ -0,0 +1,24 @@
+import { Hono } from 'hono';
+import { type AuthDeps, type NonceStore } from './auth';
+import { type BlobStore } from './blob-store';
+import type { ConnectionHub } from './hub';
+import { type PairingManager } from './pairing';
+export interface HttpDeps extends AuthDeps {
+    pairing: PairingManager;
+    nonces: NonceStore;
+    blobStore: BlobStore;
+    hub: ConnectionHub;
+    /** Per-product blob size ceiling in bytes (§7). */
+    maxBlobSizeBytes: number;
+    /** How long `GET /byok/events` holds an empty poll open before returning, ms (§8). */
+    longPollHoldMs: number;
+    /** M4 Phase 4 (part B.2): opt-in `GET /healthz` liveness route — see `CreateByokServerOptions.healthzRoute`'s doc comment (`types.ts`) for the full contract. Default `false` (no route mounted). */
+    healthzRoute?: boolean;
+}
+/**
+ * The HTTP half of the pinned wire contract: pairing, token renewal, blob
+ * flows, and the long-poll events fallback (docs/protocol.md §6-§8). WS
+ * upgrade handling lives in `ws-server.ts` (raw Node `http.Server` upgrade,
+ * not routable through Hono's fetch handler).
+ */
+export declare function buildHonoApp(deps: HttpDeps): Hono;