iterate 0.2.7 → 0.3.0

package/dist/next/lib.mjs

@@ -0,0 +1,199 @@
+//#region src/next/lib.ts
+/** A plain Error carrying `code` (+ optional `data`) as own enumerable properties. */
+function codedError(code, message, data) {
+	return Object.assign(new Error(message), data === void 0 ? { code } : {
+		code,
+		data
+	});
+}
+/** The code of an error that crossed any number of hops — undefined for uncoded errors. */
+function errorCode(error) {
+	return typeof error === "object" && error && "code" in error ? error.code : void 0;
+}
+const MAX = {
+	message: 1024,
+	stack: 16384,
+	string: 256,
+	attributeKeys: 32
+};
+/** Print ONE bounded console.error line for an unexpected failure; never throws. */
+function reportIssue(failureSite, caught, attributes) {
+	try {
+		const bounded = {};
+		for (const [key, value] of Object.entries(attributes || {}).slice(0, MAX.attributeKeys)) {
+			if (value === void 0) continue;
+			bounded[key.slice(0, MAX.string)] = typeof value === "string" ? value.slice(0, MAX.string) : value;
+		}
+		const code = errorCode(caught);
+		const error = caught instanceof Error ? {
+			type: (caught.name || "Error").slice(0, MAX.string),
+			message: caught.message.slice(0, MAX.message),
+			...caught.stack && { stack: caught.stack.slice(0, MAX.stack) }
+		} : typeof caught === "object" && caught ? { type: "ObjectThrown" } : {
+			type: `${typeof caught}Thrown`,
+			message: String(caught).slice(0, MAX.message)
+		};
+		console.error({
+			...bounded,
+			event: "issue",
+			failureSite: failureSite.slice(0, MAX.string),
+			code,
+			error
+		});
+	} catch {}
+}
+const isRecord = (v) => typeof v === "object" && !!v && !Array.isArray(v);
+const escape = (seg) => String(seg).replaceAll("~", "~0").replaceAll("/", "~1");
+/** Structural deep-equal over plain JSON values — order-insensitive, unbudgeted (JSON is acyclic).
+*  THE one deep-equal: the live-state diff's "don't emit" test AND the idempotency-body compare
+*  (re-exported through stream/processor.ts). The `Object.hasOwn(b, k)` guard is load-bearing — without
+*  it, two objects with the same key COUNT but different key SETS compare equal. */
+function jsonEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => jsonEqual(v, b[i]));
+	if (isRecord(a) && isRecord(b)) {
+		const ka = Object.keys(a);
+		return ka.length === Object.keys(b).length && ka.every((k) => Object.hasOwn(b, k) && jsonEqual(a[k], b[k]));
+	}
+	return false;
+}
+/** Structural diff `a → b`, or undefined when deep-equal (the producer's "don't emit" signal).
+*  Objects recurse per key; arrays get the chat-log fast paths (pure append → `add …/-` ops,
+*  pure tail-truncate → `remove` ops) and are replaced wholesale on any middle divergence —
+*  the LiveView trade: optimize the growing log, full-render the rewrite.
+*  Both sides are JSON-normalized first — the wire is JSON, so the diff must see exactly what
+*  the wire will carry: undefined-valued keys vanish, Dates become their ISO strings, array
+*  holes become null. Diffing what you didn't normalize is how a Date change goes silent. */
+function diff(a, b) {
+	const json = (v) => {
+		const s = JSON.stringify(v);
+		return s ? JSON.parse(s) : void 0;
+	};
+	return walk(json(a), json(b), "");
+}
+function walk(a, b, path) {
+	if (jsonEqual(a, b)) return void 0;
+	if (Array.isArray(a) && Array.isArray(b)) {
+		const shared = Math.min(a.length, b.length);
+		let p = 0;
+		while (p < shared && jsonEqual(a[p], b[p])) p++;
+		if (p === a.length) return b.slice(p).map((value) => ({
+			op: "add",
+			path: `${path}/-`,
+			value
+		}));
+		if (p === b.length) return a.slice(p).map((_, i) => ({
+			op: "remove",
+			path: `${path}/${a.length - 1 - i}`
+		}));
+		return [{
+			op: "replace",
+			path,
+			value: b
+		}];
+	}
+	if (isRecord(a) && isRecord(b)) {
+		const ops = [];
+		for (const k of Object.keys(a)) if (!Object.hasOwn(b, k)) ops.push({
+			op: "remove",
+			path: `${path}/${escape(k)}`
+		});
+		for (const k of Object.keys(b)) if (!Object.hasOwn(a, k)) ops.push({
+			op: "add",
+			path: `${path}/${escape(k)}`,
+			value: b[k]
+		});
+		else ops.push(...walk(a[k], b[k], `${path}/${escape(k)}`) ?? []);
+		return ops.length ? ops : void 0;
+	}
+	return [{
+		op: "replace",
+		path,
+		value: b
+	}];
+}
+/** Apply a patch non-mutatingly (clone-then-mutate). The client half of `diff` — exported
+*  through the SDK so subscribers need no third-party json-patch dependency. */
+function applyPatch(doc, ops) {
+	let root = structuredClone(doc);
+	for (const op of ops) {
+		if (op.path === "") {
+			if (op.op === "remove") throw new Error("applyPatch: cannot remove the document root");
+			root = op.value;
+			continue;
+		}
+		const segs = op.path.slice(1).split("/").map((s) => s.replaceAll("~1", "/").replaceAll("~0", "~"));
+		for (const s of segs) if (s === "__proto__") throw new Error(`applyPatch: refusing __proto__ in path ${op.path}`);
+		const last = segs.pop();
+		let parent = root;
+		for (const s of segs) {
+			parent = Array.isArray(parent) ? parent[Number(s)] : isRecord(parent) && Object.hasOwn(parent, s) ? parent[s] : void 0;
+			if (parent === void 0) throw new Error(`applyPatch: missing path ${op.path}`);
+		}
+		if (Array.isArray(parent)) if (op.op === "add") if (last === "-") parent.push(op.value);
+		else parent.splice(Number(last), 0, op.value);
+		else if (op.op === "replace") parent[Number(last)] = op.value;
+		else parent.splice(Number(last), 1);
+		else if (isRecord(parent)) if (op.op === "remove") delete parent[last];
+		else parent[last] = op.value;
+		else throw new Error(`applyPatch: path ${op.path} traverses a non-container`);
+	}
+	return root;
+}
+async function withTimeout(promise, ms, what) {
+	let timer;
+	try {
+		return await Promise.race([promise, new Promise((_, reject) => {
+			timer = setTimeout(() => reject(codedError("TIMEOUT", `${typeof what === "function" ? what() : what}: no answer in ${ms / 1e3}s`)), ms);
+		})]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+/** Whether `request` may spend the cookies it carries: its `Origin` header is this origin, or absent
+*  (a non-browser client — curl, a script). A browser stamps the page's origin on every WebSocket
+*  handshake, every cross-site fetch and every form POST, so a foreign origin means a foreign site
+*  drove the request with the visitor's cookie riding along. A malformed `Origin` (the literal
+*  `null` of a sandboxed document included) is foreign. */
+function isSameOriginBrowserRequest(request) {
+	const origin = request.headers.get("origin");
+	if (origin === null) return true;
+	try {
+		return new URL(origin).origin === new URL(request.url).origin;
+	} catch {
+		return false;
+	}
+}
+/** `next` as a path on `origin`, else "/" — a redirect never leaves the host: `//evil.example`,
+*  `/\evil.example` and an absolute URL all resolve to a foreign origin and fall back to "/". The
+*  issuer's login redirect uses it too (os-next issuer-pages.ts). */
+function sameOriginPath(next, origin) {
+	try {
+		const url = new URL(next, origin);
+		return url.origin === origin ? url.pathname + url.search : "/";
+	} catch {
+		return "/";
+	}
+}
+/** Only plain HTTP loopback origins use development login and client registration. */
+function isLocalOrigin(origin) {
+	const url = new URL(origin);
+	return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname.endsWith(".localhost") || url.hostname === "127.0.0.1");
+}
+/** Resolve a `cd` target against a context's own path — the one resolver every `cd` (the edge
+*  method, the built-in root, the library's relative handles) shares. Absolute ("/agents/x") stands alone; relative
+*  ("agents/x", "../inbox", ".") joins onto `base`. `.` and `..` resolve; the root cannot be
+*  escaped ("/.." is "/"). The result is canonical: leading slash, no trailing slash but for "/". */
+function resolveContextPath(basePath, contextPath) {
+	const segments = [];
+	for (const seg of `${contextPath.startsWith("/") ? "" : basePath}/${contextPath}`.split("/")) {
+		if (seg === "" || seg === ".") continue;
+		if (seg === "..") segments.pop();
+		else segments.push(seg);
+	}
+	return `/${segments.join("/")}`;
+}
+//#endregion
+export { applyPatch, codedError, diff, errorCode, isLocalOrigin, isSameOriginBrowserRequest, jsonEqual, reportIssue, resolveContextPath, sameOriginPath, withTimeout };
+
+//# sourceMappingURL=lib.mjs.map

package/dist/next/lib.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.mjs","names":[],"sources":["../../src/next/lib.ts"],"sourcesContent":["// lib.ts — the pure helpers every layer shares; four concepts, one platform-neutral file (it rides\n// the SDK bundle and the node unit lane, so no cloudflare:workers here):\n//   errors  — `codedError` / `errorCode` / `reportIssue`: THE machine-readable error channel\n//   patch   — `diff` / `applyPatch` / `jsonEqual`: the live-state delta (an RFC 6902 subset)\n//   timeout — `withTimeout`: a promise raced against a deadline (code TIMEOUT)\n//   origin  — `isSameOriginBrowserRequest`: may a request spend the cookies it carries\n\n// ── errors ── THE machine-readable error channel, after cloudflare-os\n// (workshop-shared/src/api.ts: plain Error + a `code` own-property via Object.assign, read with\n// `\"code\" in error`). Why this shape and no other: capnweb coerces custom error NAMES to a\n// builtin whitelist and drops subclass identity, but preserves ALL own enumerable properties\n// across the wire (verified at runtime against @iterate-com/capnweb 0.10.0) — and with\n// enhanced_error_serialization (our compat date) own props survive native Workers-RPC hops too.\n// So: never classify by `name`, `instanceof`, or message regex across a hop; check the code.\n// Human messages stay verbatim and greppable — the code rides beside them, never instead.\n// workerd's own stamped flags (`.retryable`, `.overloaded`, `.durableObjectReset`) ride the same\n// own-property channel; honor them rather than inventing a retry taxonomy.\n\n/** The stable machine-readable codes — SCREAMING_SNAKE, defined once, both ends import this. */\ntype ErrorCode =\n  | \"SCHEDULE_LIMIT\" // bounded pending/failed scheduled batches per context\n  | \"INVALID_INPUT\"\n  | \"IDENTITY_CONFLICT\" // verified login cannot replace another linked identity\n  | \"GRANT_NOT_FOUND\" // a caller may revoke only a grant in their own inventory\n  | \"NO_ITX_EXPRESSION_MATCH\" // no rewrite rule matches the call (default-deny)\n  | \"IDEMPOTENCY_CONFLICT\"\n  | \"OFFSET_CONFLICT\" // an input's expected `offset` is not the offset it would land at\n  | \"EVENT_TOO_LARGE\" // one event's serialized body is over the append ceiling (stream.ts EVENT_BODY_MAX_CHARS)\n  | \"REDUCE_CHECKPOINT_TOO_LARGE\" // a reduce's state would not fit one storage cell (stream/processor.ts)\n  | \"EVENT_UNREADABLE\" // a stored row's body is not JSON — `data.offset` names it (stream.ts read)\n  | \"STREAM_PAUSED\"\n  | \"INVALID_CONTEXT\" // a context name / project id the codec refuses (iterate-context.ts `DurableObjectNameCodec`) — coded, so it survives the hop\n  | \"EXPRESSION_TOO_LONG\" // a STRING itx expression over ITX_EXPRESSION_STRING_MAX_CHARS — pass the parsed form\n  | \"FACET_SOURCE_TOO_LARGE\" // a facet's literal source over FACET_SOURCE_MAX_CHARS (worker-loader.ts) — refused at the door\n  | \"INVALID_CREDENTIALS\" // authenticate(): the admin secret did not match, or the credentials named no known kind\n  | \"UNAUTHENTICATED\" // authenticate({ type: \"from-server-cookie\" }): no session cookie on the request, or a cross-origin browser's request\n  | \"FORBIDDEN\" // projects.get(project): outside the session's reach (a grant narrowed to other projects, or the user is no member of its org); create on a narrowed grant; grants/consent on a session that carries none; organizations.get outside the session's memberships; `cd` in the global namespace (a global context is reached by identity, never by path)\n  | \"PROJECT_NAME_TAKEN\" // projects.create({ project }): a project of that slug exists in another org\n  | \"RPC_STUB_OFFLINE\" // the rpc stub a row names is neither borrowed nor pager-backed right now — or its lend ended mid-call (recalled, returned, broken; the relay re-codes)\n  | \"NOT_A_METHOD\" // the dotted path's terminal segment is not callable on the target\n  | \"NO_FACET\" // no facet of that name has been loaded into this context\n  | \"FACET_NO_UPGRADE\" // a WebSocket upgrade aimed at a facet: a facet answers RPC and plain HTTP, never a socket — sockets terminate at the edge (apps/os-next context/facet-host.ts)\n  | \"WAIT_TIMEOUT\" // waitForEvent expired with no matching event committed\n  | \"TIMEOUT\"; // lib.ts withTimeout: the call did not answer within its deadline\n// (There is no separate boundary-validation library: the append door's own runtime guards\n// throw plain Errors; a client is JUST capnweb, so malformed args surface as ordinary errors.)\n\n/** A plain Error carrying `code` (+ optional `data`) as own enumerable properties. */\nexport function codedError(code: ErrorCode, message: string, data?: unknown): Error {\n  return Object.assign(new Error(message), data === undefined ? { code } : { code, data });\n}\n\n/** The code of an error that crossed any number of hops — undefined for uncoded errors. */\nexport function errorCode(error: unknown): ErrorCode | undefined {\n  return typeof error === \"object\" && error && \"code\" in error\n    ? ((error as { code: unknown }).code as ErrorCode)\n    : undefined;\n}\n\n// reportIssue — the ONE exit for unexpected failures (cloudflare-os error-reporting.ts, minus\n// its private Reporter Worker): one bounded console.error line; query event=\"issue\" in Workers\n// Logs. The Reporter seam stayed out on purpose — when one exists, check an optional env\n// binding HERE and waitUntil the dispatch; capture sites never change. Deliberately NO\n// cloudflare:workers import: this file rides the platform-neutral SDK bundle. Reporting must\n// never disturb the caller — armored end to end; worst case it prints nothing.\n\n// Bounds verbatim from cloudflare-os: hostile strings get clipped, never explode a log line.\nconst MAX = { message: 1024, stack: 16_384, string: 256, attributeKeys: 32 } as const;\ntype Scalar = string | number | boolean | null; // attribute values stay queryable scalars\n\n/** Print ONE bounded console.error line for an unexpected failure; never throws. */\nexport function reportIssue(\n  failureSite: string,\n  caught: unknown,\n  attributes?: Record<string, Scalar | undefined>,\n): void {\n  try {\n    const bounded: Record<string, Scalar> = {};\n    for (const [key, value] of Object.entries(attributes || {}).slice(0, MAX.attributeKeys)) {\n      if (value === undefined) continue;\n      bounded[key.slice(0, MAX.string)] =\n        typeof value === \"string\" ? value.slice(0, MAX.string) : value;\n    }\n    const code = errorCode(caught);\n    // The thrown value, bounded — name/message/stack read off an Error; an arbitrary object is\n    // never walked.\n    const error =\n      caught instanceof Error\n        ? {\n            type: (caught.name || \"Error\").slice(0, MAX.string),\n            message: caught.message.slice(0, MAX.message),\n            ...(caught.stack && { stack: caught.stack.slice(0, MAX.stack) }),\n          }\n        : typeof caught === \"object\" && caught\n          ? { type: \"ObjectThrown\" }\n          : { type: `${typeof caught}Thrown`, message: String(caught).slice(0, MAX.message) };\n    console.error({\n      ...bounded, // fixed keys spread last so an attribute can never shadow them\n      event: \"issue\",\n      failureSite: failureSite.slice(0, MAX.string),\n      code,\n      error,\n    });\n  } catch {\n    // Reporting must never disturb the caller — swallow and move on.\n  }\n}\n\n// ── patch ── the LiveView-style delta that rides every live-state change event. `diff` runs at\n// the PRODUCER (the processor's reduce, the mini-app helper's set) where old and new value are\n// both in hand; the stream forwards the ops verbatim; only CLIENTS apply them. The format is an\n// RFC 6902 subset (add / replace / remove, JSON-Pointer paths) so any off-the-shelf json-patch\n// library applies our patch payloads — we invent no wire format, we just never emit the exotic ops.\n\nexport type PatchOp =\n  | { op: \"add\"; path: string; value: unknown }\n  | { op: \"replace\"; path: string; value: unknown }\n  | { op: \"remove\"; path: string };\n\nconst isRecord = (v: unknown): v is Record<string, unknown> =>\n  typeof v === \"object\" && !!v && !Array.isArray(v);\n\nconst escape = (seg: string | number): string =>\n  String(seg).replaceAll(\"~\", \"~0\").replaceAll(\"/\", \"~1\");\n\n/** Structural deep-equal over plain JSON values — order-insensitive, unbudgeted (JSON is acyclic).\n *  THE one deep-equal: the live-state diff's \"don't emit\" test AND the idempotency-body compare\n *  (re-exported through stream/processor.ts). The `Object.hasOwn(b, k)` guard is load-bearing — without\n *  it, two objects with the same key COUNT but different key SETS compare equal. */\nexport function jsonEqual(a: unknown, b: unknown): boolean {\n  if (Object.is(a, b)) return true;\n  if (Array.isArray(a) && Array.isArray(b))\n    return a.length === b.length && a.every((v, i) => jsonEqual(v, b[i]));\n  if (isRecord(a) && isRecord(b)) {\n    const ka = Object.keys(a);\n    return (\n      ka.length === Object.keys(b).length &&\n      ka.every((k) => Object.hasOwn(b, k) && jsonEqual(a[k], b[k]))\n    );\n  }\n  return false;\n}\n\n/** Structural diff `a → b`, or undefined when deep-equal (the producer's \"don't emit\" signal).\n *  Objects recurse per key; arrays get the chat-log fast paths (pure append → `add …/-` ops,\n *  pure tail-truncate → `remove` ops) and are replaced wholesale on any middle divergence —\n *  the LiveView trade: optimize the growing log, full-render the rewrite.\n *  Both sides are JSON-normalized first — the wire is JSON, so the diff must see exactly what\n *  the wire will carry: undefined-valued keys vanish, Dates become their ISO strings, array\n *  holes become null. Diffing what you didn't normalize is how a Date change goes silent. */\nexport function diff(a: unknown, b: unknown): PatchOp[] | undefined {\n  // stringify can itself return undefined (a bare function, toJSON() → undefined) — parse\n  // would then throw SyntaxError('\"undefined\" is not valid JSON'); treat those as absent.\n  const json = (v: unknown) => {\n    const s = JSON.stringify(v);\n    return s ? (JSON.parse(s) as unknown) : undefined;\n  };\n  return walk(json(a), json(b), \"\");\n}\n\nfunction walk(a: unknown, b: unknown, path: string): PatchOp[] | undefined {\n  if (jsonEqual(a, b)) return undefined;\n  if (Array.isArray(a) && Array.isArray(b)) {\n    const shared = Math.min(a.length, b.length);\n    let p = 0;\n    while (p < shared && jsonEqual(a[p], b[p])) p++;\n    if (p === a.length) return b.slice(p).map((value) => ({ op: \"add\", path: `${path}/-`, value }));\n    if (p === b.length)\n      return a\n        .slice(p)\n        .map((_, i) => ({ op: \"remove\", path: `${path}/${a.length - 1 - i}` }) as const);\n    return [{ op: \"replace\", path, value: b }];\n  }\n  if (isRecord(a) && isRecord(b)) {\n    const ops: PatchOp[] = [];\n    for (const k of Object.keys(a))\n      if (!Object.hasOwn(b, k)) ops.push({ op: \"remove\", path: `${path}/${escape(k)}` });\n    for (const k of Object.keys(b)) {\n      if (!Object.hasOwn(a, k)) ops.push({ op: \"add\", path: `${path}/${escape(k)}`, value: b[k] });\n      else ops.push(...(walk(a[k], b[k], `${path}/${escape(k)}`) ?? []));\n    }\n    return ops.length ? ops : undefined;\n  }\n  return [{ op: \"replace\", path, value: b }];\n}\n\n/** Apply a patch non-mutatingly (clone-then-mutate). The client half of `diff` — exported\n *  through the SDK so subscribers need no third-party json-patch dependency. */\nexport function applyPatch<T>(doc: T, ops: PatchOp[]): T {\n  let root: unknown = structuredClone(doc);\n  for (const op of ops) {\n    if (op.path === \"\") {\n      if (op.op === \"remove\") throw new Error(\"applyPatch: cannot remove the document root\");\n      root = op.value;\n      continue;\n    }\n    const segs = op.path\n      .slice(1)\n      .split(\"/\")\n      .map((s) => s.replaceAll(\"~1\", \"/\").replaceAll(\"~0\", \"~\"));\n    // Patches arrive over the wire. \"__proto__\" is refused outright (assigning it invokes the\n    // prototype setter, not a property write); other prototype members (\"constructor\", …) are\n    // ordinary keys — traversal below is own-property-only, so the chain is never walked.\n    for (const s of segs)\n      if (s === \"__proto__\") throw new Error(`applyPatch: refusing __proto__ in path ${op.path}`);\n    const last = segs.pop()!;\n    let parent: unknown = root;\n    for (const s of segs) {\n      parent = Array.isArray(parent)\n        ? parent[Number(s)]\n        : isRecord(parent) && Object.hasOwn(parent, s)\n          ? parent[s]\n          : undefined;\n      if (parent === undefined) throw new Error(`applyPatch: missing path ${op.path}`);\n    }\n    if (Array.isArray(parent)) {\n      if (op.op === \"add\") {\n        if (last === \"-\") parent.push(op.value);\n        else parent.splice(Number(last), 0, op.value);\n      } else if (op.op === \"replace\") parent[Number(last)] = op.value;\n      else parent.splice(Number(last), 1);\n    } else if (isRecord(parent)) {\n      if (op.op === \"remove\") delete parent[last];\n      else parent[last] = op.value;\n    } else throw new Error(`applyPatch: path ${op.path} traverses a non-container`);\n  }\n  return root as T;\n}\n\n// ── timeout ── race a promise against a deadline. The timer is CLEARED on every exit: a leaked\n// timer per call would pin a Durable Object awake. A loss rejects with code TIMEOUT so a caller can\n// tell \"took too long\" from the call's own failure (the DO's facet watchdog aborts the facet on it).\n//\n// `what` may be a THUNK: a label whose construction is expensive (the facet watchdog prints the whole\n// pushed batch) is built ONLY when the deadline is actually lost, off the per-call hot path.\n\nexport async function withTimeout<T>(\n  promise: Promise<T>,\n  ms: number,\n  what: string | (() => string),\n): Promise<T> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  try {\n    return await Promise.race([\n      promise,\n      new Promise<never>((_, reject) => {\n        timer = setTimeout(\n          () =>\n            reject(\n              codedError(\n                \"TIMEOUT\",\n                `${typeof what === \"function\" ? what() : what}: no answer in ${ms / 1000}s`,\n              ),\n            ),\n          ms,\n        );\n      }),\n    ]);\n  } finally {\n    if (timer) clearTimeout(timer);\n  }\n}\n\n// ── origin ── the one check that makes an ambient cookie safe to honour (session.ts\n// `from-server-cookie`, the issuer's form posts in os-next issuer-pages.ts).\n\n/** Whether `request` may spend the cookies it carries: its `Origin` header is this origin, or absent\n *  (a non-browser client — curl, a script). A browser stamps the page's origin on every WebSocket\n *  handshake, every cross-site fetch and every form POST, so a foreign origin means a foreign site\n *  drove the request with the visitor's cookie riding along. A malformed `Origin` (the literal\n *  `null` of a sandboxed document included) is foreign. */\nexport function isSameOriginBrowserRequest(request: Pick<Request, \"url\" | \"headers\">): boolean {\n  const origin = request.headers.get(\"origin\");\n  // oxlint-disable-next-line iterate/simple-truthiness-check -- security: only a truly absent Origin (non-browser client) is trusted; an empty \"\" Origin header must stay foreign, which a truthiness check would wrongly accept\n  if (origin === null) return true;\n  try {\n    return new URL(origin).origin === new URL(request.url).origin;\n  } catch {\n    return false;\n  }\n}\n\n/** `next` as a path on `origin`, else \"/\" — a redirect never leaves the host: `//evil.example`,\n *  `/\\evil.example` and an absolute URL all resolve to a foreign origin and fall back to \"/\". The\n *  issuer's login redirect uses it too (os-next issuer-pages.ts). */\nexport function sameOriginPath(next: string, origin: string): string {\n  try {\n    const url = new URL(next, origin);\n    return url.origin === origin ? url.pathname + url.search : \"/\";\n  } catch {\n    return \"/\";\n  }\n}\n\n/** Only plain HTTP loopback origins use development login and client registration. */\nexport function isLocalOrigin(origin: string) {\n  const url = new URL(origin);\n  return (\n    url.protocol === \"http:\" &&\n    (url.hostname === \"localhost\" ||\n      url.hostname.endsWith(\".localhost\") ||\n      url.hostname === \"127.0.0.1\")\n  );\n}\n\n/** Resolve a `cd` target against a context's own path — the one resolver every `cd` (the edge\n *  method, the built-in root, the library's relative handles) shares. Absolute (\"/agents/x\") stands alone; relative\n *  (\"agents/x\", \"../inbox\", \".\") joins onto `base`. `.` and `..` resolve; the root cannot be\n *  escaped (\"/..\" is \"/\"). The result is canonical: leading slash, no trailing slash but for \"/\". */\nexport function resolveContextPath(basePath: string, contextPath: string): string {\n  const segments: string[] = [];\n  for (const seg of `${contextPath.startsWith(\"/\") ? \"\" : basePath}/${contextPath}`.split(\"/\")) {\n    if (seg === \"\" || seg === \".\") continue;\n    if (seg === \"..\") segments.pop();\n    else segments.push(seg);\n  }\n  return `/${segments.join(\"/\")}`;\n}\n"],"mappings":"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"}

package/dist/next/oauth-scopes.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+/** The platform's OAuth scopes — what an app may ask for and what a consent grants:
+ *   - `iterate`             — reach the projects the person grants (every app; implied, always granted)
+ *   - `account`             — manage the person's sessions and personal access tokens
+ *   - `organizations:write` — the person's organizations: list every one they belong to, create new ones
+ *  Consent is task-based (the shape Cloudflare's own OAuth consent took in August 2026: a client
+ *  requests a set, the person may deselect the optional ones, the token carries what was granted):
+ *  `iterate` is required, every other requested scope is optional on the consent page, and an app
+ *  reads the granted set from `session.info().scopes` rather than assuming its request. */
+export declare const OAuthScope: z.ZodEnum<{
+    iterate: "iterate";
+    account: "account";
+    "organizations:write": "organizations:write";
+}>;
+export type OAuthScope = z.infer<typeof OAuthScope>;
+export declare const OAuthScopes: z.ZodPipe<z.ZodArray<z.ZodEnum<{
+    iterate: "iterate";
+    account: "account";
+    "organizations:write": "organizations:write";
+}>>, z.ZodTransform<string[], ("iterate" | "account" | "organizations:write")[]>>;
+/** A requested scope as the consent page shows it: its name, what it means to the person, and
+ *  whether they may untick it (`iterate` never). */
+export interface ConsentScope {
+    name: OAuthScope;
+    title: string;
+    note: string;
+    required: boolean;
+}
+/** What each scope means to the person — the consent page's copy, sent with `consent.describe` so
+ *  the page renders what it is given: a scope added to `OAuthScope` is described here or it does
+ *  not compile. */
+export declare const OAuthScopeDescriptions: Record<OAuthScope, Omit<ConsentScope, "name">>;

package/dist/next/oauth-scopes.mjs

@@ -0,0 +1,40 @@
+import { z } from "zod";
+//#region src/next/oauth-scopes.ts
+/** The platform's OAuth scopes — what an app may ask for and what a consent grants:
+*   - `iterate`             — reach the projects the person grants (every app; implied, always granted)
+*   - `account`             — manage the person's sessions and personal access tokens
+*   - `organizations:write` — the person's organizations: list every one they belong to, create new ones
+*  Consent is task-based (the shape Cloudflare's own OAuth consent took in August 2026: a client
+*  requests a set, the person may deselect the optional ones, the token carries what was granted):
+*  `iterate` is required, every other requested scope is optional on the consent page, and an app
+*  reads the granted set from `session.info().scopes` rather than assuming its request. */
+const OAuthScope = z.enum([
+	"iterate",
+	"account",
+	"organizations:write"
+]);
+const OAuthScopes = z.array(OAuthScope).transform((scopes) => [...new Set(["iterate", ...scopes])]);
+/** What each scope means to the person — the consent page's copy, sent with `consent.describe` so
+*  the page renders what it is given: a scope added to `OAuthScope` is described here or it does
+*  not compile. */
+const OAuthScopeDescriptions = {
+	iterate: {
+		title: "Read and make changes in the projects you grant it",
+		note: "Required — what the app is for.",
+		required: true
+	},
+	account: {
+		title: "See and end your sessions, and mint personal access tokens",
+		note: "Optional.",
+		required: false
+	},
+	"organizations:write": {
+		title: "See all your organizations and create new ones",
+		note: "Optional.",
+		required: false
+	}
+};
+//#endregion
+export { OAuthScope, OAuthScopeDescriptions, OAuthScopes };
+
+//# sourceMappingURL=oauth-scopes.mjs.map

package/dist/next/oauth-scopes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-scopes.mjs","names":[],"sources":["../../src/next/oauth-scopes.ts"],"sourcesContent":["import { z } from \"zod\";\n\n/** The platform's OAuth scopes — what an app may ask for and what a consent grants:\n *   - `iterate`             — reach the projects the person grants (every app; implied, always granted)\n *   - `account`             — manage the person's sessions and personal access tokens\n *   - `organizations:write` — the person's organizations: list every one they belong to, create new ones\n *  Consent is task-based (the shape Cloudflare's own OAuth consent took in August 2026: a client\n *  requests a set, the person may deselect the optional ones, the token carries what was granted):\n *  `iterate` is required, every other requested scope is optional on the consent page, and an app\n *  reads the granted set from `session.info().scopes` rather than assuming its request. */\nexport const OAuthScope = z.enum([\"iterate\", \"account\", \"organizations:write\"]);\nexport type OAuthScope = z.infer<typeof OAuthScope>;\n\nexport const OAuthScopes = z\n  .array(OAuthScope)\n  .transform((scopes) => [...new Set([\"iterate\", ...scopes])]);\n\n/** A requested scope as the consent page shows it: its name, what it means to the person, and\n *  whether they may untick it (`iterate` never). */\nexport interface ConsentScope {\n  name: OAuthScope;\n  title: string;\n  note: string;\n  required: boolean;\n}\n\n/** What each scope means to the person — the consent page's copy, sent with `consent.describe` so\n *  the page renders what it is given: a scope added to `OAuthScope` is described here or it does\n *  not compile. */\nexport const OAuthScopeDescriptions: Record<OAuthScope, Omit<ConsentScope, \"name\">> = {\n  iterate: {\n    title: \"Read and make changes in the projects you grant it\",\n    note: \"Required — what the app is for.\",\n    required: true,\n  },\n  account: {\n    title: \"See and end your sessions, and mint personal access tokens\",\n    note: \"Optional.\",\n    required: false,\n  },\n  \"organizations:write\": {\n    title: \"See all your organizations and create new ones\",\n    note: \"Optional.\",\n    required: false,\n  },\n};\n"],"mappings":";;;;;;;;;;AAUA,MAAa,aAAa,EAAE,KAAK;CAAC;CAAW;CAAW;AAAqB,CAAC;AAG9E,MAAa,cAAc,EACxB,MAAM,UAAU,CAAC,CACjB,WAAW,WAAW,CAAC,GAAG,IAAI,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,CAAC,CAAC;;;;AAc7D,MAAa,yBAAyE;CACpF,SAAS;EACP,OAAO;EACP,MAAM;EACN,UAAU;CACZ;CACA,SAAS;EACP,OAAO;EACP,MAAM;EACN,UAAU;CACZ;CACA,uBAAuB;EACrB,OAAO;EACP,MAAM;EACN,UAAU;CACZ;AACF"}

