@superbee/server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@superbee/server` — the wire-protocol v0 REFERENCE server
+ * (`docs/WIRE-PROTOCOL.md`): a Web-standard `fetch`-style router over the OKF
+ * engine, plus a thin `node:http` bootstrap. A pure consumer of
+ * `@superbee/core` — no parsing/link/OKF logic lives here (see `router.ts`
+ * module doc). Reference-not-production: no auth, loopback-only default bind.
+ *
+ * @packageDocumentation
+ */
+export { createRouter, createRouterForBackend } from "./legacy-router.js";
+export { WIRE_ENDPOINTS } from "./router.js";
+export { RequestBodyTooLargeError, serve, requestFromIncomingMessage, writeResponseToServerResponse, } from "./serve.js";
+export type { RequestAdapterOptions, ServeOptions, ServerHandle, } from "./serve.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":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,wBAAwB,EACxB,KAAK,EACL,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,qBAAqB,EACrB,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@superbee/server` — the wire-protocol v0 REFERENCE server
+ * (`docs/WIRE-PROTOCOL.md`): a Web-standard `fetch`-style router over the OKF
+ * engine, plus a thin `node:http` bootstrap. A pure consumer of
+ * `@superbee/core` — no parsing/link/OKF logic lives here (see `router.ts`
+ * module doc). Reference-not-production: no auth, loopback-only default bind.
+ *
+ * @packageDocumentation
+ */
+export { createRouter, createRouterForBackend } from "./legacy-router.js";
+export { WIRE_ENDPOINTS } from "./router.js";
+export { RequestBodyTooLargeError, serve, requestFromIncomingMessage, writeResponseToServerResponse, } from "./serve.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;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,wBAAwB,EACxB,KAAK,EACL,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,YAAY,CAAC"}

package/dist/legacy-router.d.ts

@@ -0,0 +1,7 @@
+/** Node-specific compatibility adapter for the historical single-backend package root. */
+import { type Bundle, type StorageBackend } from "@superbee/core";
+/** Historical explicit-backend entry point retained at the Node package root. */
+export declare function createRouterForBackend(backend: StorageBackend): (request: Request) => Promise<Response>;
+/** Historical Bundle entry point retained at the Node package root, including `/bundles/default`. */
+export declare function createRouter(bundle: Bundle): (request: Request) => Promise<Response>;
+//# sourceMappingURL=legacy-router.d.ts.map

package/dist/legacy-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-router.d.ts","sourceRoot":"","sources":["../src/legacy-router.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAE1F,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,cAAc,EAEpB,MAAM,gBAAgB,CAAC;AAiDxB,iFAAiF;AACjF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAEvG;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAEpF"}

package/dist/legacy-router.js

@@ -0,0 +1,48 @@
+/** Node-specific compatibility adapter for the historical single-backend package root. */
+import { FilesystemBackend, MemoryBackend, } from "@superbee/core";
+import { createRouter as createWorkerRouter, } from "./router.js";
+const LEGACY_INTERNAL_BUNDLE_ID = "bnd_00000000000000000000000000000000";
+function capabilitiesForBackend(backend) {
+    return (backend.capabilities?.() ?? {
+        enforced_cas: backend instanceof MemoryBackend,
+        blobs: true,
+        projections: true,
+        backlinks: false,
+    });
+}
+function legacyAttribution(request) {
+    const actor = request.headers.get("X-Actor")?.trim();
+    const agent = request.headers.get("X-Agent")?.trim();
+    return {
+        actor: actor || "unknown",
+        ...(agent ? { agent } : {}),
+    };
+}
+/**
+ * Map the old ignored bundle slot to one internal canonical id. This adapter is reachable only
+ * from the Node package root; `@superbee/server/router` never admits `default` or another alias.
+ */
+function canonicalizeLegacyBundleRoute(request) {
+    const url = new URL(request.url);
+    const match = /^\/v0\/bundles\/([^/]+)\/(.*)$/.exec(url.pathname);
+    if (!match)
+        return request;
+    url.pathname = `/v0/bundles/${LEGACY_INTERNAL_BUNDLE_ID}/${match[2]}`;
+    return new Request(url, request);
+}
+function buildLegacyRouter(backend) {
+    const workerRouter = createWorkerRouter({
+        capabilities: capabilitiesForBackend(backend),
+        resolveContext: (request) => ({ backend, attribution: legacyAttribution(request) }),
+    });
+    return (request) => workerRouter(canonicalizeLegacyBundleRoute(request));
+}
+/** Historical explicit-backend entry point retained at the Node package root. */
+export function createRouterForBackend(backend) {
+    return buildLegacyRouter(backend);
+}
+/** Historical Bundle entry point retained at the Node package root, including `/bundles/default`. */
+export function createRouter(bundle) {
+    return buildLegacyRouter(bundle.backend ?? new FilesystemBackend(bundle.root));
+}
+//# sourceMappingURL=legacy-router.js.map

