@aigne/aos 0.2.0-beta

package/dist/http/raw-url.cjs

@@ -0,0 +1,136 @@
+const require_session_user_afs = require('../session/session-user-afs.cjs');
+
+//#region src/http/raw-url.ts
+/**
+* Signed raw-URL primitives (afs-preview T2.0/T2.1, design §3).
+*
+* `GET /api/afs/raw?path=…&sid=…&exp=…&sig=…` lets `<img>` / `<iframe>` /
+* `<video>` reference AFS bytes. GET carries no body, so session identity
+* rides a presigned HMAC instead of afs-rpc's body.sessionId:
+*
+*   sig = HMAC-SHA256(secret, [path, sid, normalizedCallerDid, exp])
+*
+* WHY presigned, not a session-registry lookup: CF session state lives in a
+* Durable Object — every `<img>` GET would wake the DO (a gallery page =
+* dozens of wakes; DO-billing lesson). HMAC verification is stateless and
+* identical on Node + workerd (crypto.subtle).
+*
+* Caller binding is symmetric and strict: the verifier recomputes the HMAC
+* with the COOKIE caller (normalized, anonymous = "") — an anonymous-issued
+* URL with an authed cookie fails, an authed-issued URL without a cookie
+* fails. No one-sided downgrade.
+*
+* Anonymous URLs are pure bearer tokens (possession = access), so they are
+* REFUSED for session-private overlay paths (static denylist exported by
+* SessionUserAFS — never hand-written, never derived from a live instance's
+* conditional mounts). Issue-side denial + verify-side second defense.
+*/
+const DEFAULT_TTL_MS = 36e5;
+/** Anonymous caller normalization — identical on issue and verify ends. */
+function normalizeCallerDid(did) {
+	return typeof did === "string" && did ? did : "";
+}
+const _encoder = new TextEncoder();
+async function importKey(secret) {
+	const raw = typeof secret === "string" ? _encoder.encode(secret) : secret;
+	return crypto.subtle.importKey("raw", raw, {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign", "verify"]);
+}
+/** Unambiguous signing payload — JSON array survives any char in fields. */
+function payloadFor(path, sid, callerDid, exp, blocklet) {
+	return _encoder.encode(JSON.stringify([
+		path,
+		sid,
+		callerDid,
+		exp,
+		blocklet
+	]));
+}
+function toBase64Url(bytes) {
+	let binary = "";
+	for (const b of bytes) binary += String.fromCharCode(b);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function fromBase64Url(s) {
+	try {
+		const b64 = s.replaceAll("-", "+").replaceAll("_", "/");
+		return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+	} catch {
+		return null;
+	}
+}
+/**
+* Issue a signed raw URL (path + query, no origin). Returns null when the
+* request is refused (anonymous caller + session-private path) — callers
+* (preview builders) fall back to the no-preview subtree.
+*/
+async function issueRawUrl(params, opts) {
+	const caller = normalizeCallerDid(params.callerDid);
+	if (caller === "" && !opts.skipPrivatePathCheck && require_session_user_afs.isSessionPrivatePath(params.path)) return null;
+	const exp = (opts.now ?? Date.now()) + (params.ttlMs ?? DEFAULT_TTL_MS);
+	const blocklet = params.blocklet ?? "";
+	const key = await importKey(opts.secret);
+	const mac = await crypto.subtle.sign("HMAC", key, payloadFor(params.path, params.sessionId, caller, exp, blocklet));
+	const sig = toBase64Url(new Uint8Array(mac));
+	const q = new URLSearchParams({
+		path: params.path,
+		sid: params.sessionId,
+		exp: String(exp),
+		sig
+	});
+	if (blocklet) q.set("blocklet", blocklet);
+	return `/api/afs/raw?${q.toString()}`;
+}
+/**
+* Verify a raw request URL against the cookie caller. Constant-time HMAC
+* verification via crypto.subtle.verify; every failure is a generic 403 at
+* the endpoint (reasons are for logs/tests, not responses).
+*/
+async function verifyRawUrl(request, cookieCallerDid, opts) {
+	const url = request instanceof URL ? request : new URL(request.url);
+	const path = url.searchParams.get("path");
+	const sid = url.searchParams.get("sid");
+	const expRaw = url.searchParams.get("exp");
+	const sig = url.searchParams.get("sig");
+	if (!path || !sid || !expRaw || !sig) return {
+		ok: false,
+		reason: "missing param"
+	};
+	const exp = Number(expRaw);
+	if (!Number.isFinite(exp)) return {
+		ok: false,
+		reason: "bad exp"
+	};
+	if ((opts.now ?? Date.now()) > exp) return {
+		ok: false,
+		reason: "expired"
+	};
+	const sigBytes = fromBase64Url(sig);
+	if (!sigBytes) return {
+		ok: false,
+		reason: "bad sig encoding"
+	};
+	const caller = normalizeCallerDid(cookieCallerDid);
+	const blocklet = url.searchParams.get("blocklet") ?? "";
+	const key = await importKey(opts.secret);
+	if (!await crypto.subtle.verify("HMAC", key, sigBytes, payloadFor(path, sid, caller, exp, blocklet))) return {
+		ok: false,
+		reason: "signature mismatch (tamper or caller mismatch)"
+	};
+	if (caller === "" && require_session_user_afs.isSessionPrivatePath(path)) return {
+		ok: false,
+		reason: "anonymous bearer URL for session-private path"
+	};
+	return {
+		ok: true,
+		path,
+		sessionId: sid,
+		blocklet: blocklet || null
+	};
+}
+
+//#endregion
+exports.issueRawUrl = issueRawUrl;
+exports.verifyRawUrl = verifyRawUrl;

package/dist/http/raw-url.d.cts

@@ -0,0 +1,54 @@
+import { isSessionPrivatePath } from "../session/session-user-afs.cjs";
+
+//#region src/http/raw-url.d.ts
+interface IssueRawUrlParams {
+  /** AFS path (the builder's sanitized path — signed verbatim). */
+  path: string;
+  /** The verified session id (NEVER a fallback like `rpc-<blocklet>`). */
+  sessionId: string;
+  /** Verified caller DID, or null for anonymous web sessions. */
+  callerDid: string | null;
+  /**
+   * The session's blocklet — rides the URL (so `<img>` works from any
+   * origin without Host-based resolution) AND the signature (so the scoped
+   * view can't be re-pointed by query tamper).
+   */
+  blocklet?: string | null;
+  /** Lifetime in ms (default 1h). */
+  ttlMs?: number;
+}
+interface RawUrlCryptoOptions {
+  /** HMAC secret (Node: vault-derived; CF: env secret). */
+  secret: string | Uint8Array;
+  /** Clock override for tests. */
+  now?: number;
+  /**
+   * TEST SEAM ONLY: skip the issue-side anonymous/private-path denial so the
+   * verify-side second defense can be exercised. Never set in production.
+   */
+  skipPrivatePathCheck?: boolean;
+}
+type VerifyRawUrlResult = {
+  ok: true;
+  path: string;
+  sessionId: string;
+  blocklet: string | null;
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * Issue a signed raw URL (path + query, no origin). Returns null when the
+ * request is refused (anonymous caller + session-private path) — callers
+ * (preview builders) fall back to the no-preview subtree.
+ */
+declare function issueRawUrl(params: IssueRawUrlParams, opts: RawUrlCryptoOptions): Promise<string | null>;
+/**
+ * Verify a raw request URL against the cookie caller. Constant-time HMAC
+ * verification via crypto.subtle.verify; every failure is a generic 403 at
+ * the endpoint (reasons are for logs/tests, not responses).
+ */
+declare function verifyRawUrl(request: Request | URL, cookieCallerDid: string | null, opts: RawUrlCryptoOptions): Promise<VerifyRawUrlResult>;
+//#endregion
+export { IssueRawUrlParams, RawUrlCryptoOptions, VerifyRawUrlResult, issueRawUrl, verifyRawUrl };
+//# sourceMappingURL=raw-url.d.cts.map

package/dist/http/raw-url.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-url.d.cts","names":[],"sources":["../../src/http/raw-url.ts"],"mappings":";;;UA+BiB,iBAAA;EA6Ba;EA3B5B,IAAA;EA4Bc;EA1Bd,SAAA;EA0B+C;EAxB/C,SAAA;EAyBe;;;AAmDjB;;EAtEE,QAAA;EAuEQ;EArER,KAAA;AAAA;AAAA,UAGe,mBAAA;EAoEP;EAlER,MAAA,WAAiB,UAAA;EAgEjB;EA9DA,GAAA;EA+DA;;;;EA1DA,oBAAA;AAAA;AAAA,KAGU,kBAAA;EACN,EAAA;EAAU,IAAA;EAAc,SAAA;EAAmB,QAAA;AAAA;EAC3C,EAAA;EAAW,MAAA;AAAA;;;;;;iBAmDK,WAAA,CACpB,MAAA,EAAQ,iBAAA,EACR,IAAA,EAAM,mBAAA,GACL,OAAA;;;;;;iBAgCmB,YAAA,CACpB,OAAA,EAAS,OAAA,GAAU,GAAA,EACnB,eAAA,iBACA,IAAA,EAAM,mBAAA,GACL,OAAA,CAAQ,kBAAA"}

package/dist/http/raw-url.d.mts

@@ -0,0 +1,54 @@
+import { isSessionPrivatePath } from "../session/session-user-afs.mjs";
+
+//#region src/http/raw-url.d.ts
+interface IssueRawUrlParams {
+  /** AFS path (the builder's sanitized path — signed verbatim). */
+  path: string;
+  /** The verified session id (NEVER a fallback like `rpc-<blocklet>`). */
+  sessionId: string;
+  /** Verified caller DID, or null for anonymous web sessions. */
+  callerDid: string | null;
+  /**
+   * The session's blocklet — rides the URL (so `<img>` works from any
+   * origin without Host-based resolution) AND the signature (so the scoped
+   * view can't be re-pointed by query tamper).
+   */
+  blocklet?: string | null;
+  /** Lifetime in ms (default 1h). */
+  ttlMs?: number;
+}
+interface RawUrlCryptoOptions {
+  /** HMAC secret (Node: vault-derived; CF: env secret). */
+  secret: string | Uint8Array;
+  /** Clock override for tests. */
+  now?: number;
+  /**
+   * TEST SEAM ONLY: skip the issue-side anonymous/private-path denial so the
+   * verify-side second defense can be exercised. Never set in production.
+   */
+  skipPrivatePathCheck?: boolean;
+}
+type VerifyRawUrlResult = {
+  ok: true;
+  path: string;
+  sessionId: string;
+  blocklet: string | null;
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * Issue a signed raw URL (path + query, no origin). Returns null when the
+ * request is refused (anonymous caller + session-private path) — callers
+ * (preview builders) fall back to the no-preview subtree.
+ */
+declare function issueRawUrl(params: IssueRawUrlParams, opts: RawUrlCryptoOptions): Promise<string | null>;
+/**
+ * Verify a raw request URL against the cookie caller. Constant-time HMAC
+ * verification via crypto.subtle.verify; every failure is a generic 403 at
+ * the endpoint (reasons are for logs/tests, not responses).
+ */
+declare function verifyRawUrl(request: Request | URL, cookieCallerDid: string | null, opts: RawUrlCryptoOptions): Promise<VerifyRawUrlResult>;
+//#endregion
+export { IssueRawUrlParams, RawUrlCryptoOptions, VerifyRawUrlResult, issueRawUrl, verifyRawUrl };
+//# sourceMappingURL=raw-url.d.mts.map

package/dist/http/raw-url.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-url.d.mts","names":[],"sources":["../../src/http/raw-url.ts"],"mappings":";;;UA+BiB,iBAAA;EA6Ba;EA3B5B,IAAA;EA4Bc;EA1Bd,SAAA;EA0B+C;EAxB/C,SAAA;EAyBe;;;AAmDjB;;EAtEE,QAAA;EAuEQ;EArER,KAAA;AAAA;AAAA,UAGe,mBAAA;EAoEP;EAlER,MAAA,WAAiB,UAAA;EAgEjB;EA9DA,GAAA;EA+DA;;;;EA1DA,oBAAA;AAAA;AAAA,KAGU,kBAAA;EACN,EAAA;EAAU,IAAA;EAAc,SAAA;EAAmB,QAAA;AAAA;EAC3C,EAAA;EAAW,MAAA;AAAA;;;;;;iBAmDK,WAAA,CACpB,MAAA,EAAQ,iBAAA,EACR,IAAA,EAAM,mBAAA,GACL,OAAA;;;;;;iBAgCmB,YAAA,CACpB,OAAA,EAAS,OAAA,GAAU,GAAA,EACnB,eAAA,iBACA,IAAA,EAAM,mBAAA,GACL,OAAA,CAAQ,kBAAA"}

package/dist/http/raw-url.mjs

@@ -0,0 +1,136 @@
+import { isSessionPrivatePath } from "../session/session-user-afs.mjs";
+
+//#region src/http/raw-url.ts
+/**
+* Signed raw-URL primitives (afs-preview T2.0/T2.1, design §3).
+*
+* `GET /api/afs/raw?path=…&sid=…&exp=…&sig=…` lets `<img>` / `<iframe>` /
+* `<video>` reference AFS bytes. GET carries no body, so session identity
+* rides a presigned HMAC instead of afs-rpc's body.sessionId:
+*
+*   sig = HMAC-SHA256(secret, [path, sid, normalizedCallerDid, exp])
+*
+* WHY presigned, not a session-registry lookup: CF session state lives in a
+* Durable Object — every `<img>` GET would wake the DO (a gallery page =
+* dozens of wakes; DO-billing lesson). HMAC verification is stateless and
+* identical on Node + workerd (crypto.subtle).
+*
+* Caller binding is symmetric and strict: the verifier recomputes the HMAC
+* with the COOKIE caller (normalized, anonymous = "") — an anonymous-issued
+* URL with an authed cookie fails, an authed-issued URL without a cookie
+* fails. No one-sided downgrade.
+*
+* Anonymous URLs are pure bearer tokens (possession = access), so they are
+* REFUSED for session-private overlay paths (static denylist exported by
+* SessionUserAFS — never hand-written, never derived from a live instance's
+* conditional mounts). Issue-side denial + verify-side second defense.
+*/
+const DEFAULT_TTL_MS = 36e5;
+/** Anonymous caller normalization — identical on issue and verify ends. */
+function normalizeCallerDid(did) {
+	return typeof did === "string" && did ? did : "";
+}
+const _encoder = new TextEncoder();
+async function importKey(secret) {
+	const raw = typeof secret === "string" ? _encoder.encode(secret) : secret;
+	return crypto.subtle.importKey("raw", raw, {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign", "verify"]);
+}
+/** Unambiguous signing payload — JSON array survives any char in fields. */
+function payloadFor(path, sid, callerDid, exp, blocklet) {
+	return _encoder.encode(JSON.stringify([
+		path,
+		sid,
+		callerDid,
+		exp,
+		blocklet
+	]));
+}
+function toBase64Url(bytes) {
+	let binary = "";
+	for (const b of bytes) binary += String.fromCharCode(b);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function fromBase64Url(s) {
+	try {
+		const b64 = s.replaceAll("-", "+").replaceAll("_", "/");
+		return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+	} catch {
+		return null;
+	}
+}
+/**
+* Issue a signed raw URL (path + query, no origin). Returns null when the
+* request is refused (anonymous caller + session-private path) — callers
+* (preview builders) fall back to the no-preview subtree.
+*/
+async function issueRawUrl(params, opts) {
+	const caller = normalizeCallerDid(params.callerDid);
+	if (caller === "" && !opts.skipPrivatePathCheck && isSessionPrivatePath(params.path)) return null;
+	const exp = (opts.now ?? Date.now()) + (params.ttlMs ?? DEFAULT_TTL_MS);
+	const blocklet = params.blocklet ?? "";
+	const key = await importKey(opts.secret);
+	const mac = await crypto.subtle.sign("HMAC", key, payloadFor(params.path, params.sessionId, caller, exp, blocklet));
+	const sig = toBase64Url(new Uint8Array(mac));
+	const q = new URLSearchParams({
+		path: params.path,
+		sid: params.sessionId,
+		exp: String(exp),
+		sig
+	});
+	if (blocklet) q.set("blocklet", blocklet);
+	return `/api/afs/raw?${q.toString()}`;
+}
+/**
+* Verify a raw request URL against the cookie caller. Constant-time HMAC
+* verification via crypto.subtle.verify; every failure is a generic 403 at
+* the endpoint (reasons are for logs/tests, not responses).
+*/
+async function verifyRawUrl(request, cookieCallerDid, opts) {
+	const url = request instanceof URL ? request : new URL(request.url);
+	const path = url.searchParams.get("path");
+	const sid = url.searchParams.get("sid");
+	const expRaw = url.searchParams.get("exp");
+	const sig = url.searchParams.get("sig");
+	if (!path || !sid || !expRaw || !sig) return {
+		ok: false,
+		reason: "missing param"
+	};
+	const exp = Number(expRaw);
+	if (!Number.isFinite(exp)) return {
+		ok: false,
+		reason: "bad exp"
+	};
+	if ((opts.now ?? Date.now()) > exp) return {
+		ok: false,
+		reason: "expired"
+	};
+	const sigBytes = fromBase64Url(sig);
+	if (!sigBytes) return {
+		ok: false,
+		reason: "bad sig encoding"
+	};
+	const caller = normalizeCallerDid(cookieCallerDid);
+	const blocklet = url.searchParams.get("blocklet") ?? "";
+	const key = await importKey(opts.secret);
+	if (!await crypto.subtle.verify("HMAC", key, sigBytes, payloadFor(path, sid, caller, exp, blocklet))) return {
+		ok: false,
+		reason: "signature mismatch (tamper or caller mismatch)"
+	};
+	if (caller === "" && isSessionPrivatePath(path)) return {
+		ok: false,
+		reason: "anonymous bearer URL for session-private path"
+	};
+	return {
+		ok: true,
+		path,
+		sessionId: sid,
+		blocklet: blocklet || null
+	};
+}
+
+//#endregion
+export { issueRawUrl, verifyRawUrl };
+//# sourceMappingURL=raw-url.mjs.map

package/dist/http/raw-url.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-url.mjs","names":[],"sources":["../../src/http/raw-url.ts"],"sourcesContent":["/**\n * Signed raw-URL primitives (afs-preview T2.0/T2.1, design §3).\n *\n * `GET /api/afs/raw?path=…&sid=…&exp=…&sig=…` lets `<img>` / `<iframe>` /\n * `<video>` reference AFS bytes. GET carries no body, so session identity\n * rides a presigned HMAC instead of afs-rpc's body.sessionId:\n *\n *   sig = HMAC-SHA256(secret, [path, sid, normalizedCallerDid, exp])\n *\n * WHY presigned, not a session-registry lookup: CF session state lives in a\n * Durable Object — every `<img>` GET would wake the DO (a gallery page =\n * dozens of wakes; DO-billing lesson). HMAC verification is stateless and\n * identical on Node + workerd (crypto.subtle).\n *\n * Caller binding is symmetric and strict: the verifier recomputes the HMAC\n * with the COOKIE caller (normalized, anonymous = \"\") — an anonymous-issued\n * URL with an authed cookie fails, an authed-issued URL without a cookie\n * fails. No one-sided downgrade.\n *\n * Anonymous URLs are pure bearer tokens (possession = access), so they are\n * REFUSED for session-private overlay paths (static denylist exported by\n * SessionUserAFS — never hand-written, never derived from a live instance's\n * conditional mounts). Issue-side denial + verify-side second defense.\n */\n\nimport { isSessionPrivatePath } from \"../session/session-user-afs.js\";\n\nexport { isSessionPrivatePath };\n\nconst DEFAULT_TTL_MS = 3600_000; // 1h — re-render/new select re-issues; no auto-renewal\n\nexport interface IssueRawUrlParams {\n  /** AFS path (the builder's sanitized path — signed verbatim). */\n  path: string;\n  /** The verified session id (NEVER a fallback like `rpc-<blocklet>`). */\n  sessionId: string;\n  /** Verified caller DID, or null for anonymous web sessions. */\n  callerDid: string | null;\n  /**\n   * The session's blocklet — rides the URL (so `<img>` works from any\n   * origin without Host-based resolution) AND the signature (so the scoped\n   * view can't be re-pointed by query tamper).\n   */\n  blocklet?: string | null;\n  /** Lifetime in ms (default 1h). */\n  ttlMs?: number;\n}\n\nexport interface RawUrlCryptoOptions {\n  /** HMAC secret (Node: vault-derived; CF: env secret). */\n  secret: string | Uint8Array;\n  /** Clock override for tests. */\n  now?: number;\n  /**\n   * TEST SEAM ONLY: skip the issue-side anonymous/private-path denial so the\n   * verify-side second defense can be exercised. Never set in production.\n   */\n  skipPrivatePathCheck?: boolean;\n}\n\nexport type VerifyRawUrlResult =\n  | { ok: true; path: string; sessionId: string; blocklet: string | null }\n  | { ok: false; reason: string };\n\n/** Anonymous caller normalization — identical on issue and verify ends. */\nfunction normalizeCallerDid(did: string | null | undefined): string {\n  return typeof did === \"string\" && did ? did : \"\";\n}\n\nconst _encoder = new TextEncoder();\n\nasync function importKey(secret: string | Uint8Array): Promise<CryptoKey> {\n  const raw = typeof secret === \"string\" ? _encoder.encode(secret) : secret;\n  return crypto.subtle.importKey(\n    \"raw\",\n    raw as BufferSource,\n    { name: \"HMAC\", hash: \"SHA-256\" },\n    false,\n    [\"sign\", \"verify\"],\n  );\n}\n\n/** Unambiguous signing payload — JSON array survives any char in fields. */\nfunction payloadFor(\n  path: string,\n  sid: string,\n  callerDid: string,\n  exp: number,\n  blocklet: string,\n): Uint8Array {\n  return _encoder.encode(JSON.stringify([path, sid, callerDid, exp, blocklet]));\n}\n\nfunction toBase64Url(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (const b of bytes) binary += String.fromCharCode(b);\n  return btoa(binary).replaceAll(\"+\", \"-\").replaceAll(\"/\", \"_\").replace(/=+$/, \"\");\n}\n\nfunction fromBase64Url(s: string): Uint8Array | null {\n  try {\n    const b64 = s.replaceAll(\"-\", \"+\").replaceAll(\"_\", \"/\");\n    return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Issue a signed raw URL (path + query, no origin). Returns null when the\n * request is refused (anonymous caller + session-private path) — callers\n * (preview builders) fall back to the no-preview subtree.\n */\nexport async function issueRawUrl(\n  params: IssueRawUrlParams,\n  opts: RawUrlCryptoOptions,\n): Promise<string | null> {\n  const caller = normalizeCallerDid(params.callerDid);\n  if (caller === \"\" && !opts.skipPrivatePathCheck && isSessionPrivatePath(params.path)) {\n    // Anonymous = bearer URL; private overlay content must not become\n    // possession-grants-access (design §3).\n    return null;\n  }\n  const now = opts.now ?? Date.now();\n  const exp = now + (params.ttlMs ?? DEFAULT_TTL_MS);\n  const blocklet = params.blocklet ?? \"\";\n  const key = await importKey(opts.secret);\n  const mac = await crypto.subtle.sign(\n    \"HMAC\",\n    key,\n    payloadFor(params.path, params.sessionId, caller, exp, blocklet) as BufferSource,\n  );\n  const sig = toBase64Url(new Uint8Array(mac));\n  const q = new URLSearchParams({\n    path: params.path,\n    sid: params.sessionId,\n    exp: String(exp),\n    sig,\n  });\n  if (blocklet) q.set(\"blocklet\", blocklet);\n  return `/api/afs/raw?${q.toString()}`;\n}\n\n/**\n * Verify a raw request URL against the cookie caller. Constant-time HMAC\n * verification via crypto.subtle.verify; every failure is a generic 403 at\n * the endpoint (reasons are for logs/tests, not responses).\n */\nexport async function verifyRawUrl(\n  request: Request | URL,\n  cookieCallerDid: string | null,\n  opts: RawUrlCryptoOptions,\n): Promise<VerifyRawUrlResult> {\n  const url = request instanceof URL ? request : new URL(request.url);\n  const path = url.searchParams.get(\"path\");\n  const sid = url.searchParams.get(\"sid\");\n  const expRaw = url.searchParams.get(\"exp\");\n  const sig = url.searchParams.get(\"sig\");\n  if (!path || !sid || !expRaw || !sig) return { ok: false, reason: \"missing param\" };\n\n  const exp = Number(expRaw);\n  if (!Number.isFinite(exp)) return { ok: false, reason: \"bad exp\" };\n  const now = opts.now ?? Date.now();\n  if (now > exp) return { ok: false, reason: \"expired\" };\n\n  const sigBytes = fromBase64Url(sig);\n  if (!sigBytes) return { ok: false, reason: \"bad sig encoding\" };\n\n  const caller = normalizeCallerDid(cookieCallerDid);\n  const blocklet = url.searchParams.get(\"blocklet\") ?? \"\";\n  const key = await importKey(opts.secret);\n  const valid = await crypto.subtle.verify(\n    \"HMAC\",\n    key,\n    sigBytes as BufferSource,\n    payloadFor(path, sid, caller, exp, blocklet) as BufferSource,\n  );\n  if (!valid) return { ok: false, reason: \"signature mismatch (tamper or caller mismatch)\" };\n\n  // Second defense (design §3): even a correctly-signed anonymous URL must\n  // not reach session-private overlays.\n  if (caller === \"\" && isSessionPrivatePath(path)) {\n    return { ok: false, reason: \"anonymous bearer URL for session-private path\" };\n  }\n\n  return { ok: true, path, sessionId: sid, blocklet: blocklet || null };\n}\n"],"mappings":"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"}

package/dist/http/request-context.cjs

@@ -0,0 +1,178 @@
+const require_auth_context = require('./auth-context.cjs');
+const require_read_blocklet_scope = require('../scope/read-blocklet-scope.cjs');
+let ufo = require("ufo");
+let _aigne_afs = require("@aigne/afs");
+let _aigne_afs_logger = require("@aigne/afs-logger");
+let _aigne_afs_timing = require("@aigne/afs-timing");
+
+//#region src/http/request-context.ts
+/**
+* Shared HTTP request-context + scoped-AFS helper (afs-preview T2.0).
+*
+* `createAfsRpcHandler` historically封装ed blocklet/host resolution, the
+* per-blocklet projection cache, caller/trusted-context resolution, and the
+* per-request overlay inside one closure — unreachable for the raw-bytes
+* endpoint. This module extracts that pipeline so RPC and raw share ONE
+* implementation (copying an incomplete auth/overlay stack = permission
+* bypass; the HTTP/WS dual-overlay lesson).
+*
+* CACHE SEMANTICS (pinned, design §3): the projection cache is
+* PER-HELPER-INSTANCE. rpc and raw each instantiate their own helper —
+* shared code, NOT shared runtime state. raw must never reach into rpc's
+* cache.
+*
+* SESSION ID: `resolveScoped` takes an EXPLICIT `sessionId` parameter. The
+* raw endpoint passes the signature-verified sid; it never flows through
+* any `sessionId ?? "rpc-<blocklet>"` fallback (that fallback lives in the
+* CF rpc overlay closure and stays rpc-only).
+*/
+/** afs:auth structured logger (debug self-guards; off by default). */
+const authLog = (0, _aigne_afs.nsLog)("afs:auth");
+const DEFAULT_PROJECTION_CACHE_LIMIT = 32;
+const DEFAULT_REGISTRY_PATH = "/registry/blocklets";
+/**
+* Ops the default read-only blocklet projection allows through. Superset of
+* the request-type vocabulary: `query` is a read-class SEMANTIC op (judged by
+* `semanticOpForRootAction` when `/.actions/query` rides exec) but NOT a wire
+* op — requests still arrive as `type: "exec"` (zero protocol change,
+* design §3.1).
+*/
+const PROJECTION_READ_OPS = new Set([
+	"read",
+	"list",
+	"stat",
+	"search",
+	"exec",
+	"query"
+]);
+function makeDefaultBlockletAFSFactory(registryPath) {
+	return async function defaultCreateBlockletAFS(blocklet, globalAFS) {
+		if (await require_read_blocklet_scope.readBlockletScope(globalAFS, blocklet) === "root") return globalAFS;
+		const sessionAFS = new _aigne_afs.AFS();
+		await sessionAFS.mount(new _aigne_afs.ProjectionProvider({
+			name: blocklet,
+			globalAFS,
+			sourcePath: (0, ufo.joinURL)(registryPath, blocklet),
+			allowedOps: PROJECTION_READ_OPS
+		}), "/");
+		return sessionAFS;
+	};
+}
+function normalizeHostAliasCandidate(host) {
+	const value = host.trim().toLowerCase();
+	if (!value) return void 0;
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code <= 32 || code === 127) return void 0;
+	}
+	if (value.includes("/") || value.includes("@") || value.includes("\\")) return void 0;
+	if (value.startsWith("[")) return void 0;
+	const colonCount = (value.match(/:/g) ?? []).length;
+	if (colonCount > 1) return void 0;
+	let hostname = value;
+	if (colonCount === 1) {
+		const [name, port] = value.split(":");
+		if (!name || !port || !/^\d+$/.test(port)) return void 0;
+		hostname = name;
+	}
+	hostname = hostname.replace(/\.$/, "");
+	return hostname || void 0;
+}
+function createAfsRequestContext(options) {
+	const cache = /* @__PURE__ */ new Map();
+	const cacheLimit = Math.max(1, options.projectionCacheLimit ?? DEFAULT_PROJECTION_CACHE_LIMIT);
+	const registryPath = options.registryPath ?? DEFAULT_REGISTRY_PATH;
+	const factory = options.createBlockletAFS ?? makeDefaultBlockletAFSFactory(registryPath);
+	async function getBlockletAFS(blocklet) {
+		const existing = cache.get(blocklet);
+		if (existing) {
+			cache.delete(blocklet);
+			cache.set(blocklet, existing);
+			(0, _aigne_afs_timing.timeMeta)("bafs", "hit");
+			return existing;
+		}
+		const fresh = await (0, _aigne_afs_timing.time)("bafs", () => factory(blocklet, options.globalAFS));
+		cache.set(blocklet, fresh);
+		while (cache.size > cacheLimit) {
+			const oldest = cache.keys().next().value;
+			if (oldest === void 0) break;
+			cache.delete(oldest);
+		}
+		return fresh;
+	}
+	async function resolveBlocklet(request, explicitBlocklet, opts) {
+		const explicit = typeof explicitBlocklet === "string" && explicitBlocklet ? explicitBlocklet : null;
+		if ((opts?.explicitPriority ?? "trusted") === "trusted" && explicit) return explicit;
+		const url = new URL(request.url);
+		const queryBlocklet = url.searchParams.get("blocklet");
+		if ((opts?.queryPriority ?? "trusted") === "trusted" && queryBlocklet) return queryBlocklet;
+		const host = request.headers.get("Host") ?? url.host;
+		const aliasHost = normalizeHostAliasCandidate(host);
+		if (options.resolveHostAlias && aliasHost) {
+			const aliased = await options.resolveHostAlias(aliasHost);
+			if (aliased) return aliased;
+		}
+		const fromHost = (0, _aigne_afs.extractBlockletFromHost)(host, options.domainRoots ? { domainRoots: options.domainRoots } : void 0);
+		if (fromHost) return fromHost;
+		if (explicit) return explicit;
+		if (queryBlocklet) return queryBlocklet;
+		return options.fallbackBlocklet ?? null;
+	}
+	async function resolveCaller(request) {
+		const caller = options.resolveCaller ? await (0, _aigne_afs_timing.time)("auth", () => options.resolveCaller(request)) : null;
+		authLog.debug({
+			message: "caller resolved",
+			userDid: caller?.did ?? null,
+			authMethod: caller?.authMethod
+		});
+		return caller;
+	}
+	async function resolveScoped(request, args) {
+		const { blocklet, sessionId, caller } = args;
+		const scope = await require_read_blocklet_scope.readBlockletScope(options.globalAFS, blocklet);
+		let afs = await getBlockletAFS(blocklet);
+		const trusted = options.resolveTrustedAfsContext ? await options.resolveTrustedAfsContext(request, {
+			blocklet,
+			caller,
+			sessionId
+		}) : {
+			instanceDid: blocklet,
+			agentRunOrigin: "interactive"
+		};
+		trusted.callerOrigin = "network";
+		const context = require_auth_context.mergeCallerContext(args.opOptions ?? {}, caller, trusted);
+		if (!context.requestId) {
+			const rid = (0, _aigne_afs_timing.getTiming)()?.requestId;
+			if (rid) context.requestId = rid;
+		}
+		const identity = { blockletId: blocklet };
+		if (caller?.did) identity.userDid = caller.did;
+		if (trusted.instanceDid) identity.instanceDid = trusted.instanceDid;
+		if (sessionId) identity.sessionId = sessionId;
+		(0, _aigne_afs_logger.getLogContext)()?.enrich(identity);
+		if (options.overlayForRequest && scope !== "root") try {
+			afs = await (0, _aigne_afs_timing.time)("ovl", () => options.overlayForRequest(afs, {
+				blocklet,
+				caller,
+				sessionId,
+				scope,
+				instanceDid: trusted.instanceDid
+			}));
+		} catch {}
+		return {
+			blocklet,
+			scope,
+			afs,
+			caller,
+			context
+		};
+	}
+	return {
+		resolveBlocklet,
+		resolveScoped,
+		resolveCaller
+	};
+}
+
+//#endregion
+exports.createAfsRequestContext = createAfsRequestContext;

package/dist/http/request-context.d.cts

@@ -0,0 +1,76 @@
+import { BlockletScope } from "../scope/types.cjs";
+import { ResolveCallerFn, ResolveTrustedAfsContext } from "./auth-context.cjs";
+import { AFSRoot, CallerInfo } from "@aigne/afs";
+
+//#region src/http/request-context.d.ts
+interface AfsRequestContextOptions {
+  /** The runtime-global AFS (the projection's source). */
+  globalAFS: AFSRoot;
+  /** Roots passed to `extractBlockletFromHost` (e.g. `["afsd.io"]`). */
+  domainRoots?: string[];
+  /** Resolve a normalized Host hostname to a blocklet id (runtime alias map). */
+  resolveHostAlias?: (host: string) => Promise<string | undefined> | string | undefined;
+  /** Used when neither explicit value, query, nor Host header resolve a blocklet. */
+  fallbackBlocklet?: string;
+  /** Bound on how many distinct blocklet projections we keep in memory. */
+  projectionCacheLimit?: number;
+  /** Where the blocklet catalog lives in the global AFS. */
+  registryPath?: string;
+  /** Test seam / runtime adapter: override the projected-AFS factory. */
+  createBlockletAFS?: (blocklet: string, globalAFS: AFSRoot) => Promise<AFSRoot>;
+  /** Resolve a verified caller from the inbound request. */
+  resolveCaller?: ResolveCallerFn;
+  /** Resolve the trusted, host-controlled AFSContext slice. */
+  resolveTrustedAfsContext?: ResolveTrustedAfsContext;
+  /** Optional PER-REQUEST overlay (per-caller `/user`, per-session `/tmp`, …). */
+  overlayForRequest?: (baseAFS: AFSRoot, ctx: {
+    blocklet: string;
+    caller: CallerInfo | null;
+    sessionId: string | null;
+    scope: BlockletScope;
+    /**
+     * Host-resolved instanceDid (the trusted-context slice), present even for an
+     * ANONYMOUS caller. Use this — NOT `caller.instanceDid` — for the `/instance`
+     * partition key, so anonymous + bound-host reads land on the SAME tenant the
+     * WS / DO path uses (instance-resolve F-2).
+     */
+    instanceDid?: string;
+  }) => AFSRoot | Promise<AFSRoot>;
+}
+interface ScopedRequest {
+  blocklet: string;
+  scope: BlockletScope;
+  /** The per-request AFS view (cached base + uncached per-request overlay). */
+  afs: AFSRoot;
+  caller: CallerInfo | null;
+  /** Merged op context (caller + trusted slice + callerOrigin + requestId). */
+  context: Record<string, unknown>;
+}
+interface AfsRequestContext {
+  /**
+   * Resolve the target blocklet. The default treats explicitBlocklet as trusted
+   * (signed raw URLs); HTTP RPC passes explicitPriority:"fallback" so the
+   * server-resolved Host/alias wins over browser-provided hints.
+   */
+  resolveBlocklet(request: Request, explicitBlocklet?: string | null, opts?: {
+    explicitPriority?: "trusted" | "fallback";
+    queryPriority?: "trusted" | "fallback";
+  }): Promise<string | null>;
+  /**
+   * Build the per-request scoped view + op context. `sessionId` is the
+   * caller-supplied session identity (rpc: body.sessionId; raw: the
+   * signature-verified sid) — null means "no session".
+   */
+  resolveScoped(request: Request, args: {
+    blocklet: string;
+    sessionId: string | null;
+    caller: CallerInfo | null;
+    opOptions?: Record<string, unknown>;
+  }): Promise<ScopedRequest>;
+  /** Resolve the verified caller (or null when no resolver / anonymous). */
+  resolveCaller(request: Request): Promise<CallerInfo | null>;
+}
+declare function createAfsRequestContext(options: AfsRequestContextOptions): AfsRequestContext;
+//#endregion
+export { AfsRequestContext, AfsRequestContextOptions, ScopedRequest, createAfsRequestContext };
+//# sourceMappingURL=request-context.d.cts.map

package/dist/http/request-context.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.cts","names":[],"sources":["../../src/http/request-context.ts"],"mappings":";;;;;UAuDiB,wBAAA;EAcf;EAZA,SAAA,EAAW,OAAA;EAYuC;EAVlD,WAAA;EAU8D;EAR9D,gBAAA,IAAoB,IAAA,aAAiB,OAAA;EAUrC;EARA,gBAAA;EAUA;EARA,oBAAA;EAUA;EARA,YAAA;EASE;EAPF,iBAAA,IAAqB,QAAA,UAAkB,SAAA,EAAW,OAAA,KAAY,OAAA,CAAQ,OAAA;EAUlE;EARJ,aAAA,GAAgB,eAAA;EASZ;EAPJ,wBAAA,GAA2B,wBAAA;EAQhB;EANX,iBAAA,IACE,OAAA,EAAS,OAAA,EACT,GAAA;IACE,QAAA;IACA,MAAA,EAAQ,UAAA;IACR,SAAA;IACA,KAAA,EAAO,aAAA;IASmB;;AAGhC;;;;IALM,WAAA;EAAA,MAEC,OAAA,GAAU,OAAA,CAAQ,OAAA;AAAA;AAAA,UAGR,aAAA;EACf,QAAA;EACA,KAAA,EAAO,aAAA;EAAP;EAEA,GAAA,EAAK,OAAA;EACL,MAAA,EAAQ,UAAA;EADH;EAGL,OAAA,EAAS,MAAA;AAAA;AAAA,UAGM,iBAAA;EAHN;;;AAGX;;EAME,eAAA,CACE,OAAA,EAAS,OAAA,EACT,gBAAA,kBACA,IAAA;IACE,gBAAA;IACA,aAAA;EAAA,IAED,OAAA;EAWS;;;;;EALZ,aAAA,CACE,OAAA,EAAS,OAAA,EACT,IAAA;IACE,QAAA;IACA,SAAA;IACA,MAAA,EAAQ,UAAA;IACR,SAAA,GAAY,MAAA;EAAA,IAEb,OAAA,CAAQ,aAAA;EApBT;EAsBF,aAAA,CAAc,OAAA,EAAS,OAAA,GAAU,OAAA,CAAQ,UAAA;AAAA;AAAA,iBAiD3B,uBAAA,CAAwB,OAAA,EAAS,wBAAA,GAA2B,iBAAA"}