package/dist/next/oauth.mjs

@@ -0,0 +1,29 @@
+import { OAuthScopes } from "./oauth-scopes.mjs";
+import * as oauth from "oauth4webapi";
+//#region src/next/client/oauth.ts
+/** The same code/PKCE parameters for browser login and a console-minted token. */
+async function authorizationCodeRequest(input) {
+	const verifier = oauth.generateRandomCodeVerifier();
+	const challenge = await oauth.calculatePKCECodeChallenge(verifier);
+	const state = oauth.generateRandomState();
+	const url = new URL("/oauth2/auth", input.issuer);
+	url.search = new URLSearchParams({
+		response_type: "code",
+		client_id: input.clientId,
+		redirect_uri: input.redirectUri,
+		scope: OAuthScopes.parse(input.scopes || []).join(" "),
+		state,
+		code_challenge: challenge,
+		code_challenge_method: "S256"
+	}).toString();
+	for (const resource of input.resources) url.searchParams.append("resource", resource);
+	return {
+		url,
+		state,
+		verifier
+	};
+}
+//#endregion
+export { authorizationCodeRequest };
+
+//# sourceMappingURL=oauth.mjs.map

package/dist/next/oauth.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.mjs","names":[],"sources":["../../src/next/client/oauth.ts"],"sourcesContent":["import * as oauth from \"oauth4webapi\";\nimport { OAuthScopes } from \"../oauth-scopes.ts\";\n\n/** The same code/PKCE parameters for browser login and a console-minted token. */\nexport async function authorizationCodeRequest(input: {\n  issuer: string;\n  clientId: string;\n  redirectUri: string;\n  resources: string[];\n  scopes?: string[];\n}) {\n  const verifier = oauth.generateRandomCodeVerifier();\n  const challenge = await oauth.calculatePKCECodeChallenge(verifier);\n  const state = oauth.generateRandomState();\n  const url = new URL(\"/oauth2/auth\", input.issuer);\n  url.search = new URLSearchParams({\n    response_type: \"code\",\n    client_id: input.clientId,\n    redirect_uri: input.redirectUri,\n    scope: OAuthScopes.parse(input.scopes || []).join(\" \"),\n    state,\n    code_challenge: challenge,\n    code_challenge_method: \"S256\",\n  }).toString();\n  for (const resource of input.resources) url.searchParams.append(\"resource\", resource);\n  return { url, state, verifier };\n}\n"],"mappings":";;;;AAIA,eAAsB,yBAAyB,OAM5C;CACD,MAAM,WAAW,MAAM,2BAA2B;CAClD,MAAM,YAAY,MAAM,MAAM,2BAA2B,QAAQ;CACjE,MAAM,QAAQ,MAAM,oBAAoB;CACxC,MAAM,MAAM,IAAI,IAAI,gBAAgB,MAAM,MAAM;CAChD,IAAI,SAAS,IAAI,gBAAgB;EAC/B,eAAe;EACf,WAAW,MAAM;EACjB,cAAc,MAAM;EACpB,OAAO,YAAY,MAAM,MAAM,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG;EACrD;EACA,gBAAgB;EAChB,uBAAuB;CACzB,CAAC,CAAC,CAAC,SAAS;CACZ,KAAK,MAAM,YAAY,MAAM,WAAW,IAAI,aAAa,OAAO,YAAY,QAAQ;CACpF,OAAO;EAAE;EAAK;EAAO;CAAS;AAChC"}

