@byok-sdk/server 0.12.0 → 0.14.0

package/dist/auth.d.ts

@@ -1,218 +0,0 @@
-/**
- * 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 literal lives in `@byok-sdk/core` (`src/pairing.ts`) and the client signs
- * the same binding (`packages/client/src/daemon/device-keys.ts`) — it used to
- * be three copies, each commented as byte-identical to the other two, which is
- * an agreement that holds only until someone edits one. Re-exported here so
- * this module's public surface is unchanged.
- *
- * 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 { NONCE_SIGNING_DOMAIN } from '@byok-sdk/core';
-/**
- * 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;
-}
-/**
- * Everything `POST /byok/pair` knows at registration time — which is the whole
- * row. Revocation DELETES the registration (§6.3), so there is no lifecycle
- * flag for the registry to own on top of what pairing supplies.
- */
-export type DeviceRegistration = DeviceRecord;
-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}). It holds the same record
-     * objects rather than copies, and {@link revoke} removes the entry here in
-     * the same call that removes the composite-key one — a stale entry left
-     * behind would be a deleted device that can still get a token.
-     */
-    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`).
-     * Revocation DELETES the registration (docs/protocol.md §6.3): afterwards
-     * the device id is byte-for-byte one that was never registered — absent
-     * from {@link list}, resolving to nothing on the pre-tenant
-     * `/byok/challenge` and `/byok/token` paths, and a 401 on every authed
-     * surface. The daemon's only recourse is to re-run `/byok/pair`.
-     *
-     * There is deliberately no retained `revoked` row: a flag every read path
-     * has to remember to exclude is a second way to represent "not a
-     * principal", and the first read path that forgets it is a live credential.
-     *
-     * A tenant can only revoke its own devices: a (tenantId, deviceId) pair it
-     * does not own resolves to nothing, deletes nothing, and is silently
-     * indistinguishable from revoking one that never existed.
-     *
-     * Returns whether a row was actually removed — the composition in
-     * `index.ts` uses it to delete the device-scoped state that only existed to
-     * serve that row (nonces, presence, dedup), so a no-op revoke touches
-     * nothing at all.
-     */
-    revoke(tenantId: TenantId, deviceId: string): boolean;
-    /** 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;
-    /**
-     * Drop every nonce outstanding for `deviceId` — called when the device's
-     * registration is deleted (§6.3 revocation). An unspent challenge is state
-     * that only existed to serve a row the directory can no longer name, so it
-     * goes with the row rather than sitting until its TTL sweeps it.
-     */
-    deleteForDevice(deviceId: string): void;
-    /** 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
- * core's `nonceSigningBytes` — the 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;
-    /**
-     * The product THIS server instance serves (`createByokServer`'s
-     * `productId`). Part of authentication, not of routing: a device row paired
-     * into another product is not a principal here at all — see
-     * {@link authenticateBearer}.
-     */
-    productId: string;
-}
-/**
- * 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 whose row belongs to a
- * different product than this instance serves all fail identically here and
- * are indistinguishable to the caller — a revoked device is exactly the first
- * of those, since revocation deleted its row (§6.3) — there
- * is deliberately no "which of those was it" signal to hand back, so no route
- * can turn a 401 into a cross-tenant (or cross-product) existence oracle.
- *
- * The last two checks are different facts and both are needed. Row vs claims
- * says "the token belongs to this row"; row vs instance says "this row
- * belongs to the product this server serves" — a single server can mint
- * pairing codes for any product (`createPairingCode` takes the claims per
- * code), so a row from another product is a real row holding a real token
- * and is still not a principal here. `conn.hello`'s own product checks
- * (`ws-server.ts`) validate the client's ANNOUNCEMENT, which is a third fact
- * and stays where it is.
- */
-export declare function authenticateBearer(header: string | undefined, deps: AuthDeps): Promise<AuthenticatedDevice | undefined>;

package/dist/blob-store.d.ts

@@ -1,89 +0,0 @@
-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
- * 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, 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;
-    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;
-}
-/** 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(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(tenantId: TenantId, blobId: string): Promise<string | undefined>;
-    /** Whether `blobId` is known *and* has finished uploading. */
-    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. */
-    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}: persisted metadata/content and HMAC-signed expiring URLs. */
-export declare class LocalDiskBlobStore implements BlobStore {
-    private secret;
-    private readonly directory;
-    private readonly metadataPath;
-    private readonly urlTtlMs;
-    private readonly blobs;
-    private readonly ready;
-    private metadataWriteTail;
-    constructor(opts?: LocalDiskBlobStoreOptions);
-    createUpload(tenantId: TenantId, input: CreateUploadInput, requestedBlobId?: string): Promise<{
-        blobId: string;
-        uploadUrl: string;
-    }>;
-    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/heartbeat.d.ts

@@ -1,30 +0,0 @@
-/**
- * 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

@@ -1,24 +0,0 @@
-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;