@zap-proto/web 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @zap-proto/web — browser-frontend RPC over ZAP.
+ *
+ * A drop-in tRPC replacement that speaks native ZAP envelopes over WebSocket
+ * binary frames instead of JSON-over-HTTP. Layered on @zap-proto/zap (the wire
+ * runtime). Service shape comes from .zap schemas via `zapgen --target=ts`, not
+ * a Zod/procedure DSL. Binary only — no JSON fallback, no Cap'n Proto.
+ *
+ *   - serve(httpServer, opts)   — Node: attach a ZAP RPC endpoint to http.Server.
+ *   - connect(url, opts)        — browser/Node: open a typed RPC connection.
+ *   - {node,browser}WsTransport — isomorphic WS transport factories.
+ *   - MintCap                   — the bearer→ctx auth slot at the upgrade.
+ */
+export { serve } from "./server.js";
+export type { ServeOptions, ServeHandle, RootCap } from "./server.js";
+export { connect } from "./client.js";
+export type { ConnectOptions, Connection } from "./client.js";
+export { nodeWsTransport, browserWsTransport, WS_CLOSE_UNSUPPORTED, } from "./transport.js";
+export type { WsTransport } from "./transport.js";
+export { Conn } from "./conn.js";
+export type { CallHandler, CallOptions } from "./conn.js";
+export type { MintCap } from "./auth.js";
+export { WebRpcError, ZapParseError } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE1D,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+/**
+ * @zap-proto/web — browser-frontend RPC over ZAP.
+ *
+ * A drop-in tRPC replacement that speaks native ZAP envelopes over WebSocket
+ * binary frames instead of JSON-over-HTTP. Layered on @zap-proto/zap (the wire
+ * runtime). Service shape comes from .zap schemas via `zapgen --target=ts`, not
+ * a Zod/procedure DSL. Binary only — no JSON fallback, no Cap'n Proto.
+ *
+ *   - serve(httpServer, opts)   — Node: attach a ZAP RPC endpoint to http.Server.
+ *   - connect(url, opts)        — browser/Node: open a typed RPC connection.
+ *   - {node,browser}WsTransport — isomorphic WS transport factories.
+ *   - MintCap                   — the bearer→ctx auth slot at the upgrade.
+ */
+export { serve } from "./server.js";
+export { connect } from "./client.js";
+export { nodeWsTransport, browserWsTransport, WS_CLOSE_UNSUPPORTED, } from "./transport.js";
+export { Conn } from "./conn.js";
+export { WebRpcError, ZapParseError } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,4CAA4C;AAE5C;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAKjC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,35 @@
+import type { Server as HttpServer } from "node:http";
+import type { CallHandler } from "./conn.js";
+import type { MintCap } from "./auth.js";
+/**
+ * rootCap produces the per-connection dispatch root for a minted ctx.
+ *
+ * On the real @zap-proto/zap foundation a "service" is a dispatcher over decoded
+ * Calls (method ordinal + payload), not a Cap'n Proto Server object — so the
+ * bootstrap capability is modelled here as a {@link CallHandler}. Generated
+ * zapgen bindings give you the typed param/result views to decode the payload
+ * and encode the response body inside that handler.
+ */
+export type RootCap<Ctx> = (ctx: Ctx) => CallHandler;
+/** Options for {@link serve}. */
+export interface ServeOptions<Ctx> {
+    /** Upgrade path this endpoint binds to (default "/zap"). */
+    path?: string;
+    /** Bearer→ctx boundary; return null to reject the upgrade with HTTP 401. */
+    mintCap: MintCap<Ctx>;
+    /** Produce the bootstrap dispatch handler for the minted ctx. */
+    rootCap: RootCap<Ctx>;
+    /** Optional sink for connection/dispatch errors. */
+    onError?: (err: unknown) => void;
+}
+/** A live ZAP-over-WebSocket endpoint attached to an http.Server. */
+export interface ServeHandle {
+    /** Close the endpoint and every live connection. */
+    close(): Promise<void>;
+}
+/**
+ * Attach a ZAP RPC endpoint to `httpServer`. Returns a handle whose close()
+ * tears down the WebSocket server and all open connections.
+ */
+export declare function serve<Ctx>(httpServer: HttpServer, opts: ServeOptions<Ctx>): ServeHandle;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAmB,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,WAAW,CAAC;AAErD,iCAAiC;AACjC,MAAM,WAAW,YAAY,CAAC,GAAG;IAC/B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,oDAAoD;IACpD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,GAAG,EACvB,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,GACtB,WAAW,CAmEb"}