package/dist/legacy-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-router.js","sourceRoot":"","sources":["../src/legacy-router.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAE1F,OAAO,EACL,iBAAiB,EACjB,aAAa,GAId,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,YAAY,IAAI,kBAAkB,GAEnC,MAAM,aAAa,CAAC;AAErB,MAAM,yBAAyB,GAAG,sCAAsC,CAAC;AAEzE,SAAS,sBAAsB,CAAC,OAAuB;IACrD,OAAO,CACL,OAAO,CAAC,YAAY,EAAE,EAAE,IAAI;QAC1B,YAAY,EAAE,OAAO,YAAY,aAAa;QAC9C,KAAK,EAAE,IAAI;QACX,WAAW,EAAE,IAAI;QACjB,SAAS,EAAE,KAAK;KACjB,CACF,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAgB;IACzC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC;IACrD,OAAO;QACL,KAAK,EAAE,KAAK,IAAI,SAAS;QACzB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5B,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,6BAA6B,CAAC,OAAgB;IACrD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,gCAAgC,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClE,IAAI,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC;IAC3B,GAAG,CAAC,QAAQ,GAAG,eAAe,yBAAyB,IAAI,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC;IACvE,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAuB;IAChD,MAAM,YAAY,GAAG,kBAAkB,CAAC;QACtC,YAAY,EAAE,sBAAsB,CAAC,OAAO,CAAC;QAC7C,cAAc,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;KACpF,CAAC,CAAC;IACH,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,6BAA6B,CAAC,OAAO,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,sBAAsB,CAAC,OAAuB;IAC5D,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO,iBAAiB,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AACjF,CAAC"}