package/dist/next/principal.d.ts

@@ -0,0 +1,64 @@
+/** Who is acting: a stable actor id (the control plane's user id) and, when known, an email. */
+export type Principal = {
+    actor: string;
+    email?: string;
+};
+/** WHO is making a call: the acting principal (null = anonymous). The one thing carried through every
+ *  dispatch and every sibling hop (`invoke(call, args, caller)`). Set ONLY by trusted code — the edge
+ *  after admission, the kernel — never by a client: the DO's `invoke` is a Workers-RPC verb, never
+ *  capnweb-exposed, so a client cannot supply its own `Caller`. Authority is inferred FROM the
+ *  principal (no separate scopes/trust field). Global contexts remain non-navigable through
+ *  `cd`, including calls without a principal. */
+export type Caller = {
+    principal: Principal | null;
+    /** THE CONNECTION the principal acts through: the OAuth grant's id — one per connected
+     *  client (a Claude Code install, a dash sign-in, a personal token), the same across every call it
+     *  makes. Absent for the admin secret and the kernel. */
+    grant?: string;
+    /** The context the call ORIGINATED at — stamped by the first `cd` hop and forwarded by every later
+     *  one, so a relative path resolved after a hop (`repos.get('./x')` answered at the root) still
+     *  means the caller's `./x`. Absent until a hop. Its presence also means the complete input
+     *  expression was already admitted: a receiving resolver must not recheck owner-written
+     *  rewrites as loaded code's input. Fresh env.ITX calls never inherit this stamp. */
+    path?: string;
+    /** Set when the caller is LOADED CODE — a worker, a facet, a script — holding a context through
+     *  `env.ITX`. Under it the resolver refuses the fixed point (`itx.builtins…`) and any `cd` above
+     *  the caller's own context on the INPUT expression; rewrites the owner wrote are never subject. */
+    app?: true;
+    /** THE PLATFORM ORIGIN the caller reached the platform on (os-next platform-origin.ts) — what a
+     *  public URL is composed from (`itx.url`, a signed file URL). Absent for a caller with none (a
+     *  loaded worker's `env.ITX`, the kernel); the context then uses the last one it was reached on. */
+    platformOrigin?: string | null;
+};
+/** The header the edge sets on a Request it forwards on a principal's behalf — the ingress after
+ *  the cookie check, a session's terminal `fetch` — and strips from every inbound Request. */
+export declare const ITX_PRINCIPAL_HEADER = "x-itx-principal";
+/** The grant's header beside it (the caller's `grant`), set and stripped exactly where the
+ *  principal's is. */
+export declare const ITX_GRANT_HEADER = "x-itx-grant";
+/** The header a loaded worker's `env.ITX.fetch` sets on the Request it forwards, so the context's
+ *  fetch runs the call as app code; stripped from every Request that arrives from outside. */
+export declare const ITX_APP_HEADER = "x-itx-app";
+/** Originating context of a native fetch forwarded by a trusted context. */
+export declare const ITX_CALLER_PATH_HEADER = "x-itx-caller-path";
+/** The event as the log stores it: `source.principal` and `source.grant` are the platform's — set
+ *  from the admitted caller, client-supplied ones dropped (an anonymous session's event carries
+ *  neither, the kernel's none). */
+export declare function stampCaller<E extends {
+    source?: Record<string, unknown>;
+}>(event: E, caller: Caller): E;
+/** Sign JSON claims: the bounded Google login flow's cookie (identity.ts). */
+export declare function signClaims(claims: unknown, secret: string): Promise<string>;
+/** The claims of a token that is well-formed and signed with `secret` — else null (no reason: a
+ *  caller answers every bad token the same way). A blank secret verifies nothing. The caller checks
+ *  the claims' SHAPE and expiry. */
+export declare function verifyClaims(token: string, secret: string): Promise<unknown>;
+/** The principal the admin secret grants — `{ actor: "admin" }`, every project — when `candidate`
+ *  IS `secret` (`APP_CONFIG_ADMIN_API_SECRET`: at `authenticate({ type: "admin-secret" })`, as a
+ *  lane's bearer and on `/mcp`), else null. Both are SHA-256 hashed and the digests compared in
+ *  constant time. A blank secret matches nothing. */
+export declare function verifyAdminSecret(candidate: string, secret: string): Promise<{
+    actor: "admin";
+} | null>;
+/** The value of the cookie `name` in a `Cookie` header, or null. */
+export declare function cookieValueOf(cookieHeader: string | null, name: string): string | null;

