@rayfold/server 0.1.0

package/bindings.js

@@ -0,0 +1,284 @@
+import { annotation } from "@rayfold/schema";
+import { HTTP_STATUS, RayfoldError } from "./protocol.js";
+import { applyCacheHeaders } from "./http.js";
+import { BodyTooLarge, PROBLEM_TYPE_BASE, hostProblem, mediaType, originProblem, refuse, refuseBody } from "./guard.js";
+export const QUERY_METHODS = ["GET", "QUERY"];
+export const COMMAND_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
+/** Methods whose HTTP semantics are idempotent: a command bound to them may run without an Idempotency-Key. */
+const IDEMPOTENT_METHODS = new Set(["PUT", "PATCH", "DELETE"]);
+export function bindingsOf(ir) {
+    const out = [];
+    for (const op of Object.values(ir.ops)) {
+        const a = annotation(op, "http");
+        if (!a)
+            continue;
+        const method = identOrString(a.args["method"])?.toUpperCase();
+        const path = typeof a.args["path"] === "string" ? a.args["path"] : undefined;
+        if (!method || !path)
+            continue;
+        const params = [];
+        const pattern = path.replace(/[.*+?^()|[\]\\]/g, "\\$&").replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => {
+            params.push(name);
+            return "([^/]+)";
+        });
+        const b = { op, method, path, params, regex: new RegExp(`^${pattern}$`) };
+        const body = identOrString(a.args["body"]);
+        if (body)
+            b.body = body;
+        if (typeof a.args["location"] === "string")
+            b.location = a.args["location"];
+        out.push(b);
+    }
+    return out;
+}
+function identOrString(v) {
+    if (typeof v === "string")
+        return v;
+    if (v && typeof v === "object" && "$ident" in v)
+        return String(v.$ident);
+    return undefined;
+}
+/** Returns a handler that answers bound routes and returns false for anything else. */
+export function createBindingHandler(server, opts = {}) {
+    const bindings = bindingsOf(server.ir);
+    const prefix = opts.prefix ?? "";
+    const maxBody = opts.maxBody ?? 1_048_576;
+    return async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (!url.pathname.startsWith(prefix))
+            return false;
+        const path = url.pathname.slice(prefix.length) || "/";
+        const matches = bindings.map((b) => ({ b, m: b.regex.exec(path) })).filter((x) => x.m);
+        if (!matches.length)
+            return false;
+        res.setHeader("X-Content-Type-Options", "nosniff");
+        const safeMethod = req.method === "GET" || req.method === "HEAD" || req.method === "QUERY"; // queries only: they cannot change data
+        const refused = hostProblem(req, opts) ?? (safeMethod ? null : originProblem(req, opts));
+        if (refused) {
+            refuse(res, 403, "permission_denied", refused);
+            return true;
+        }
+        const hit = matches.find((x) => x.b.method === req.method);
+        if (!hit) {
+            res.setHeader("Allow", matches.map((x) => x.b.method).join(", "));
+            problem(res, 405, { code: "unimplemented", message: `${req.method} is not bound on ${path}` });
+            return true;
+        }
+        const { b, m } = hit;
+        try {
+            const args = {};
+            b.params.forEach((name, i) => (args[name] = fromText(b.op, name, decodePathSegment(m[i + 1], name))));
+            const shapeParam = url.searchParams.get("shape");
+            if (b.method === "GET") {
+                for (const [k, v] of url.searchParams)
+                    if (k !== "shape" && !(k in args))
+                        args[k] = fromText(b.op, k, v);
+            }
+            if (b.body) {
+                const raw = await readBody(req, maxBody);
+                if (raw.length) {
+                    const ct = mediaType(req);
+                    const accepted = b.method === "PATCH" ? ["application/merge-patch+json", "application/json"] : ["application/json"];
+                    if (!accepted.includes(ct)) {
+                        refuse(res, 415, "invalid_argument", `Content-Type ${ct || "(none)"} is not accepted; send ${accepted[0]}`, "unsupported_media_type");
+                        return true;
+                    }
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(raw);
+                    }
+                    catch {
+                        throw new RayfoldError("invalid_argument", "Body is not valid JSON");
+                    }
+                    if (b.body === "*") {
+                        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                            throw new RayfoldError("invalid_argument", "Body must be a JSON object");
+                        Object.assign(args, parsed);
+                    }
+                    else
+                        args[b.body] = parsed;
+                }
+            }
+            const op = { id: 1, op: b.op.name, args };
+            if (shapeParam)
+                op.shape = shapeParam;
+            const key = header(req, "idempotency-key");
+            if (key)
+                op.key = key;
+            const ifMatch = header(req, "if-match");
+            if (ifMatch) {
+                const v = ifMatch.replace(/^W\//, "").replace(/^"|"$/g, "");
+                op.ifVersion = /^\d+$/.test(v) ? Number(v) : v;
+            }
+            if (b.op.kind === "command" && b.method === "POST" && !key) {
+                const idem = annotation(b.op, "idempotent");
+                if (!(idem && idem.args["value"] === false)) {
+                    throw new RayfoldError("invalid_argument", `POST ${b.path} requires an Idempotency-Key header (16-128 characters)`);
+                }
+            }
+            const envelope = { ops: [op] };
+            const viewer = opts.viewer ? await opts.viewer(req) : null;
+            const frames = [];
+            for await (const f of server.execute(envelope, { viewer, keyOptional: IDEMPOTENT_METHODS.has(b.method) }))
+                frames.push(f);
+            const folded = fold(frames);
+            if ("error" in folded) {
+                const e = folded.error;
+                const status = e.type === "VersionConflict" ? 412 : HTTP_STATUS[e.code];
+                problem(res, status, e);
+                return true;
+            }
+            const result = folded.result;
+            if (b.op.kind === "query") {
+                applyCacheHeaders(server, envelope, frames, viewer, res);
+                if (header(req, "if-none-match") && header(req, "if-none-match") === res.getHeader("ETag")) {
+                    res.removeHeader("X-Content-Type-Options"); // no body to sniff; the cached response keeps its headers
+                    res.writeHead(304).end();
+                    return true;
+                }
+                json(res, 200, result);
+                return true;
+            }
+            res.setHeader("Cache-Control", "no-store");
+            const version = versionOf(server.ir, b.op, result);
+            if (version !== undefined)
+                res.setHeader("ETag", `"${version}"`);
+            if (folded.replay)
+                res.setHeader("Idempotent-Replayed", "true");
+            if (b.method === "POST" && b.location && result && typeof result === "object") {
+                res.setHeader("Location", prefix + b.location.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, f) => encodeURIComponent(String(result[f] ?? ""))));
+                json(res, 201, result);
+                return true;
+            }
+            json(res, 200, result);
+            return true;
+        }
+        catch (e) {
+            if (e instanceof BodyTooLarge) {
+                refuseBody(res, e);
+                return true;
+            }
+            const w = e instanceof RayfoldError ? e.toWire() : { code: "internal", message: "Internal error" };
+            problem(res, HTTP_STATUS[w.code], w);
+            return true;
+        }
+    };
+}
+function decodePathSegment(raw, name) {
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        throw new RayfoldError("invalid_argument", `Path parameter ${name} is not valid percent-encoding`);
+    }
+}
+/** Path and query-string values are text; coerce them by the argument's declared type. */
+function fromText(op, name, text) {
+    const def = op.args.find((a) => a.name === name);
+    if (!def || def.type.kind !== "named")
+        return text;
+    switch (def.type.name) {
+        case "Int":
+        case "Float":
+            return /^-?\d+(\.\d+)?$/.test(text) ? Number(text) : text;
+        case "Boolean":
+            return text === "true" ? true : text === "false" ? false : text;
+        case "ID":
+        case "String":
+        case "Decimal":
+        case "Date":
+        case "Instant":
+            return text;
+        default:
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+    }
+}
+/** The @version field of the result entity, if the op returns one. */
+function versionOf(ir, op, result) {
+    if (!result || typeof result !== "object" || op.returns.kind !== "named")
+        return undefined;
+    const def = ir.types[op.returns.name];
+    if (!def || def.kind !== "entity")
+        return undefined;
+    const vf = def.fields.find((f) => annotation(f, "version"));
+    return vf ? result[vf.name] : undefined;
+}
+function fold(frames) {
+    let result = null;
+    let replay = false;
+    for (const f of frames) {
+        if ("error" in f)
+            return { error: f.error };
+        if ("ok" in f) {
+            result = f.ok;
+            replay = !!f.meta?.replay;
+        }
+        else if ("data" in f && !("at" in f))
+            result = f.data;
+        else if ("at" in f && result && typeof result === "object") {
+            let target = result;
+            if (f.at !== "")
+                for (const p of f.at.split("."))
+                    target = target && typeof target === "object" ? target[p] : undefined;
+            if (target && typeof target === "object")
+                Object.assign(target, f.data);
+        }
+    }
+    return { result, replay };
+}
+function header(req, name) {
+    const v = req.headers[name];
+    return typeof v === "string" ? v : undefined;
+}
+/** How much of an over-limit body is drained (so the refusal can be read) before the socket is dropped. */
+const DRAIN_LIMIT = 1_048_576;
+function readBody(req, max) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let over = false;
+        req.on("data", (c) => {
+            size += c.length;
+            if (over) {
+                // A client that keeps streaming long after the refusal is cut off rather than read forever.
+                if (size > max + DRAIN_LIMIT)
+                    req.destroy();
+                return;
+            }
+            if (size > max) {
+                // Stop buffering but keep draining: destroying the socket here would lose the refusal on its way out.
+                over = true;
+                chunks.length = 0;
+                reject(new BodyTooLarge(max));
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function json(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+}
+/** RFC 9457 problem; typed Rayfold errors keep their `type` and `data` so REST clients can branch on them. */
+function problem(res, status, e) {
+    const body = {
+        type: PROBLEM_TYPE_BASE + (e.type ?? e.code),
+        title: e.type ?? e.code.replace(/_/g, " "),
+        status,
+        detail: e.message,
+        code: e.code,
+    };
+    if (e.path !== undefined)
+        body["path"] = e.path;
+    if (e.data !== undefined)
+        body["data"] = e.data;
+    res.writeHead(status, { "Content-Type": "application/problem+json", "Cache-Control": "no-store" }).end(JSON.stringify(body));
+}
+//# sourceMappingURL=bindings.js.map

package/bindings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.js","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HTTP bindings (extension `http`, spec 04 section 8): expose queries and commands on REST-shaped routes with\n * their natural methods, backed by the same contract (validation, policies, typed errors, idempotency, patches).\n *\n *   query   book(id: ID): Book?            @http(method: GET,    path: \"/books/{id}\")\n *   command editReview(id: ID, input: ...) @http(method: PUT,    path: \"/reviews/{id}\", body: input)\n *   command updateBook(id: ID, patch: ...) @http(method: PATCH,  path: \"/books/{id}\",   body: patch)\n *   command deleteReview(id: ID)           @http(method: DELETE, path: \"/reviews/{id}\")\n *   command placeOrder(input: ...)         @http(method: POST,   path: \"/orders\", body: input, location: \"/orders/{id}\")\n *   query   books(filter: ..., page: ...)  @http(method: QUERY,  path: \"/books\", body: \"*\")\n */\nimport type { IncomingMessage, ServerResponse } from \"node:http\";\nimport { annotation, type OpDef, type RayfoldSchemaIR } from \"@rayfold/schema\";\nimport type { RayfoldServer } from \"./server.ts\";\nimport { HTTP_STATUS, RayfoldError, type Frame, type RequestEnvelope, type RequestOp, type WireError } from \"./protocol.ts\";\nimport { applyCacheHeaders } from \"./http.ts\";\nimport { BodyTooLarge, PROBLEM_TYPE_BASE, hostProblem, mediaType, originProblem, refuse, refuseBody, type OriginOptions } from \"./guard.ts\";\n\nexport const QUERY_METHODS = [\"GET\", \"QUERY\"] as const;\nexport const COMMAND_METHODS = [\"POST\", \"PUT\", \"PATCH\", \"DELETE\"] as const;\n/** Methods whose HTTP semantics are idempotent: a command bound to them may run without an Idempotency-Key. */\nconst IDEMPOTENT_METHODS = new Set([\"PUT\", \"PATCH\", \"DELETE\"]);\n\nexport interface Binding {\n  op: OpDef;\n  method: string;\n  path: string;\n  /** name of the argument that receives the JSON body, or \"*\" to spread the body into the arguments */\n  body?: string;\n  /** Location template for 201 responses, filled from the result, e.g. \"/orders/{id}\" */\n  location?: string;\n  params: string[];\n  regex: RegExp;\n}\n\nexport function bindingsOf(ir: RayfoldSchemaIR): Binding[] {\n  const out: Binding[] = [];\n  for (const op of Object.values(ir.ops)) {\n    const a = annotation(op, \"http\");\n    if (!a) continue;\n    const method = identOrString(a.args[\"method\"])?.toUpperCase();\n    const path = typeof a.args[\"path\"] === \"string\" ? a.args[\"path\"] : undefined;\n    if (!method || !path) continue;\n    const params: string[] = [];\n    const pattern = path.replace(/[.*+?^()|[\\]\\\\]/g, \"\\\\$&\").replace(/\\{([A-Za-z_][A-Za-z0-9_]*)\\}/g, (_m, name: string) => {\n      params.push(name);\n      return \"([^/]+)\";\n    });\n    const b: Binding = { op, method, path, params, regex: new RegExp(`^${pattern}$`) };\n    const body = identOrString(a.args[\"body\"]);\n    if (body) b.body = body;\n    if (typeof a.args[\"location\"] === \"string\") b.location = a.args[\"location\"];\n    out.push(b);\n  }\n  return out;\n}\n\nfunction identOrString(v: unknown): string | undefined {\n  if (typeof v === \"string\") return v;\n  if (v && typeof v === \"object\" && \"$ident\" in v) return String((v as { $ident: string }).$ident);\n  return undefined;\n}\n\nexport interface BindingOptions extends OriginOptions {\n  /** Mount prefix, default \"\" (routes are served exactly as declared). */\n  prefix?: string;\n  viewer?: (req: IncomingMessage) => unknown | Promise<unknown>;\n  maxBody?: number;\n}\n\n/** Returns a handler that answers bound routes and returns false for anything else. */\nexport function createBindingHandler(server: RayfoldServer, opts: BindingOptions = {}): (req: IncomingMessage, res: ServerResponse) => Promise<boolean> {\n  const bindings = bindingsOf(server.ir);\n  const prefix = opts.prefix ?? \"\";\n  const maxBody = opts.maxBody ?? 1_048_576;\n\n  return async (req, res) => {\n    const url = new URL(req.url ?? \"/\", \"http://localhost\");\n    if (!url.pathname.startsWith(prefix)) return false;\n    const path = url.pathname.slice(prefix.length) || \"/\";\n    const matches = bindings.map((b) => ({ b, m: b.regex.exec(path) })).filter((x) => x.m);\n    if (!matches.length) return false;\n    res.setHeader(\"X-Content-Type-Options\", \"nosniff\");\n    const safeMethod = req.method === \"GET\" || req.method === \"HEAD\" || req.method === \"QUERY\"; // queries only: they cannot change data\n    const refused = hostProblem(req, opts) ?? (safeMethod ? null : originProblem(req, opts));\n    if (refused) {\n      refuse(res, 403, \"permission_denied\", refused);\n      return true;\n    }\n    const hit = matches.find((x) => x.b.method === req.method);\n    if (!hit) {\n      res.setHeader(\"Allow\", matches.map((x) => x.b.method).join(\", \"));\n      problem(res, 405, { code: \"unimplemented\", message: `${req.method} is not bound on ${path}` });\n      return true;\n    }\n    const { b, m } = hit as { b: Binding; m: RegExpExecArray };\n    try {\n      const args: Record<string, unknown> = {};\n      b.params.forEach((name, i) => (args[name] = fromText(b.op, name, decodePathSegment(m[i + 1]!, name))));\n      const shapeParam = url.searchParams.get(\"shape\");\n      if (b.method === \"GET\") {\n        for (const [k, v] of url.searchParams) if (k !== \"shape\" && !(k in args)) args[k] = fromText(b.op, k, v);\n      }\n      if (b.body) {\n        const raw = await readBody(req, maxBody);\n        if (raw.length) {\n          const ct = mediaType(req);\n          const accepted = b.method === \"PATCH\" ? [\"application/merge-patch+json\", \"application/json\"] : [\"application/json\"];\n          if (!accepted.includes(ct)) {\n            refuse(res, 415, \"invalid_argument\", `Content-Type ${ct || \"(none)\"} is not accepted; send ${accepted[0]}`, \"unsupported_media_type\");\n            return true;\n          }\n          let parsed: unknown;\n          try {\n            parsed = JSON.parse(raw);\n          } catch {\n            throw new RayfoldError(\"invalid_argument\", \"Body is not valid JSON\");\n          }\n          if (b.body === \"*\") {\n            if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) throw new RayfoldError(\"invalid_argument\", \"Body must be a JSON object\");\n            Object.assign(args, parsed);\n          } else args[b.body] = parsed;\n        }\n      }\n      const op: RequestOp = { id: 1, op: b.op.name, args };\n      if (shapeParam) op.shape = shapeParam;\n      const key = header(req, \"idempotency-key\");\n      if (key) op.key = key;\n      const ifMatch = header(req, \"if-match\");\n      if (ifMatch) {\n        const v = ifMatch.replace(/^W\\//, \"\").replace(/^\"|\"$/g, \"\");\n        op.ifVersion = /^\\d+$/.test(v) ? Number(v) : v;\n      }\n      if (b.op.kind === \"command\" && b.method === \"POST\" && !key) {\n        const idem = annotation(b.op, \"idempotent\");\n        if (!(idem && idem.args[\"value\"] === false)) {\n          throw new RayfoldError(\"invalid_argument\", `POST ${b.path} requires an Idempotency-Key header (16-128 characters)`);\n        }\n      }\n      const envelope: RequestEnvelope = { ops: [op] };\n      const viewer = opts.viewer ? await opts.viewer(req) : null;\n      const frames: Frame[] = [];\n      for await (const f of server.execute(envelope, { viewer, keyOptional: IDEMPOTENT_METHODS.has(b.method) })) frames.push(f);\n      const folded = fold(frames);\n      if (\"error\" in folded) {\n        const e = folded.error;\n        const status = e.type === \"VersionConflict\" ? 412 : HTTP_STATUS[e.code];\n        problem(res, status, e);\n        return true;\n      }\n      const result = folded.result;\n      if (b.op.kind === \"query\") {\n        applyCacheHeaders(server, envelope, frames, viewer, res);\n        if (header(req, \"if-none-match\") && header(req, \"if-none-match\") === res.getHeader(\"ETag\")) {\n          res.removeHeader(\"X-Content-Type-Options\"); // no body to sniff; the cached response keeps its headers\n          res.writeHead(304).end();\n          return true;\n        }\n        json(res, 200, result);\n        return true;\n      }\n      res.setHeader(\"Cache-Control\", \"no-store\");\n      const version = versionOf(server.ir, b.op, result);\n      if (version !== undefined) res.setHeader(\"ETag\", `\"${version}\"`);\n      if (folded.replay) res.setHeader(\"Idempotent-Replayed\", \"true\");\n      if (b.method === \"POST\" && b.location && result && typeof result === \"object\") {\n        res.setHeader(\"Location\", prefix + b.location.replace(/\\{([A-Za-z_][A-Za-z0-9_]*)\\}/g, (_m, f: string) => encodeURIComponent(String((result as Record<string, unknown>)[f] ?? \"\"))));\n        json(res, 201, result);\n        return true;\n      }\n      json(res, 200, result);\n      return true;\n    } catch (e) {\n      if (e instanceof BodyTooLarge) {\n        refuseBody(res, e);\n        return true;\n      }\n      const w = e instanceof RayfoldError ? e.toWire() : { code: \"internal\" as const, message: \"Internal error\" };\n      problem(res, HTTP_STATUS[w.code], w);\n      return true;\n    }\n  };\n}\n\nfunction decodePathSegment(raw: string, name: string): string {\n  try {\n    return decodeURIComponent(raw);\n  } catch {\n    throw new RayfoldError(\"invalid_argument\", `Path parameter ${name} is not valid percent-encoding`);\n  }\n}\n\n/** Path and query-string values are text; coerce them by the argument's declared type. */\nfunction fromText(op: OpDef, name: string, text: string): unknown {\n  const def = op.args.find((a) => a.name === name);\n  if (!def || def.type.kind !== \"named\") return text;\n  switch (def.type.name) {\n    case \"Int\":\n    case \"Float\":\n      return /^-?\\d+(\\.\\d+)?$/.test(text) ? Number(text) : text;\n    case \"Boolean\":\n      return text === \"true\" ? true : text === \"false\" ? false : text;\n    case \"ID\":\n    case \"String\":\n    case \"Decimal\":\n    case \"Date\":\n    case \"Instant\":\n      return text;\n    default:\n      try {\n        return JSON.parse(text);\n      } catch {\n        return text;\n      }\n  }\n}\n\n/** The @version field of the result entity, if the op returns one. */\nfunction versionOf(ir: RayfoldSchemaIR, op: OpDef, result: unknown): unknown {\n  if (!result || typeof result !== \"object\" || op.returns.kind !== \"named\") return undefined;\n  const def = ir.types[op.returns.name];\n  if (!def || def.kind !== \"entity\") return undefined;\n  const vf = def.fields.find((f) => annotation(f, \"version\"));\n  return vf ? (result as Record<string, unknown>)[vf.name] : undefined;\n}\n\nfunction fold(frames: Frame[]): { result: unknown; replay: boolean } | { error: WireError } {\n  let result: unknown = null;\n  let replay = false;\n  for (const f of frames) {\n    if (\"error\" in f) return { error: f.error };\n    if (\"ok\" in f) {\n      result = f.ok;\n      replay = !!(f.meta as { replay?: boolean } | undefined)?.replay;\n    } else if (\"data\" in f && !(\"at\" in f)) result = f.data;\n    else if (\"at\" in f && result && typeof result === \"object\") {\n      let target: unknown = result;\n      if (f.at !== \"\") for (const p of f.at.split(\".\")) target = target && typeof target === \"object\" ? (target as Record<string, unknown>)[p] : undefined;\n      if (target && typeof target === \"object\") Object.assign(target as object, f.data as object);\n    }\n  }\n  return { result, replay };\n}\n\nfunction header(req: IncomingMessage, name: string): string | undefined {\n  const v = req.headers[name];\n  return typeof v === \"string\" ? v : undefined;\n}\n\n/** How much of an over-limit body is drained (so the refusal can be read) before the socket is dropped. */\nconst DRAIN_LIMIT = 1_048_576;\n\nfunction readBody(req: IncomingMessage, max: number): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const chunks: Buffer[] = [];\n    let size = 0;\n    let over = false;\n    req.on(\"data\", (c: Buffer) => {\n      size += c.length;\n      if (over) {\n        // A client that keeps streaming long after the refusal is cut off rather than read forever.\n        if (size > max + DRAIN_LIMIT) req.destroy();\n        return;\n      }\n      if (size > max) {\n        // Stop buffering but keep draining: destroying the socket here would lose the refusal on its way out.\n        over = true;\n        chunks.length = 0;\n        reject(new BodyTooLarge(max));\n        return;\n      }\n      chunks.push(c);\n    });\n    req.on(\"end\", () => resolve(Buffer.concat(chunks).toString(\"utf8\")));\n    req.on(\"error\", reject);\n  });\n}\n\nfunction json(res: ServerResponse, status: number, body: unknown): void {\n  res.writeHead(status, { \"Content-Type\": \"application/json; charset=utf-8\" }).end(JSON.stringify(body));\n}\n\n/** RFC 9457 problem; typed Rayfold errors keep their `type` and `data` so REST clients can branch on them. */\nfunction problem(res: ServerResponse, status: number, e: WireError): void {\n  const body: Record<string, unknown> = {\n    type: PROBLEM_TYPE_BASE + (e.type ?? e.code),\n    title: e.type ?? e.code.replace(/_/g, \" \"),\n    status,\n    detail: e.message,\n    code: e.code,\n  };\n  if (e.path !== undefined) body[\"path\"] = e.path;\n  if (e.data !== undefined) body[\"data\"] = e.data;\n  res.writeHead(status, { \"Content-Type\": \"application/problem+json\", \"Cache-Control\": \"no-store\" }).end(JSON.stringify(body));\n}\n"]}

package/capability-scope.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether a viewer holding a capability may call this operation. A viewer without `caps.ops` is not a capability
+ * holder and is left to the schema's own policies.
+ *
+ * Kept apart from capability.ts, which signs tokens with node:crypto: the batch needs only this check, and the batch
+ * has to run anywhere, browsers included.
+ */
+export declare function capabilityAllows(viewer: unknown, op: string): boolean;

package/capability-scope.js

@@ -0,0 +1,19 @@
+/**
+ * Whether a viewer holding a capability may call this operation. A viewer without `caps.ops` is not a capability
+ * holder and is left to the schema's own policies.
+ *
+ * Kept apart from capability.ts, which signs tokens with node:crypto: the batch needs only this check, and the batch
+ * has to run anywhere, browsers included.
+ */
+export function capabilityAllows(viewer, op) {
+    if (!viewer || typeof viewer !== "object" || Array.isArray(viewer))
+        return true;
+    const caps = viewer.caps;
+    if (!caps || typeof caps !== "object" || Array.isArray(caps))
+        return true;
+    const ops = caps.ops;
+    if (!Array.isArray(ops))
+        return true;
+    return ops.includes(op);
+}
+//# sourceMappingURL=capability-scope.js.map

package/capability-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-scope.js","sourceRoot":"","sources":["../src/capability-scope.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAe,EAAE,EAAU;IAC1D,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAChF,MAAM,IAAI,GAAI,MAA6B,CAAC,IAAI,CAAC;IACjD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,MAAM,GAAG,GAAI,IAA0B,CAAC,GAAG,CAAC;IAC5C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC1B,CAAC","sourcesContent":["/**\n * Whether a viewer holding a capability may call this operation. A viewer without `caps.ops` is not a capability\n * holder and is left to the schema's own policies.\n *\n * Kept apart from capability.ts, which signs tokens with node:crypto: the batch needs only this check, and the batch\n * has to run anywhere, browsers included.\n */\nexport function capabilityAllows(viewer: unknown, op: string): boolean {\n  if (!viewer || typeof viewer !== \"object\" || Array.isArray(viewer)) return true;\n  const caps = (viewer as { caps?: unknown }).caps;\n  if (!caps || typeof caps !== \"object\" || Array.isArray(caps)) return true;\n  const ops = (caps as { ops?: unknown }).ops;\n  if (!Array.isArray(ops)) return true;\n  return ops.includes(op);\n}\n"]}

package/capability.d.ts

@@ -0,0 +1,56 @@
+export interface Capability {
+    /** the viewer this token speaks for, as the server's own viewer shape */
+    viewer: unknown;
+    /** the operations it may call; an empty list may call none */
+    ops: string[];
+    /** epoch milliseconds after which it is refused */
+    exp: number;
+    /** who issued it, for logs and revocation lists */
+    iss?: string;
+    /** extra facts the schema's policies read as `viewer.caps` */
+    caps?: Record<string, unknown>;
+    /** unique id of this token, so one can be named in a revocation list */
+    jti: string;
+}
+export interface MintOptions {
+    /** the operations the holder may call */
+    ops: string[];
+    /** how long it lives, in milliseconds */
+    ttlMs: number;
+    iss?: string;
+    caps?: Record<string, unknown>;
+}
+export interface CapabilitiesOptions {
+    /** the signing secret; anything derived from it must not leave the server */
+    secret: string | Uint8Array;
+    now?: () => number;
+    /** the longest life any token may have, minted or attenuated. Default one hour. */
+    maxTtlMs?: number;
+}
+/** Mints, verifies and narrows capability tokens with one secret. */
+export declare class Capabilities {
+    private readonly secret;
+    private readonly now;
+    private readonly maxTtlMs;
+    constructor(opts: CapabilitiesOptions);
+    mint(viewer: unknown, opts: MintOptions): string;
+    /** The capability a token carries, or a refusal: unsigned, edited, malformed and expired all fail here. */
+    verify(token: string): Capability;
+    /**
+     * A narrower token derived from this one: operations must be a subset of what it already allows, and the life
+     * may only be shortened. The derived token is a token in its own right, so it can be narrowed again.
+     */
+    attenuate(token: string, narrow: {
+        ops?: string[];
+        ttlMs?: number;
+        caps?: Record<string, unknown>;
+    }): string;
+    /**
+     * The viewer a token stands for, with what it allows attached as `caps`. Hand this to `execute` as the viewer:
+     * the schema's policies read `viewer.caps.*`, and the batch refuses operations the token does not name.
+     */
+    viewerOf(token: string): unknown;
+    private sign;
+    private hmac;
+}
+export { capabilityAllows } from "./capability-scope.js";

package/capability.js

@@ -0,0 +1,112 @@
+/**
+ * Capability tokens (extension `cap`, spec 06 section 6): short-lived, scoped, delegatable references to a viewer.
+ * They let an agent or a downstream service perform exactly one class of operation without ever holding the user's
+ * credentials, and they can be narrowed further before being handed on.
+ *
+ * A token carries everything it claims and is signed, so verifying one needs no storage and no round trip:
+ *
+ *   rfcap1.<payload as base64url JSON>.<HMAC-SHA256 of the payload, base64url>
+ *
+ * The payload names the viewer it speaks for, the operations it may call, when it expires and any extra facts the
+ * schema's policies may read as `viewer.caps`. Nothing in it is secret from its holder: it is a reference, not a
+ * password, and it is signed so it cannot be edited.
+ *
+ * Attenuation only ever narrows: a derived token may drop operations and shorten the life, never add or extend.
+ */
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { RayfoldError } from "./protocol.js";
+const PREFIX = "rfcap1";
+const b64url = (b) => b.toString("base64url");
+const unb64url = (s) => Buffer.from(s, "base64url");
+/** Mints, verifies and narrows capability tokens with one secret. */
+export class Capabilities {
+    secret;
+    now;
+    maxTtlMs;
+    constructor(opts) {
+        this.secret = typeof opts.secret === "string" ? new TextEncoder().encode(opts.secret) : opts.secret;
+        if (this.secret.length < 16)
+            throw new Error("capability secret must be at least 16 bytes");
+        this.now = opts.now ?? Date.now;
+        this.maxTtlMs = opts.maxTtlMs ?? 3_600_000;
+    }
+    mint(viewer, opts) {
+        if (opts.ttlMs <= 0 || opts.ttlMs > this.maxTtlMs) {
+            throw new Error(`capability ttl must be between 1 and ${this.maxTtlMs} ms`);
+        }
+        const cap = {
+            viewer,
+            ops: [...new Set(opts.ops)].sort(),
+            exp: this.now() + opts.ttlMs,
+            jti: randomUUID().replace(/-/g, ""),
+            ...(opts.iss ? { iss: opts.iss } : {}),
+            ...(opts.caps ? { caps: opts.caps } : {}),
+        };
+        return this.sign(cap);
+    }
+    /** The capability a token carries, or a refusal: unsigned, edited, malformed and expired all fail here. */
+    verify(token) {
+        const parts = token.split(".");
+        if (parts.length !== 3 || parts[0] !== PREFIX)
+            throw new RayfoldError("unauthenticated", "Not a capability token");
+        const signature = unb64url(parts[2]);
+        const expected = this.hmac(parts[1]);
+        if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) {
+            throw new RayfoldError("unauthenticated", "Capability signature does not match");
+        }
+        let cap;
+        try {
+            cap = JSON.parse(unb64url(parts[1]).toString("utf8"));
+        }
+        catch {
+            throw new RayfoldError("unauthenticated", "Capability payload is not readable");
+        }
+        if (!cap || typeof cap !== "object" || !Array.isArray(cap.ops) || typeof cap.exp !== "number") {
+            throw new RayfoldError("unauthenticated", "Capability payload is not a capability");
+        }
+        if (cap.exp <= this.now())
+            throw new RayfoldError("unauthenticated", "Capability has expired");
+        return cap;
+    }
+    /**
+     * A narrower token derived from this one: operations must be a subset of what it already allows, and the life
+     * may only be shortened. The derived token is a token in its own right, so it can be narrowed again.
+     */
+    attenuate(token, narrow) {
+        const cap = this.verify(token);
+        const ops = narrow.ops ? [...new Set(narrow.ops)].sort() : cap.ops;
+        const widened = ops.filter((op) => !cap.ops.includes(op));
+        if (widened.length)
+            throw new RayfoldError("permission_denied", `Cannot widen a capability: ${widened.join(", ")}`);
+        const exp = narrow.ttlMs === undefined ? cap.exp : Math.min(cap.exp, this.now() + narrow.ttlMs);
+        if (exp <= this.now())
+            throw new RayfoldError("permission_denied", "Cannot derive a capability that has expired");
+        return this.sign({
+            ...cap,
+            ops,
+            exp,
+            jti: randomUUID().replace(/-/g, ""),
+            // extra facts may be replaced, never added to: a narrower token cannot claim more than the one it came from
+            ...(narrow.caps ? { caps: narrow.caps } : {}),
+        });
+    }
+    /**
+     * The viewer a token stands for, with what it allows attached as `caps`. Hand this to `execute` as the viewer:
+     * the schema's policies read `viewer.caps.*`, and the batch refuses operations the token does not name.
+     */
+    viewerOf(token) {
+        const cap = this.verify(token);
+        const viewer = cap.viewer;
+        const caps = { ops: cap.ops, exp: cap.exp, jti: cap.jti, ...(cap.iss ? { iss: cap.iss } : {}), ...(cap.caps ?? {}) };
+        return viewer !== null && typeof viewer === "object" && !Array.isArray(viewer) ? { ...viewer, caps } : { viewer, caps };
+    }
+    sign(cap) {
+        const payload = b64url(Buffer.from(JSON.stringify(cap), "utf8"));
+        return `${PREFIX}.${payload}.${b64url(this.hmac(payload))}`;
+    }
+    hmac(payload) {
+        return createHmac("sha256", this.secret).update(`${PREFIX}.${payload}`).digest();
+    }
+}
+export { capabilityAllows } from "./capability-scope.js";
+//# sourceMappingURL=capability.js.map

package/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Capability tokens (extension `cap`, spec 06 section 6): short-lived, scoped, delegatable references to a viewer.\n * They let an agent or a downstream service perform exactly one class of operation without ever holding the user's\n * credentials, and they can be narrowed further before being handed on.\n *\n * A token carries everything it claims and is signed, so verifying one needs no storage and no round trip:\n *\n *   rfcap1.<payload as base64url JSON>.<HMAC-SHA256 of the payload, base64url>\n *\n * The payload names the viewer it speaks for, the operations it may call, when it expires and any extra facts the\n * schema's policies may read as `viewer.caps`. Nothing in it is secret from its holder: it is a reference, not a\n * password, and it is signed so it cannot be edited.\n *\n * Attenuation only ever narrows: a derived token may drop operations and shorten the life, never add or extend.\n */\nimport { createHmac, randomUUID, timingSafeEqual } from \"node:crypto\";\nimport { RayfoldError } from \"./protocol.ts\";\n\nconst PREFIX = \"rfcap1\";\n\nexport interface Capability {\n  /** the viewer this token speaks for, as the server's own viewer shape */\n  viewer: unknown;\n  /** the operations it may call; an empty list may call none */\n  ops: string[];\n  /** epoch milliseconds after which it is refused */\n  exp: number;\n  /** who issued it, for logs and revocation lists */\n  iss?: string;\n  /** extra facts the schema's policies read as `viewer.caps` */\n  caps?: Record<string, unknown>;\n  /** unique id of this token, so one can be named in a revocation list */\n  jti: string;\n}\n\nexport interface MintOptions {\n  /** the operations the holder may call */\n  ops: string[];\n  /** how long it lives, in milliseconds */\n  ttlMs: number;\n  iss?: string;\n  caps?: Record<string, unknown>;\n}\n\nexport interface CapabilitiesOptions {\n  /** the signing secret; anything derived from it must not leave the server */\n  secret: string | Uint8Array;\n  now?: () => number;\n  /** the longest life any token may have, minted or attenuated. Default one hour. */\n  maxTtlMs?: number;\n}\n\nconst b64url = (b: Buffer): string => b.toString(\"base64url\");\nconst unb64url = (s: string): Buffer => Buffer.from(s, \"base64url\");\n\n/** Mints, verifies and narrows capability tokens with one secret. */\nexport class Capabilities {\n  private readonly secret: Uint8Array;\n  private readonly now: () => number;\n  private readonly maxTtlMs: number;\n\n  constructor(opts: CapabilitiesOptions) {\n    this.secret = typeof opts.secret === \"string\" ? new TextEncoder().encode(opts.secret) : opts.secret;\n    if (this.secret.length < 16) throw new Error(\"capability secret must be at least 16 bytes\");\n    this.now = opts.now ?? Date.now;\n    this.maxTtlMs = opts.maxTtlMs ?? 3_600_000;\n  }\n\n  mint(viewer: unknown, opts: MintOptions): string {\n    if (opts.ttlMs <= 0 || opts.ttlMs > this.maxTtlMs) {\n      throw new Error(`capability ttl must be between 1 and ${this.maxTtlMs} ms`);\n    }\n    const cap: Capability = {\n      viewer,\n      ops: [...new Set(opts.ops)].sort(),\n      exp: this.now() + opts.ttlMs,\n      jti: randomUUID().replace(/-/g, \"\"),\n      ...(opts.iss ? { iss: opts.iss } : {}),\n      ...(opts.caps ? { caps: opts.caps } : {}),\n    };\n    return this.sign(cap);\n  }\n\n  /** The capability a token carries, or a refusal: unsigned, edited, malformed and expired all fail here. */\n  verify(token: string): Capability {\n    const parts = token.split(\".\");\n    if (parts.length !== 3 || parts[0] !== PREFIX) throw new RayfoldError(\"unauthenticated\", \"Not a capability token\");\n    const signature = unb64url(parts[2]!);\n    const expected = this.hmac(parts[1]!);\n    if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) {\n      throw new RayfoldError(\"unauthenticated\", \"Capability signature does not match\");\n    }\n    let cap: Capability;\n    try {\n      cap = JSON.parse(unb64url(parts[1]!).toString(\"utf8\")) as Capability;\n    } catch {\n      throw new RayfoldError(\"unauthenticated\", \"Capability payload is not readable\");\n    }\n    if (!cap || typeof cap !== \"object\" || !Array.isArray(cap.ops) || typeof cap.exp !== \"number\") {\n      throw new RayfoldError(\"unauthenticated\", \"Capability payload is not a capability\");\n    }\n    if (cap.exp <= this.now()) throw new RayfoldError(\"unauthenticated\", \"Capability has expired\");\n    return cap;\n  }\n\n  /**\n   * A narrower token derived from this one: operations must be a subset of what it already allows, and the life\n   * may only be shortened. The derived token is a token in its own right, so it can be narrowed again.\n   */\n  attenuate(token: string, narrow: { ops?: string[]; ttlMs?: number; caps?: Record<string, unknown> }): string {\n    const cap = this.verify(token);\n    const ops = narrow.ops ? [...new Set(narrow.ops)].sort() : cap.ops;\n    const widened = ops.filter((op) => !cap.ops.includes(op));\n    if (widened.length) throw new RayfoldError(\"permission_denied\", `Cannot widen a capability: ${widened.join(\", \")}`);\n    const exp = narrow.ttlMs === undefined ? cap.exp : Math.min(cap.exp, this.now() + narrow.ttlMs);\n    if (exp <= this.now()) throw new RayfoldError(\"permission_denied\", \"Cannot derive a capability that has expired\");\n    return this.sign({\n      ...cap,\n      ops,\n      exp,\n      jti: randomUUID().replace(/-/g, \"\"),\n      // extra facts may be replaced, never added to: a narrower token cannot claim more than the one it came from\n      ...(narrow.caps ? { caps: narrow.caps } : {}),\n    });\n  }\n\n  /**\n   * The viewer a token stands for, with what it allows attached as `caps`. Hand this to `execute` as the viewer:\n   * the schema's policies read `viewer.caps.*`, and the batch refuses operations the token does not name.\n   */\n  viewerOf(token: string): unknown {\n    const cap = this.verify(token);\n    const viewer = cap.viewer;\n    const caps = { ops: cap.ops, exp: cap.exp, jti: cap.jti, ...(cap.iss ? { iss: cap.iss } : {}), ...(cap.caps ?? {}) };\n    return viewer !== null && typeof viewer === \"object\" && !Array.isArray(viewer) ? { ...(viewer as Record<string, unknown>), caps } : { viewer, caps };\n  }\n\n  private sign(cap: Capability): string {\n    const payload = b64url(Buffer.from(JSON.stringify(cap), \"utf8\"));\n    return `${PREFIX}.${payload}.${b64url(this.hmac(payload))}`;\n  }\n\n  private hmac(payload: string): Buffer {\n    return createHmac(\"sha256\", this.secret).update(`${PREFIX}.${payload}`).digest();\n  }\n}\n\nexport { capabilityAllows } from \"./capability-scope.ts\";\n"]}