package/dist/router.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Wire-protocol v0 fetch router — the wire-protocol v0 seam-over-HTTP contract
+ * (`docs/WIRE-PROTOCOL.md`) implemented as a plain
+ * `(req: Request) => Promise<Response>` function using Web-standard `Request`/
+ * `Response`, so the identical router can mount unchanged in another Fetch-compatible runtime.
+ *
+ * ONE-ENGINE RULE: this module contains NO parsing/link/OKF logic of its own.
+ * Doc WRITES route through the engine (`writeDocVersioned` from `@superbee/core`)
+ * so server-side OKF enforcement (non-empty `type`, id safety, reserved-file
+ * rejection) comes free — the engine keeps ALL semantics, the router only maps
+ * HTTP <-> the `StorageBackend` seam. Reads / list / versions / reserved-file
+ * access go through the bundle's `StorageBackend` DIRECTLY (protocol principle 2:
+ * "the seam is the schema" — every endpoint maps 1:1 to a seam method), not
+ * through the engine's `query`/`readDoc` wrappers.
+ *
+ * See `docs/WIRE-PROTOCOL.md` "Implemented by reference" section for the exact
+ * endpoint set and any recorded deviations from the draft.
+ */
+import { type BlobKey, type ConceptId, type ReservedFilename, type StorageBackend, type StorageCapabilities } from "@superbee/core/storage";
+/** Canonical remote bundle id: 16 random bytes rendered as lowercase hexadecimal. */
+export type BundleId = `bnd_${string}`;
+/** Access needed before a registered endpoint may dispatch. */
+export type WireAccessClass = "public" | "read" | "write";
+/**
+ * The complete public route/method registry for the reference router. Runtime dispatch consumes
+ * this table, and the repository contract test compares the same rows with WIRE-PROTOCOL.md, so a
+ * route cannot become reachable without entering the documented agreement surface.
+ */
+export declare const WIRE_ENDPOINTS: readonly [{
+    readonly id: "capabilities";
+    readonly resource: "capabilities";
+    readonly method: "GET";
+    readonly path: "/v0/capabilities";
+    readonly accessClass: "public";
+}, {
+    readonly id: "docs-list";
+    readonly resource: "docs";
+    readonly method: "GET";
+    readonly path: "/v0/bundles/{bundle}/docs";
+    readonly accessClass: "read";
+}, {
+    readonly id: "docs-read-many";
+    readonly resource: "docs-read-many";
+    readonly method: "POST";
+    readonly path: "/v0/bundles/{bundle}/docs:read-many";
+    readonly accessClass: "read";
+}, {
+    readonly id: "doc-read";
+    readonly resource: "doc";
+    readonly method: "GET";
+    readonly path: "/v0/bundles/{bundle}/docs/{id...}";
+    readonly accessClass: "read";
+}, {
+    readonly id: "doc-write";
+    readonly resource: "doc";
+    readonly method: "PUT";
+    readonly path: "/v0/bundles/{bundle}/docs/{id...}";
+    readonly accessClass: "write";
+}, {
+    readonly id: "doc-head";
+    readonly resource: "doc";
+    readonly method: "HEAD";
+    readonly path: "/v0/bundles/{bundle}/docs/{id...}";
+    readonly accessClass: "read";
+}, {
+    readonly id: "doc-delete";
+    readonly resource: "doc";
+    readonly method: "DELETE";
+    readonly path: "/v0/bundles/{bundle}/docs/{id...}";
+    readonly accessClass: "write";
+}, {
+    readonly id: "doc-versions";
+    readonly resource: "doc-versions";
+    readonly method: "GET";
+    readonly path: "/v0/bundles/{bundle}/docs/{id...}/versions";
+    readonly accessClass: "read";
+}, {
+    readonly id: "reserved-read";
+    readonly resource: "reserved";
+    readonly method: "GET";
+    readonly path: "/v0/bundles/{bundle}/reserved/{name}";
+    readonly accessClass: "read";
+}, {
+    readonly id: "reserved-write";
+    readonly resource: "reserved";
+    readonly method: "PUT";
+    readonly path: "/v0/bundles/{bundle}/reserved/{name}";
+    readonly accessClass: "write";
+}, {
+    readonly id: "blobs-list";
+    readonly resource: "blobs";
+    readonly method: "GET";
+    readonly path: "/v0/bundles/{bundle}/blobs";
+    readonly accessClass: "read";
+}, {
+    readonly id: "blob-read";
+    readonly resource: "blob";
+    readonly method: "GET";
+    readonly path: "/v0/bundles/{bundle}/blobs/{key...}";
+    readonly accessClass: "read";
+}, {
+    readonly id: "blob-write";
+    readonly resource: "blob";
+    readonly method: "PUT";
+    readonly path: "/v0/bundles/{bundle}/blobs/{key...}";
+    readonly accessClass: "write";
+}, {
+    readonly id: "blob-head";
+    readonly resource: "blob";
+    readonly method: "HEAD";
+    readonly path: "/v0/bundles/{bundle}/blobs/{key...}";
+    readonly accessClass: "read";
+}, {
+    readonly id: "blob-delete";
+    readonly resource: "blob";
+    readonly method: "DELETE";
+    readonly path: "/v0/bundles/{bundle}/blobs/{key...}";
+    readonly accessClass: "write";
+}];
+export type WireEndpointId = (typeof WIRE_ENDPOINTS)[number]["id"];
+export type ResolvedWireResource = {
+    kind: "capabilities";
+} | {
+    kind: "docs";
+} | {
+    kind: "docs-read-many";
+} | {
+    kind: "doc";
+    id: ConceptId;
+} | {
+    kind: "doc-versions";
+    id: ConceptId;
+} | {
+    kind: "reserved";
+    dir: string;
+    name: ReservedFilename;
+} | {
+    kind: "blobs";
+} | {
+    kind: "blob";
+    key: BlobKey;
+};
+interface ResolvedWireRouteBase {
+    endpointId: WireEndpointId;
+    accessClass: WireAccessClass;
+    resource: ResolvedWireResource;
+    searchParams: URLSearchParams;
+}
+/** A deployment-scoped route never causes context or backend resolution. */
+export interface ResolvedDeploymentWireRoute extends ResolvedWireRouteBase {
+    scope: "deployment";
+    endpointId: "capabilities";
+    accessClass: "public";
+    resource: {
+        kind: "capabilities";
+    };
+}
+/** A bundle-scoped route carries the one canonical bundle selection used by all later stages. */
+export interface ResolvedBundleWireRoute extends ResolvedWireRouteBase {
+    scope: "bundle";
+    bundleId: BundleId;
+    accessClass: "read" | "write";
+}
+export type ResolvedWireRoute = ResolvedDeploymentWireRoute | ResolvedBundleWireRoute;
+/** Attribution supplied by the trusted host after authentication, never by public request headers. */
+export interface TrustedAttribution {
+    actor: string;
+    agent?: string;
+}
+/** The host's one-shot authorization result, including a backend already bound to `route.bundleId`. */
+export interface TrustedRouterContext {
+    backend: StorageBackend;
+    attribution: TrustedAttribution;
+}
+export interface RouterOptions {
+    capabilities: StorageCapabilities;
+    resolveContext(request: Request, route: ResolvedBundleWireRoute): TrustedRouterContext | Response | Promise<TrustedRouterContext | Response>;
+}
+/** Typed resolution failure retained as a stable host-side rejection seam. */
+export declare class WireRequestResolutionError extends Error {
+    readonly status: 400 | 404;
+    readonly code: "USAGE" | "NOT_FOUND";
+    constructor(status: 400 | 404, code: "USAGE" | "NOT_FOUND", message: string);
+}
+export declare function isCanonicalBundleId(value: string): value is BundleId;
+/** Resolve route identity, canonical bundle selection, decoded resource, and access once. */
+export declare function resolveWireRequest(request: Request): ResolvedWireRoute;
+/**
+ * Build the fetch-style router for Worker runtimes. Bundle routes resolve context exactly once
+ * after canonical route resolution; deployment capabilities bypass context and storage entirely.
+ */
+export declare function createRouter(options: RouterOptions): (req: Request) => Promise<Response>;
+export {};
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

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