package/dist/next/principal.mjs

@@ -0,0 +1,98 @@
+//#region src/next/principal.ts
+/** The header the edge sets on a Request it forwards on a principal's behalf — the ingress after
+*  the cookie check, a session's terminal `fetch` — and strips from every inbound Request. */
+const ITX_PRINCIPAL_HEADER = "x-itx-principal";
+/** The grant's header beside it (the caller's `grant`), set and stripped exactly where the
+*  principal's is. */
+const ITX_GRANT_HEADER = "x-itx-grant";
+/** The header a loaded worker's `env.ITX.fetch` sets on the Request it forwards, so the context's
+*  fetch runs the call as app code; stripped from every Request that arrives from outside. */
+const ITX_APP_HEADER = "x-itx-app";
+/** Originating context of a native fetch forwarded by a trusted context. */
+const ITX_CALLER_PATH_HEADER = "x-itx-caller-path";
+/** The event as the log stores it: `source.principal` and `source.grant` are the platform's — set
+*  from the admitted caller, client-supplied ones dropped (an anonymous session's event carries
+*  neither, the kernel's none). */
+function stampCaller(event, caller) {
+	const { principal: _clientPrincipal, grant: _clientGrant, ...source } = event.source || {};
+	if (caller.principal) {
+		const stamped = {
+			...source,
+			principal: caller.principal
+		};
+		if (caller.grant) stamped.grant = caller.grant;
+		return {
+			...event,
+			source: stamped
+		};
+	}
+	return Object.keys(source).length > 0 ? {
+		...event,
+		source
+	} : (({ source: _dropped, ...rest }) => rest)(event);
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const base64url = (bytes) => btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+const bytesFromBase64url = (text) => Uint8Array.from(atob(text.replaceAll("-", "+").replaceAll("_", "/").padEnd(Math.ceil(text.length / 4) * 4, "=")), (c) => c.charCodeAt(0));
+async function hmacKey(secret, usage) {
+	return crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, [usage]);
+}
+/** Sign JSON claims: the bounded Google login flow's cookie (identity.ts). */
+async function signClaims(claims, secret) {
+	const payload = base64url(encoder.encode(JSON.stringify(claims)));
+	const signature = await crypto.subtle.sign("HMAC", await hmacKey(secret, "sign"), encoder.encode(payload));
+	return `${payload}.${base64url(new Uint8Array(signature))}`;
+}
+/** The claims of a token that is well-formed and signed with `secret` — else null (no reason: a
+*  caller answers every bad token the same way). A blank secret verifies nothing. The caller checks
+*  the claims' SHAPE and expiry. */
+async function verifyClaims(token, secret) {
+	if (!secret) return null;
+	const dot = token.indexOf(".");
+	if (dot <= 0) return null;
+	const payload = token.slice(0, dot);
+	let signature;
+	let claims;
+	try {
+		signature = bytesFromBase64url(token.slice(dot + 1));
+		claims = JSON.parse(decoder.decode(bytesFromBase64url(payload)));
+	} catch {
+		return null;
+	}
+	return await crypto.subtle.verify("HMAC", await hmacKey(secret, "verify"), signature, encoder.encode(payload)) ? claims : null;
+}
+const sha256 = async (text) => new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(text)));
+/** Whether two digests are the same bytes — every byte compared, no early exit, so neither a
+*  matching prefix nor its length leaks by timing. */
+const digestsEqual = (a, b) => {
+	if (a.length !== b.length) return false;
+	let difference = 0;
+	for (let i = 0; i < a.length; i++) difference |= a[i] ^ b[i];
+	return difference === 0;
+};
+/** The principal the admin secret grants — `{ actor: "admin" }`, every project — when `candidate`
+*  IS `secret` (`APP_CONFIG_ADMIN_API_SECRET`: at `authenticate({ type: "admin-secret" })`, as a
+*  lane's bearer and on `/mcp`), else null. Both are SHA-256 hashed and the digests compared in
+*  constant time. A blank secret matches nothing. */
+async function verifyAdminSecret(candidate, secret) {
+	if (!secret) return null;
+	const [candidateDigest, secretDigest] = await Promise.all([sha256(candidate), sha256(secret)]);
+	return digestsEqual(candidateDigest, secretDigest) ? { actor: "admin" } : null;
+}
+/** The value of the cookie `name` in a `Cookie` header, or null. */
+function cookieValueOf(cookieHeader, name) {
+	for (const part of (cookieHeader || "").split(";")) {
+		const separator = part.indexOf("=");
+		if (separator < 0) continue;
+		if (part.slice(0, separator).trim() === name) return part.slice(separator + 1).trim();
+	}
+	return null;
+}
+//#endregion
+export { ITX_APP_HEADER, ITX_CALLER_PATH_HEADER, ITX_GRANT_HEADER, ITX_PRINCIPAL_HEADER, cookieValueOf, signClaims, stampCaller, verifyAdminSecret, verifyClaims };
+
+//# sourceMappingURL=principal.mjs.map