package/context.d.ts

@@ -0,0 +1,74 @@
+import type { Expr, Shape } from "@rayfold/schema";
+import type { RequestMeta } from "./protocol.js";
+/** In-process event bus used for `emits` and for streams that subscribe to events. */
+export declare class EventBus {
+    private readonly subs;
+    private seq;
+    publish(name: string, payload: Record<string, unknown>): void;
+    on(name: string, fn: (payload: unknown) => void): () => void;
+    /** Async iterator over an event; ends when `signal` aborts. Buffers between pulls. */
+    subscribe<T = unknown>(name: string, signal?: AbortSignal): AsyncIterable<T>;
+}
+export interface PolicyHint {
+    /** Pushable read policy for the type being loaded, if any (spec 06 §4). */
+    filter?: Expr;
+}
+/** What every resolver receives. `V` is the server's viewer type. */
+export interface RayfoldContext<V = unknown> {
+    viewer: V;
+    signal: AbortSignal;
+    simulate: boolean;
+    /** Compact wire mode requested by the client (spec 04 section 1). */
+    compact?: boolean;
+    /** Expected version for a conditional command (spec 03 section 4a). */
+    ifVersion?: string | number;
+    /**
+     * Conditional-write check: throws VersionConflict when the request carried `ifVersion` and it differs
+     * from `actual`. `current` is the entity as stored; it is returned to the client in the op's shape.
+     */
+    checkVersion(key: string, actual: unknown, current: unknown): void;
+    events: EventBus;
+    meta: RequestMeta;
+    opId: number;
+    opName: string;
+    policy: PolicyHint;
+    /** The shape this op asked for, so an adapter can plan a whole screen at once (spec 02). */
+    shape?: Shape;
+    /** Values for `$name` references in the op's shape. */
+    vars?: Record<string, unknown>;
+    /** Per-request scratch space (e.g. per-request loader caches). */
+    state: Map<string, unknown>;
+    /**
+     * Scratch space shared by every op of the batch. The executor keeps loaded field values here, so an entity one op
+     * already loaded is not loaded again by another op of the same request (spec 03 section 2).
+     */
+    batch: Map<string, unknown>;
+    /** Wall clock, injectable for tests. */
+    now: () => number;
+}
+export interface IdempotencyRecord {
+    argsHash: string;
+    /** the full ok frame */
+    frame: unknown;
+    /** the same result in compact form, for retries that ask for compact frames */
+    compactFrame?: unknown;
+    at: number;
+}
+export interface IdempotencyStore {
+    get(scope: string, key: string): Promise<IdempotencyRecord | undefined>;
+    put(scope: string, key: string, record: IdempotencyRecord): Promise<void>;
+}
+/**
+ * In-memory idempotency records. Records expire after `ttlMs`; expired ones are dropped on read and swept on every
+ * write, and past `maxEntries` the oldest go first, so memory stays bounded however many commands arrive.
+ */
+export declare class MemoryIdempotencyStore implements IdempotencyStore {
+    private readonly ttlMs;
+    private readonly now;
+    private readonly maxEntries;
+    private readonly map;
+    constructor(ttlMs?: number, now?: () => number, maxEntries?: number);
+    get(scope: string, key: string): Promise<IdempotencyRecord | undefined>;
+    put(scope: string, key: string, record: IdempotencyRecord): Promise<void>;
+    get size(): number;
+}