package/dist/server.js

@@ -0,0 +1,101 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+/**
+ * server.ts — serve(httpServer, opts): attach a ZAP-over-WebSocket RPC endpoint
+ * to an existing Node http.Server.
+ *
+ * Sharing one http.Server is the integration seam: Next.js's
+ * `app.getRequestHandler()` and a Remix Node server both run on a plain
+ * http.Server, so a single `serve(server, ...)` line adds ZAP RPC alongside the
+ * app without a second port. (Same shape as the WebSocket attachments in
+ * hanzo/platform's app/platform/server/server.ts.)
+ *
+ * Auth runs at the upgrade boundary: mintCap(req) is awaited BEFORE the
+ * handshake completes. A null mint writes HTTP 401 and destroys the socket — no
+ * WebSocket is ever opened for an unauthorized request. A non-null mint becomes
+ * the per-connection `ctx`, and rootCap(ctx) yields the CallHandler that
+ * dispatches every decoded ZAP Call on that connection.
+ *
+ * `ws` is a peer dependency (server side only); we import it lazily so the
+ * browser bundle never pulls it in.
+ */
+import { createRequire } from "node:module";
+import { Conn } from "./conn.js";
+import { nodeWsTransport } from "./transport.js";
+/**
+ * Attach a ZAP RPC endpoint to `httpServer`. Returns a handle whose close()
+ * tears down the WebSocket server and all open connections.
+ */
+export function serve(httpServer, opts) {
+    const path = opts.path ?? "/zap";
+    const onError = opts.onError ?? (() => { });
+    // Lazy require so browser bundles never resolve `ws`. createRequire keeps
+    // this ESM-safe (no top-level `require`) and server-only (node:module never
+    // ends up in a browser bundle, since serve() is the Node entry).
+    const req = createRequire(import.meta.url);
+    const { WebSocketServer } = req("ws");
+    const wss = new WebSocketServer({ noServer: true });
+    const conns = new Set();
+    const onUpgrade = (req, socket, head) => {
+        let url;
+        try {
+            url = new URL(req.url ?? "/", "http://localhost");
+        }
+        catch {
+            return; // not ours; let other upgrade listeners handle it.
+        }
+        if (url.pathname !== path)
+            return; // path mismatch — not our endpoint.
+        void (async () => {
+            let ctx;
+            try {
+                ctx = await opts.mintCap(req);
+            }
+            catch (err) {
+                onError(err);
+                reject(socket, 500, "Internal Server Error");
+                return;
+            }
+            if (ctx === null) {
+                reject(socket, 401, "Unauthorized");
+                return;
+            }
+            const minted = ctx;
+            wss.handleUpgrade(req, socket, head, (ws) => {
+                const transport = nodeWsTransport(ws);
+                let handler;
+                try {
+                    handler = opts.rootCap(minted);
+                }
+                catch (err) {
+                    onError(err);
+                    transport.close(1011, "rootCap failed");
+                    return;
+                }
+                const conn = new Conn(transport, { handler });
+                conns.add(conn);
+                transport.onClose(() => conns.delete(conn));
+                ws.on("error", onError);
+            });
+        })();
+    };
+    httpServer.on("upgrade", onUpgrade);
+    return {
+        async close() {
+            httpServer.removeListener("upgrade", onUpgrade);
+            for (const conn of conns)
+                conn.close(1001, "server shutting down");
+            conns.clear();
+            await new Promise((resolve) => wss.close(() => resolve()));
+        },
+    };
+}
+/** Write a bare HTTP error response on the raw upgrade socket and destroy it. */
+function reject(socket, code, text) {
+    socket.write(`HTTP/1.1 ${code} ${text}\r\n` +
+        "Connection: close\r\n" +
+        "Content-Length: 0\r\n" +
+        "\r\n");
+    socket.destroy();
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -0,0 +1,46 @@
+/**
+ * transport.ts — an isomorphic WebSocket transport for ZAP RPC frames.
+ *
+ * The foundation runtime (@zap-proto/zap) frames a call as a single ZAP envelope
+ * (envelope.ts buildRequest / buildResponse). Over TCP, @zap-proto/zap's ZapClient
+ * length-prefixes each envelope to recover message boundaries. WebSocket binary
+ * frames already give us message boundaries for free, so the framing here is
+ * one ZAP envelope = one WS binary message — no extra length prefix.
+ *
+ * A single internal impl (makeWsTransport) feature-detects whether it is given
+ * the `ws` package WebSocket (Node, post-upgrade) or the browser's native
+ * WebSocket, and normalises both to the same {@link WsTransport} shape. Bytes
+ * in arrive as ArrayBuffer or Uint8Array (or, on Node `ws`, a Buffer) and are
+ * normalised to Uint8Array; bytes out are written as Uint8Array.
+ *
+ * Cap'n Proto-style text frames are a protocol violation: ZAP is binary-only.
+ * A received text frame closes the connection with WebSocket close code 1003
+ * (Unsupported Data).
+ */
+/** WebSocket close code for a non-binary (text) frame — Unsupported Data. */
+export declare const WS_CLOSE_UNSUPPORTED = 1003;
+/**
+ * WsTransport is the byte pipe a ZAP RPC connection rides on. It is duplex and
+ * message-oriented: every {@link send} ships exactly one ZAP envelope, and the
+ * {@link onMessage} callback fires once per inbound envelope.
+ */
+export interface WsTransport {
+    /** Ship one ZAP envelope as a single binary WebSocket message. */
+    send(bytes: Uint8Array): void;
+    /** Register the inbound-envelope handler. At most one is active. */
+    onMessage(handler: (bytes: Uint8Array) => void): void;
+    /** Register the close handler (fires once, on either side closing). */
+    onClose(handler: (code: number, reason: string) => void): void;
+    /** Close the underlying socket. */
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Wrap a Node `ws` package WebSocket (after the HTTP upgrade completes) as a
+ * {@link WsTransport}. Server side.
+ */
+export declare function nodeWsTransport(ws: unknown): WsTransport;
+/**
+ * Wrap the browser's native WebSocket as a {@link WsTransport}. Client side.
+ */
+export declare function browserWsTransport(ws: unknown): WsTransport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,oEAAoE;IACpE,SAAS,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;IACtD,uEAAuE;IACvE,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/D,mCAAmC;IACnC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAuHD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,GAAG,WAAW,CAExD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,OAAO,GAAG,WAAW,CAE3D"}

package/dist/transport.js

@@ -0,0 +1,140 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+/**
+ * transport.ts — an isomorphic WebSocket transport for ZAP RPC frames.
+ *
+ * The foundation runtime (@zap-proto/zap) frames a call as a single ZAP envelope
+ * (envelope.ts buildRequest / buildResponse). Over TCP, @zap-proto/zap's ZapClient
+ * length-prefixes each envelope to recover message boundaries. WebSocket binary
+ * frames already give us message boundaries for free, so the framing here is
+ * one ZAP envelope = one WS binary message — no extra length prefix.
+ *
+ * A single internal impl (makeWsTransport) feature-detects whether it is given
+ * the `ws` package WebSocket (Node, post-upgrade) or the browser's native
+ * WebSocket, and normalises both to the same {@link WsTransport} shape. Bytes
+ * in arrive as ArrayBuffer or Uint8Array (or, on Node `ws`, a Buffer) and are
+ * normalised to Uint8Array; bytes out are written as Uint8Array.
+ *
+ * Cap'n Proto-style text frames are a protocol violation: ZAP is binary-only.
+ * A received text frame closes the connection with WebSocket close code 1003
+ * (Unsupported Data).
+ */
+/** WebSocket close code for a non-binary (text) frame — Unsupported Data. */
+export const WS_CLOSE_UNSUPPORTED = 1003;
+/** Normalise any WS payload shape to a Uint8Array, or null for a text frame. */
+function toBytes(data) {
+    if (data instanceof Uint8Array)
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data)) {
+        const v = data;
+        return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+    }
+    // Node `ws` can hand back an array of Buffers when fragmented; coalesce.
+    if (Array.isArray(data)) {
+        const parts = data.map(toBytes);
+        if (parts.some((p) => p === null))
+            return null;
+        const total = parts.reduce((n, p) => n + p.byteLength, 0);
+        const out = new Uint8Array(total);
+        let off = 0;
+        for (const p of parts) {
+            out.set(p, off);
+            off += p.byteLength;
+        }
+        return out;
+    }
+    // A string payload is a text frame — a protocol violation for ZAP.
+    return null;
+}
+/**
+ * Wrap a socket (browser native WebSocket or Node `ws` WebSocket) as a
+ * {@link WsTransport}. Branches on whether the socket exposes the browser
+ * `addEventListener` API or the Node `ws` `on(...)` emitter API.
+ */
+function makeWsTransport(socket) {
+    // Ask for ArrayBuffer payloads where the API allows it (browser + `ws`),
+    // so toBytes has a fast path and never sees a Blob.
+    if ("binaryType" in socket)
+        socket.binaryType = "arraybuffer";
+    let onMsg = () => { };
+    let onClose = () => { };
+    let closed = false;
+    const handleData = (data) => {
+        const bytes = toBytes(data);
+        if (bytes === null) {
+            // Text frame (or unrecognised payload): reject per ZAP binary-only rule.
+            if (!closed) {
+                closed = true;
+                socket.close(WS_CLOSE_UNSUPPORTED, "zap: binary frames only");
+            }
+            return;
+        }
+        onMsg(bytes);
+    };
+    const handleClose = (code, reason) => {
+        if (closed)
+            return;
+        closed = true;
+        onClose(code, reason);
+    };
+    if (typeof socket.addEventListener === "function") {
+        // Browser native WebSocket.
+        socket.addEventListener("message", (ev) => handleData(ev.data));
+        socket.addEventListener("close", (ev) => {
+            const ce = ev;
+            handleClose(ce.code ?? 1006, ce.reason ?? "");
+        });
+        socket.addEventListener("error", () => handleClose(1006, "error"));
+    }
+    else if (typeof socket.on === "function") {
+        // Node `ws` WebSocket.
+        socket.on("message", (data, isBinary) => {
+            // `ws` passes (data, isBinary); a false isBinary is a text frame.
+            if (isBinary === false) {
+                handleData("text");
+                return;
+            }
+            handleData(data);
+        });
+        socket.on("close", (code, reason) => handleClose(typeof code === "number" ? code : 1006, reason ? String(reason) : ""));
+        socket.on("error", () => handleClose(1006, "error"));
+    }
+    else {
+        throw new TypeError("zap-web: unsupported WebSocket implementation");
+    }
+    return {
+        send(bytes) {
+            if (closed)
+                throw new Error("zap-web: transport closed");
+            socket.send(bytes);
+        },
+        onMessage(handler) {
+            onMsg = handler;
+        },
+        onClose(handler) {
+            onClose = handler;
+        },
+        close(code, reason) {
+            if (closed)
+                return;
+            closed = true;
+            socket.close(code, reason);
+        },
+    };
+}
+/**
+ * Wrap a Node `ws` package WebSocket (after the HTTP upgrade completes) as a
+ * {@link WsTransport}. Server side.
+ */
+export function nodeWsTransport(ws) {
+    return makeWsTransport(ws);
+}
+/**
+ * Wrap the browser's native WebSocket as a {@link WsTransport}. Client side.
+ */
+export function browserWsTransport(ws) {
+    return makeWsTransport(ws);
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@zap-proto/web",
+  "version": "0.1.0",
+  "description": "Browser frontend RPC over ZAP — a drop-in tRPC replacement for Next.js / Remix / SvelteKit. Native ZAP envelopes over WebSocket binary frames; layered on @zap-proto/zap. No Cap'n Proto, no JSON.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
+    },
+    "./transport": {
+      "types": "./dist/transport.d.ts",
+      "import": "./dist/transport.js",
+      "default": "./dist/transport.js"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "import": "./dist/auth.js",
+      "default": "./dist/auth.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@zap-proto/zap": "^1.1.0"
+  },
+  "peerDependencies": {
+    "ws": ">=8"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.12",
+    "eslint": "^9.0.0",
+    "prettier": "^3.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4",
+    "ws": "^8.18.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src test",
+    "format": "prettier --write src test"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,25 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+import type { IncomingMessage } from "node:http";
+
+/**
+ * MintCap is the boundary where a bearer (cookie, header, session) becomes a
+ * typed Capability that downstream RPC methods are authorized against.
+ *
+ * v0 ships the SLOT — apps supply their own fn. The canonical ML-DSA-65 signed
+ * Capability mint (per zap-spec/capabilities.zap — the 3408-byte signature
+ * footer, BLAKE3 object identity, attenuable/revocable authority) lands in a
+ * later version. Until then you can return any object: whatever non-null value
+ * you return becomes the `ctx` threaded into your `rootCap(ctx)` factory and
+ * carried on every {@link import("@zap-proto/zap").Call} as its capability buffer.
+ *
+ * Return `null` to reject the connection with HTTP 401 before the WebSocket
+ * upgrade completes — no socket is opened for an unauthorized request.
+ *
+ * @typeParam Ctx - the minted authority/context type your handlers consume.
+ * @param req - the raw HTTP upgrade request (read `req.headers.authorization`,
+ *              cookies, etc.).
+ * @returns the minted context, or `null` to reject with 401.
+ */
+export type MintCap<Ctx> = (req: IncomingMessage) => Promise<Ctx | null>;