package/dist/next/principal.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.mjs","names":[],"sources":["../../src/next/principal.ts"],"sourcesContent":["// Verified attribution, the signed-claims codec (the login flow's cookie) and the admin secret's compare.\n\n/** Who is acting: a stable actor id (the control plane's user id) and, when known, an email. */\nexport type Principal = { actor: string; email?: string };\n\n/** WHO is making a call: the acting principal (null = anonymous). The one thing carried through every\n *  dispatch and every sibling hop (`invoke(call, args, caller)`). Set ONLY by trusted code — the edge\n *  after admission, the kernel — never by a client: the DO's `invoke` is a Workers-RPC verb, never\n *  capnweb-exposed, so a client cannot supply its own `Caller`. Authority is inferred FROM the\n *  principal (no separate scopes/trust field). Global contexts remain non-navigable through\n *  `cd`, including calls without a principal. */\nexport type Caller = {\n  principal: Principal | null;\n  /** THE CONNECTION the principal acts through: the OAuth grant's id — one per connected\n   *  client (a Claude Code install, a dash sign-in, a personal token), the same across every call it\n   *  makes. Absent for the admin secret and the kernel. */\n  grant?: string;\n  /** The context the call ORIGINATED at — stamped by the first `cd` hop and forwarded by every later\n   *  one, so a relative path resolved after a hop (`repos.get('./x')` answered at the root) still\n   *  means the caller's `./x`. Absent until a hop. Its presence also means the complete input\n   *  expression was already admitted: a receiving resolver must not recheck owner-written\n   *  rewrites as loaded code's input. Fresh env.ITX calls never inherit this stamp. */\n  path?: string;\n  /** Set when the caller is LOADED CODE — a worker, a facet, a script — holding a context through\n   *  `env.ITX`. Under it the resolver refuses the fixed point (`itx.builtins…`) and any `cd` above\n   *  the caller's own context on the INPUT expression; rewrites the owner wrote are never subject. */\n  app?: true;\n  /** THE PLATFORM ORIGIN the caller reached the platform on (os-next platform-origin.ts) — what a\n   *  public URL is composed from (`itx.url`, a signed file URL). Absent for a caller with none (a\n   *  loaded worker's `env.ITX`, the kernel); the context then uses the last one it was reached on. */\n  platformOrigin?: string | null;\n};\n/** The header the edge sets on a Request it forwards on a principal's behalf — the ingress after\n *  the cookie check, a session's terminal `fetch` — and strips from every inbound Request. */\nexport const ITX_PRINCIPAL_HEADER = \"x-itx-principal\";\n/** The grant's header beside it (the caller's `grant`), set and stripped exactly where the\n *  principal's is. */\nexport const ITX_GRANT_HEADER = \"x-itx-grant\";\n/** The header a loaded worker's `env.ITX.fetch` sets on the Request it forwards, so the context's\n *  fetch runs the call as app code; stripped from every Request that arrives from outside. */\nexport const ITX_APP_HEADER = \"x-itx-app\";\n/** Originating context of a native fetch forwarded by a trusted context. */\nexport const ITX_CALLER_PATH_HEADER = \"x-itx-caller-path\";\n\n/** The event as the log stores it: `source.principal` and `source.grant` are the platform's — set\n *  from the admitted caller, client-supplied ones dropped (an anonymous session's event carries\n *  neither, the kernel's none). */\nexport function stampCaller<E extends { source?: Record<string, unknown> }>(\n  event: E,\n  caller: Caller,\n): E {\n  const { principal: _clientPrincipal, grant: _clientGrant, ...source } = event.source || {};\n  if (caller.principal) {\n    const stamped: Record<string, unknown> = { ...source, principal: caller.principal };\n    if (caller.grant) stamped.grant = caller.grant;\n    return { ...event, source: stamped };\n  }\n  return Object.keys(source).length > 0\n    ? { ...event, source }\n    : (({ source: _dropped, ...rest }) => rest as E)(event);\n}\nconst encoder = new TextEncoder();\nconst decoder = new TextDecoder();\nconst base64url = (bytes: Uint8Array): string =>\n  btoa(String.fromCharCode(...bytes))\n    .replaceAll(\"+\", \"-\")\n    .replaceAll(\"/\", \"_\")\n    .replace(/=+$/, \"\");\nconst bytesFromBase64url = (text: string): Uint8Array<ArrayBuffer> =>\n  Uint8Array.from(\n    atob(\n      text\n        .replaceAll(\"-\", \"+\")\n        .replaceAll(\"_\", \"/\")\n        .padEnd(Math.ceil(text.length / 4) * 4, \"=\"),\n    ),\n    (c) => c.charCodeAt(0),\n  );\n\nasync function hmacKey(secret: string, usage: \"sign\" | \"verify\"): Promise<CryptoKey> {\n  return crypto.subtle.importKey(\n    \"raw\",\n    encoder.encode(secret),\n    { name: \"HMAC\", hash: \"SHA-256\" },\n    false,\n    [usage],\n  );\n}\n\n/** Sign JSON claims: the bounded Google login flow's cookie (identity.ts). */\nexport async function signClaims(claims: unknown, secret: string): Promise<string> {\n  const payload = base64url(encoder.encode(JSON.stringify(claims)));\n  const signature = await crypto.subtle.sign(\n    \"HMAC\",\n    await hmacKey(secret, \"sign\"),\n    encoder.encode(payload),\n  );\n  return `${payload}.${base64url(new Uint8Array(signature))}`;\n}\n\n/** The claims of a token that is well-formed and signed with `secret` — else null (no reason: a\n *  caller answers every bad token the same way). A blank secret verifies nothing. The caller checks\n *  the claims' SHAPE and expiry. */\nexport async function verifyClaims(token: string, secret: string): Promise<unknown> {\n  if (!secret) return null;\n  const dot = token.indexOf(\".\");\n  if (dot <= 0) return null;\n  const payload = token.slice(0, dot);\n  let signature: Uint8Array<ArrayBuffer>;\n  let claims: unknown;\n  try {\n    signature = bytesFromBase64url(token.slice(dot + 1));\n    claims = JSON.parse(decoder.decode(bytesFromBase64url(payload)));\n  } catch {\n    return null;\n  }\n  const valid = await crypto.subtle.verify(\n    \"HMAC\",\n    await hmacKey(secret, \"verify\"),\n    signature,\n    encoder.encode(payload),\n  );\n  return valid ? claims : null;\n}\n\nconst sha256 = async (text: string): Promise<Uint8Array> =>\n  new Uint8Array(await crypto.subtle.digest(\"SHA-256\", encoder.encode(text)));\n\n/** Whether two digests are the same bytes — every byte compared, no early exit, so neither a\n *  matching prefix nor its length leaks by timing. */\nconst digestsEqual = (a: Uint8Array, b: Uint8Array): boolean => {\n  if (a.length !== b.length) return false;\n  let difference = 0;\n  for (let i = 0; i < a.length; i++) difference |= a[i]! ^ b[i]!;\n  return difference === 0;\n};\n\n/** The principal the admin secret grants — `{ actor: \"admin\" }`, every project — when `candidate`\n *  IS `secret` (`APP_CONFIG_ADMIN_API_SECRET`: at `authenticate({ type: \"admin-secret\" })`, as a\n *  lane's bearer and on `/mcp`), else null. Both are SHA-256 hashed and the digests compared in\n *  constant time. A blank secret matches nothing. */\nexport async function verifyAdminSecret(\n  candidate: string,\n  secret: string,\n): Promise<{ actor: \"admin\" } | null> {\n  if (!secret) return null;\n  const [candidateDigest, secretDigest] = await Promise.all([sha256(candidate), sha256(secret)]);\n  return digestsEqual(candidateDigest, secretDigest) ? { actor: \"admin\" } : null;\n}\n\n/** The value of the cookie `name` in a `Cookie` header, or null. */\nexport function cookieValueOf(cookieHeader: string | null, name: string): string | null {\n  for (const part of (cookieHeader || \"\").split(\";\")) {\n    const separator = part.indexOf(\"=\");\n    if (separator < 0) continue;\n    if (part.slice(0, separator).trim() === name) return part.slice(separator + 1).trim();\n  }\n  return null;\n}\n"],"mappings":"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"}

package/dist/next/project-ingress.d.ts

@@ -0,0 +1,37 @@
+/** How projects are reached over HTTP; null ⇒ no ingress (`/api` and `/mcp` still answer). */
+export type IngressRouting = {
+    type: "subdomains";
+    hostname: string;
+} | {
+    type: "paths";
+} | null;
+/** What a request names: the project (its slug, as written — whether it EXISTS is the directory's
+ *  answer), the app (null ⇒ the apex: the project's config worker answers), and the path prefix the
+ *  edge strips before the app sees the URL ("" under subdomains; "/projects/<project>" or
+ *  "/projects/<project>/<app>" under paths). */
+export type ProjectAddress = {
+    project: string;
+    app: string | null;
+    basePath: string;
+};
+/** The project + app `url` names under `routing`, or null when it names none. Pure. */
+export declare function projectAddressOf(routing: IngressRouting, url: URL, platformOrigin: string): ProjectAddress | null;
+/** A CUSTOM HOSTNAME — one of a deployment's own that IS a project's apex (os-next
+ *  `urls.temporaryCustomHostnames`, `{ "iterate2.com": "iterate" }`): the apex shape, `app: null`, so the
+ *  project's config worker `fetch` answers exactly as it does on `<project>.<hostname>`. Null for a
+ *  hostname the map does not name — the map's spelling, case and a trailing dot forgiven, no wildcard
+ *  under it. Pure. */
+export declare function customProjectHostOf(hostname: string, hostnames: Record<string, string>): {
+    app: null;
+    project: string;
+} | null;
+/** The URL of `app` (null ⇒ the apex, the config worker) in `project` under `routing`, at `path`
+ *  (default "/", must start with "/"). Null when there is no ingress, or when the result would not
+ *  parse back to the same address (a bad label; a `path` that climbs out of its app). subdomains:
+ *  the protocol and port are `platformOrigin`'s (local dev is `http://localhost:8788`, so
+ *  `http://<app>--<project>.localhost:8788/…`); paths: `<platformOrigin>/projects/<project>[/<app>]<path>`. Pure. */
+export declare function projectUrlOf(routing: IngressRouting, platformOrigin: string, target: {
+    project: string;
+    app?: string | null;
+    path?: string;
+}): URL | null;