akanjs 3.0.2 → 3.1.0-rc.0

package/server/di/diLifecycle.ts

@@ -22,6 +22,7 @@ import type { ServerSignal, ServerSignalCls } from "../../signal/serverSignal";
 import { SignalRegistry } from "../../signal/signalRegistry";
 import type { AkanLib, DatabaseModule, ScalarModule, ServiceModule } from "../akanLib";
 import { createDefaultAkanOption } from "../akanOption";
+import { MachineAccount } from "../machine/machineAccount";
 import type { WebProxyRegistration } from "../proxy";
 import { CascadeRunner, DatabaseResolver, ServiceResolver, SignalResolver } from "../resolver";
 import type { SignalRoutes, WebsocketRoutes } from "../types";
@@ -32,6 +33,7 @@ import {
   type DiModuleCandidate,
   getModuleCascadeRefNames,
   getModuleDependencyRefNames,
+  getModuleRelationRefNames,
   isDestroyableUse,
   normalizeAdaptorRefName,
   normalizeServiceRefName,
@@ -168,6 +170,8 @@ export class DiLifecycle {
         this.#scalar.set(mod.constant.refName, mod);
       });
     });
+    
+    this.#middleware.set(MachineAccount.refName, MachineAccount);
     const disabledModules = this.#resolveDisabledModules({
       databaseCandidates,
       serviceCandidates,
@@ -235,11 +239,18 @@ export class DiLifecycle {
     const candidates = new Map<string, DiModuleCandidate>([...databaseCandidates, ...serviceCandidates]);
     const disabledReasons = new Map<string, string>();
 
+    const { operationMode } = getEnv();
     candidates.forEach(({ refName, module }) => {
-      if (!module.service.srv.enabled) disabledReasons.set(refName, "service disabled");
+      const modes = module.service.srv.operationMode;
+      if (modes && !modes.includes(operationMode))
+        disabledReasons.set(refName, `operationMode "${operationMode}" is not in [${modes.join(", ")}]`);
+      else if (!module.service.srv.enabled) disabledReasons.set(refName, "service disabled");
     });
 
-    const selected = this.#resolveSelectedModules(candidates, modules);
+    const selected = this.#resolveSelectedModules(
+      candidates,
+      DiLifecycle.#expandSelectors(modules, candidates, "modules"),
+    );
     if (selected) {
       candidates.forEach(({ refName }) => {
         if (!selected.has(refName) && !disabledReasons.has(refName))
@@ -247,7 +258,12 @@ export class DiLifecycle {
       });
     }
 
-    const excluded = this.#resolveExcludedModules({ candidates, disableModules, disableLibs, moduleLibs });
+    const excluded = this.#resolveExcludedModules({
+      candidates,
+      disableModules: DiLifecycle.#expandSelectors(disableModules, candidates, "disableModules"),
+      disableLibs,
+      moduleLibs,
+    });
     
     excluded.forEach((reason, refName) => {
       if (!disabledReasons.has(refName)) disabledReasons.set(refName, reason);
@@ -334,6 +350,7 @@ export class DiLifecycle {
       const dependencies = [
         ...getModuleDependencyRefNames(candidate.module),
         ...getModuleCascadeRefNames(candidate.module),
+        ...getModuleRelationRefNames(candidate.module),
       ];
       for (const dependency of dependencies) if (candidates.has(dependency)) pending.push(dependency);
     }
@@ -342,6 +359,25 @@ export class DiLifecycle {
     return selected;
   }
 
+  static #expandSelectors(names: string[], candidates: Map<string, DiModuleCandidate>, option: string) {
+    return [
+      ...new Set(
+        names.flatMap((name) => {
+          if (!name.startsWith("@")) return [name];
+          const mode = name.slice(1);
+          const tagged = [...candidates.values()]
+            .filter(({ module }) => module.service.srv.operationMode?.includes(mode))
+            .map(({ refName }) => refName);
+          if (!tagged.length)
+            throw new Error(
+              `[DI:${option}] "${name}" names no module: no serve() in this app or its libs lists operationMode "${mode}".`,
+            );
+          return tagged;
+        }),
+      ),
+    ];
+  }
+
   static #assertKnown(names: string[], known: Set<string>, unknownLabel: string, knownLabel: string) {
     const unknown = names.filter((name) => !known.has(name));
     if (!unknown.length) return;

package/server/di/utils.ts

@@ -1,9 +1,15 @@
-import { INJECT_META } from "akanjs/base";
+import { FIELD_META, INJECT_META } from "akanjs/base";
 import { lowerlize, toError } from "akanjs/common";
 import { ConstantRegistry } from "akanjs/constant";
 import type { InjectInfo } from "akanjs/service";
 import type { DatabaseModule, ServiceModule } from "../akanLib";
 
+interface FieldMeta {
+  isClass: boolean;
+  isScalar: boolean;
+  modelRef: unknown;
+}
+
 interface StageTask {
   label: string;
   run: () => Promise<unknown>;
@@ -68,6 +74,27 @@ export const getModuleDependencyRefNames = (mod: DatabaseModule | ServiceModule)
   return dependencies;
 };
 
+export const getModuleRelationRefNames = (mod: DatabaseModule | ServiceModule) => {
+  const dependencies = new Set<string>();
+  if (!("constant" in mod)) return dependencies;
+  const visited = new Set<unknown>();
+  const visit = (modelRef: unknown) => {
+    if (visited.has(modelRef)) return;
+    visited.add(modelRef);
+    const fields = (modelRef as { [FIELD_META]?: Record<string, FieldMeta> })[FIELD_META] ?? {};
+    for (const field of Object.values(fields)) {
+      if (!field.isClass) continue;
+      if (field.isScalar) visit(field.modelRef);
+      else {
+        const refName = ConstantRegistry.getRefName(field.modelRef as never, { allowEmpty: true });
+        if (refName) dependencies.add(refName);
+      }
+    }
+  };
+  visit(mod.constant.full);
+  return dependencies;
+};
+
 export const getModuleCascadeRefNames = (mod: DatabaseModule | ServiceModule) => {
   const dependencies = new Set<string>();
   if (!("constant" in mod)) return dependencies;

package/server/ed25519Key.ts

@@ -0,0 +1,48 @@
+import { createPrivateKey, createPublicKey, generateKeyPairSync, type KeyObject } from "node:crypto";
+
+export class Ed25519Key {
+  /** PEM (with `\n` escapes, as an env file holds one), a JWK, base64 SPKI DER, or a raw 32-byte base64url key. */
+  static parsePublic(value: string, name: string): KeyObject {
+    const trimmed = value.trim();
+    const key = (() => {
+      if (trimmed.startsWith("{")) return createPublicKey({ key: JSON.parse(trimmed) as JsonWebKey, format: "jwk" });
+      if (trimmed.includes("-----BEGIN")) return createPublicKey(trimmed.replace(/\\n/g, "\n"));
+      const raw = Buffer.from(trimmed, "base64url");
+      if (raw.length === 32)
+        return createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: raw.toString("base64url") }, format: "jwk" });
+      if (raw.length === 44) return createPublicKey({ key: raw, format: "der", type: "spki" });
+      throw new Error(`${name} must be a PEM, a JWK, base64 SPKI DER, or a raw 32-byte base64url key`);
+    })();
+    if (key.asymmetricKeyType !== "ed25519") throw new Error(`${name} must be an Ed25519 public key`);
+    return key;
+  }
+
+  /** PEM (with `\n` escapes), a JWK, or base64 PKCS#8 DER. */
+  static parsePrivate(value: string, name: string): KeyObject {
+    const trimmed = value.trim();
+    const key = (() => {
+      if (trimmed.startsWith("{")) return createPrivateKey({ key: JSON.parse(trimmed) as JsonWebKey, format: "jwk" });
+      if (trimmed.includes("-----BEGIN")) return createPrivateKey(trimmed.replace(/\\n/g, "\n"));
+      const raw = Buffer.from(trimmed, "base64");
+      if (raw.length === 48) return createPrivateKey({ key: raw, format: "der", type: "pkcs8" });
+      throw new Error(`${name} must be a PEM, a JWK, or base64 PKCS#8 DER private key`);
+    })();
+    if (key.asymmetricKeyType !== "ed25519") throw new Error(`${name} must be an Ed25519 private key`);
+    return key;
+  }
+
+  /** The private key as PKCS#8 PEM, and the public key as the raw 32 bytes in base64url, short enough for an env line. */
+  static generate() {
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    return {
+      privatePem: privateKey.export({ format: "pem", type: "pkcs8" }).toString(),
+      publicKey: Ed25519Key.rawPublic(publicKey),
+    };
+  }
+
+  static rawPublic(key: KeyObject) {
+    const { x } = key.export({ format: "jwk" });
+    if (!x) throw new Error("not an Ed25519 public key");
+    return x;
+  }
+}

package/server/index.ts

@@ -7,6 +7,7 @@ export * from "./console";
 export * from "./decorators";
 export * from "./devtools";
 export type { ChangeBatch, ChangeKind } from "./hmr/wsHub";
+export * from "./machine";
 export * from "./nativeFile";
 export * from "./oauth";
 export * from "./processMetricsCollector";

package/server/machine/index.ts

@@ -0,0 +1,2 @@
+export * from "./machineAccount";
+export * from "./machineToken";

package/server/machine/machineAccount.ts

@@ -0,0 +1,27 @@
+import { getEnv } from "akanjs/base";
+import type { Middleware, SignalContext } from "akanjs/signal";
+import { MachineToken } from "./machineToken";
+
+interface AccountHolder {
+  headers?: Headers;
+  account?: Record<string, unknown>;
+}
+
+export class MachineAccount implements Middleware {
+  static readonly refName = "MachineAccount";
+
+  use() {
+    return async (context: SignalContext, next: () => Promise<unknown>) => {
+      const holder = (
+        context.transport === "http" ? context.getHttpContext().req : context.getWebSocketContext().ws.data
+      ) as AccountHolder;
+      const machine = MachineToken.fromAuthorization(holder.headers?.get("authorization"));
+      const { machine: _unverified, ...account } = holder.account ?? {};
+      if (machine) {
+        const { appName, environment } = getEnv();
+        holder.account = { ...(holder.account ? account : { appName, environment }), machine };
+      } else if (holder.account && "machine" in holder.account) holder.account = account;
+      return await next();
+    };
+  }
+}

package/server/machine/machineToken.ts

@@ -0,0 +1,151 @@
+import { createPublicKey, type KeyObject, sign, verify } from "node:crypto";
+import { getEnv } from "akanjs/base";
+import { Logger } from "akanjs/common";
+import type { MachineIdentity } from "akanjs/signal";
+import { Ed25519Key } from "../ed25519Key";
+
+export interface MachineTokenIssueOptions {
+  /** None by default: a machine's token lapses only when its version is bumped. */
+  expiresAt?: Date | { toDate(): Date };
+  /** The `<app>/<environment>` that accepts it; this server's own by default. */
+  audience?: string;
+}
+
+export type MachineTokenVerdict = { ok: true; identity: MachineIdentity } | { ok: false; reason: string };
+
+interface KeyPair {
+  privateKey: KeyObject | null;
+  publicKey: KeyObject | null;
+}
+
+export class MachineToken {
+  static readonly type = "akan-machine+jwt";
+  static readonly #logger = new Logger("MachineToken");
+  static #keys: { source: string; pair: KeyPair } | null = null;
+  static #warnedKeyless = false;
+
+  static audience() {
+    const { appName, environment } = getEnv();
+    return `${appName}/${environment}`;
+  }
+
+  static #keyPair(): KeyPair {
+    const privateValue = process.env.AKAN_MACHINE_PRIVATE_KEY?.trim() ?? "";
+    const publicValue = process.env.AKAN_MACHINE_PUBLIC_KEY?.trim() ?? "";
+    const source = `${privateValue}\0${publicValue}`;
+    if (MachineToken.#keys?.source === source) return MachineToken.#keys.pair;
+    const privateKey = privateValue ? Ed25519Key.parsePrivate(privateValue, "AKAN_MACHINE_PRIVATE_KEY") : null;
+    const publicKey = publicValue
+      ? Ed25519Key.parsePublic(publicValue, "AKAN_MACHINE_PUBLIC_KEY")
+      : privateKey
+        ? createPublicKey(privateKey)
+        : null;
+    const pair = { privateKey, publicKey };
+    MachineToken.#keys = { source, pair };
+    return pair;
+  }
+
+  static canIssue() {
+    return !!MachineToken.#keyPair().privateKey;
+  }
+
+  static canVerify() {
+    return !!MachineToken.#keyPair().publicKey;
+  }
+
+  static issue(identity: MachineIdentity, { expiresAt, audience }: MachineTokenIssueOptions = {}): string {
+    const { privateKey } = MachineToken.#keyPair();
+    if (!privateKey) throw new Error("MachineToken.issue needs AKAN_MACHINE_PRIVATE_KEY on the server that issues it");
+    MachineToken.#assertIdentity(identity);
+    const iat = Math.floor(Date.now() / 1000);
+    const expiry = expiresAt ? ("toDate" in expiresAt ? expiresAt.toDate() : expiresAt) : null;
+    const claims = {
+      aud: audience ?? MachineToken.audience(),
+      sub: identity.id,
+      kind: identity.kind,
+      ver: identity.version,
+      iat,
+      ...(expiry ? { exp: Math.floor(expiry.getTime() / 1000) } : {}),
+    };
+    const signed = `${MachineToken.#encode({ alg: "EdDSA", typ: MachineToken.type })}.${MachineToken.#encode(claims)}`;
+    return `${signed}.${sign(null, Buffer.from(signed), privateKey).toString("base64url")}`;
+  }
+
+  /** By its header alone, so a staff session's bearer is told apart without a verification. */
+  static isMachineToken(token: string) {
+    const [headerPart = ""] = token.split(".");
+    return MachineToken.#decode(headerPart)?.typ === MachineToken.type;
+  }
+
+  static verify(token: string, nowSec = Math.floor(Date.now() / 1000)): MachineTokenVerdict {
+    const parts = token.split(".");
+    if (parts.length !== 3) return { ok: false, reason: "malformed token" };
+    const [headerPart = "", payloadPart = "", signaturePart = ""] = parts;
+    const header = MachineToken.#decode(headerPart);
+    if (header?.alg !== "EdDSA" || header.typ !== MachineToken.type)
+      return { ok: false, reason: `not an EdDSA ${MachineToken.type}` };
+    const { publicKey } = MachineToken.#keyPair();
+    if (!publicKey)
+      return { ok: false, reason: "no AKAN_MACHINE_PUBLIC_KEY or AKAN_MACHINE_PRIVATE_KEY to verify with" };
+    const signed = verify(
+      null,
+      Buffer.from(`${headerPart}.${payloadPart}`),
+      publicKey,
+      Buffer.from(signaturePart, "base64url"),
+    );
+    if (!signed) return { ok: false, reason: "bad signature" };
+    const claims = MachineToken.#decode(payloadPart);
+    if (!claims) return { ok: false, reason: "malformed claims" };
+    const { aud, sub, kind, ver, exp } = claims;
+    const audiences = Array.isArray(aud) ? aud : [aud];
+    if (!audiences.includes(MachineToken.audience())) return { ok: false, reason: "audience mismatch" };
+    if (exp !== undefined && (typeof exp !== "number" || exp <= nowSec)) return { ok: false, reason: "expired" };
+    const identity = { kind, id: sub, version: ver } as MachineIdentity;
+    if (!MachineToken.#isIdentity(identity)) return { ok: false, reason: "sub, kind and ver are required" };
+    return { ok: true, identity: { kind: identity.kind, id: identity.id, version: identity.version } };
+  }
+
+  /** The identity a bearer machine token proves, or `null`: absent, another kind of token, or one that fails. */
+  static fromAuthorization(authorization: string | null | undefined): MachineIdentity | null {
+    const token = /^Bearer +(\S+)$/i.exec(authorization ?? "")?.[1];
+    if (!token || !MachineToken.isMachineToken(token)) return null;
+    const verdict = MachineToken.verify(token);
+    if (verdict.ok) return verdict.identity;
+    if (!MachineToken.canVerify() && !MachineToken.#warnedKeyless) {
+      MachineToken.#warnedKeyless = true;
+      MachineToken.#logger.error(
+        "A machine token arrived, and this server has neither AKAN_MACHINE_PUBLIC_KEY nor AKAN_MACHINE_PRIVATE_KEY to verify it: every machine call is anonymous.",
+      );
+    } else MachineToken.#logger.verbose(`refused a machine token: ${verdict.reason}`);
+    return null;
+  }
+
+  static #isIdentity(identity: MachineIdentity) {
+    return (
+      typeof identity.kind === "string" &&
+      !!identity.kind &&
+      typeof identity.id === "string" &&
+      !!identity.id &&
+      Number.isSafeInteger(identity.version) &&
+      identity.version >= 0
+    );
+  }
+
+  static #assertIdentity(identity: MachineIdentity) {
+    if (!MachineToken.#isIdentity(identity))
+      throw new Error("A machine identity is { kind, id } as non-empty strings and version as an integer from 0");
+  }
+
+  static #encode(value: object) {
+    return Buffer.from(JSON.stringify(value)).toString("base64url");
+  }
+
+  static #decode(part: string): Record<string, unknown> | null {
+    try {
+      const value = JSON.parse(Buffer.from(part, "base64url").toString("utf8")) as unknown;
+      return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+    } catch {
+      return null;
+    }
+  }
+}

package/server/mcp/McpApps.ts

@@ -0,0 +1,256 @@
+import { getEnv } from "akanjs/base";
+import type { PromptContent, PromptMessage } from "../../signal/mcp/Msg";
+import {
+  MCP_UI_EXTENSION,
+  MCP_UI_LEGACY_RESOURCE_URI,
+  MCP_UI_MIME_TYPE,
+  type McpResource,
+  type McpResourceContents,
+  type McpTool,
+} from "../../signal/mcp/mcpProtocol";
+import type { PagePromptEntry, PagePromptRecord, PagePromptRun } from "../../signal/mcp/pagePrompt";
+
+/** The CSR shell a view boots from: one single-file HTML per basePath, read from the build that serves the web. */
+export interface McpAppShellSource {
+  readonly basePaths: readonly string[];
+  /** `""` is the app without a basePath; `null` when this build has no single-file shell for it. */
+  read(basePath: string): Promise<string | null>;
+}
+
+interface McpAppSnapshotRecord {
+  key: string;
+  args: Record<string, unknown>;
+  value: unknown;
+}
+
+export class McpApps {
+  static readonly scheme = "ui://";
+  static readonly sessionPrefix = "ui.";
+  
+  static readonly snapshotKey = "akanjs/snapshot";
+  
+  static readonly rootSegment = "app";
+  static readonly #tokenClaims = new Set(["iss", "aud", "exp", "nbf", "iat", "jti", "client_id", "scope"]);
+
+  static readonly #runtime = `
+(() => {
+  const memoryStorage = () => {
+    const items = new Map();
+    return {
+      get length() { return items.size; },
+      key: (idx) => [...items.keys()][idx] ?? null,
+      getItem: (key) => (items.has(key) ? items.get(key) : null),
+      setItem: (key, value) => { items.set(String(key), String(value)); },
+      removeItem: (key) => { items.delete(String(key)); },
+      clear: () => { items.clear(); },
+    };
+  };
+  for (const name of ["localStorage", "sessionStorage"])
+    Object.defineProperty(window, name, { value: memoryStorage(), configurable: true });
+  const jar = new Map();
+  Object.defineProperty(document, "cookie", {
+    configurable: true,
+    get: () => [...jar].map(([name, value]) => name + "=" + value).join("; "),
+    set: (raw) => {
+      const [pair, ...attrs] = String(raw).split(";");
+      const at = pair.indexOf("=");
+      if (at < 0) return;
+      const name = pair.slice(0, at).trim();
+      const expired = attrs.some((attr) => /^\\s*expires=/i.test(attr) && Date.parse(attr.split("=")[1]) < Date.now());
+      if (expired) jar.delete(name);
+      else jar.set(name, pair.slice(at + 1).trim());
+    },
+  });
+  const origin = window.__AKAN_EMBED__.origin;
+  if (!origin || document.baseURI.startsWith(origin + "/")) return;
+  const absolute = (url) => (url.startsWith("/") && !url.startsWith("//") ? origin + url : url);
+  const valueOf = (el, name, value) => {
+    if (typeof value !== "string") return value;
+    if (name === "src" || name === "poster" || (name === "href" && el.tagName === "LINK")) return absolute(value);
+    if (name !== "srcset") return value;
+    return value.split(",").map((part) => part.trim().replace(/^\\S+/, absolute)).join(", ");
+  };
+  const setAttribute = Element.prototype.setAttribute;
+  Element.prototype.setAttribute = function (name, value) {
+    return setAttribute.call(this, name, valueOf(this, String(name).toLowerCase(), value));
+  };
+  const fix = (el) => {
+    for (const name of ["src", "srcset", "poster", "href"]) {
+      const value = el.getAttribute(name);
+      if (value !== null && valueOf(el, name, value) !== value) setAttribute.call(el, name, valueOf(el, name, value));
+    }
+  };
+  new MutationObserver((records) => {
+    for (const record of records) {
+      if (record.type === "attributes") fix(record.target);
+      else for (const node of record.addedNodes) {
+        if (node.nodeType !== 1) continue;
+        fix(node);
+        for (const el of node.querySelectorAll("[src],[srcset],[poster],link[href]")) fix(el);
+      }
+    }
+  }).observe(document.documentElement, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    attributeFilter: ["src", "srcset", "poster", "href"],
+  });
+})();
+`;
+
+  readonly #shell: McpAppShellSource | null;
+
+  constructor(shell: McpAppShellSource | null) {
+    this.#shell = shell;
+  }
+
+  get rendersUi() {
+    return this.#shell !== null;
+  }
+
+  static declaresUi(capabilities: unknown) {
+    if (!capabilities || typeof capabilities !== "object") return false;
+    const extensions = (capabilities as { extensions?: unknown }).extensions;
+    if (!extensions || typeof extensions !== "object") return false;
+    const ui = (extensions as Record<string, { mimeTypes?: unknown } | undefined>)[MCP_UI_EXTENSION];
+    return Array.isArray(ui?.mimeTypes) && ui.mimeTypes.includes(MCP_UI_MIME_TYPE);
+  }
+
+  toolOf(entry: PagePromptEntry): McpTool {
+    const properties = Object.fromEntries(
+      entry.arguments.map((arg) => [
+        arg.name,
+        { type: "string", ...(arg.description ? { description: arg.description } : {}) },
+      ]),
+    );
+    const required = entry.arguments.filter((arg) => arg.required).map((arg) => arg.name);
+    return {
+      name: entry.name,
+      description: entry.description,
+      inputSchema: {
+        type: "object",
+        properties,
+        ...(required.length ? { required } : {}),
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      ...(this.#shell ? { _meta: this.#toolMetaOf(this.uriOf(this.#basePathOf(entry.pattern))) } : {}),
+    };
+  }
+
+  #toolMetaOf(resourceUri: string) {
+    return { ui: { resourceUri }, [MCP_UI_LEGACY_RESOURCE_URI]: resourceUri };
+  }
+
+  resourcesOf(entries: PagePromptEntry[]): McpResource[] {
+    if (!this.#shell) return [];
+    const { appName } = getEnv();
+    const basePaths = [...new Set(entries.map((entry) => this.#basePathOf(entry.pattern)))];
+    return basePaths.map((basePath) => ({
+      uri: this.uriOf(basePath),
+      name: basePath || appName,
+      description: `The ${basePath || appName} screens, rendered in place of a tool result.`,
+      mimeType: MCP_UI_MIME_TYPE,
+    }));
+  }
+
+  uriOf(basePath: string) {
+    const root = `${McpApps.scheme}${getEnv().appName.toLowerCase()}/${McpApps.rootSegment}`;
+    return basePath ? `${root}/${basePath}` : root;
+  }
+
+  async read(uri: string, origin: string): Promise<McpResourceContents | null> {
+    const shell = this.#shell;
+    const basePath = shell ? this.#basePathOfUri(uri) : null;
+    if (!shell || basePath === null) return null;
+    const html = await shell.read(basePath);
+    if (!html) return null;
+    const appOrigin = McpApps.#originOf(origin);
+    return {
+      uri,
+      mimeType: MCP_UI_MIME_TYPE,
+      text: McpApps.#withHead(appOrigin ? McpApps.#absoluteCss(html, appOrigin) : html, appOrigin),
+      _meta: {
+        ui: {
+          prefersBorder: false,
+          ...(appOrigin ? { csp: { resourceDomains: [appOrigin], baseUriDomains: [appOrigin] } } : {}),
+        },
+      },
+    };
+  }
+
+  resultOf(
+    run: Extract<PagePromptRun, { ok: true }>,
+    messages: PromptMessage[],
+    webOrigin: string,
+    forView: { account: Record<string, unknown> | null } | null,
+  ) {
+    const url = new URL(run.url);
+    const href = `${url.pathname}${url.search}`;
+    const content: PromptContent[] = [
+      ...messages.map((message) => message.content),
+      { type: "text", text: `Open this screen in a browser: ${webOrigin}${href}` },
+    ];
+    if (!this.#shell || !forView) return { content, isError: false };
+    const _meta = { [McpApps.snapshotKey]: McpApps.#snapshotOf(run.records), "akanjs/account": forView.account };
+    return { content, structuredContent: { href }, _meta, isError: false };
+  }
+
+  static accountOf(req: Request): Record<string, unknown> | null {
+    const token = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "");
+    const payload = token?.split(".")[1];
+    if (!payload) return null;
+    try {
+      const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as Record<string, unknown>;
+      return Object.fromEntries(Object.entries(claims).filter(([key]) => !McpApps.#tokenClaims.has(key)));
+    } catch {
+      return null;
+    }
+  }
+
+  #basePathOf(pattern: string) {
+    const [, , segment] = pattern.split("/");
+    return segment && this.#shell?.basePaths.includes(segment) ? segment : "";
+  }
+
+  #basePathOfUri(uri: string) {
+    const match = /^ui:\/\/([^/]+)\/([^?#]*)$/i.exec(uri);
+    if (!match || match[1]?.toLowerCase() !== getEnv().appName.toLowerCase()) return null;
+    const [root, basePath, ...rest] = (match[2] ?? "").split("/");
+    if (root !== McpApps.rootSegment || rest.length) return null;
+    if (!basePath) return "";
+    return this.#shell?.basePaths.includes(basePath) ? basePath : null;
+  }
+
+  static #snapshotOf(records: PagePromptRecord[]): McpAppSnapshotRecord[] {
+    return records.flatMap(({ key, args, value }) => (value === undefined ? [] : [{ key, args, value }]));
+  }
+
+  static #originOf(origin: string) {
+    try {
+      const parsed = new URL(origin);
+      return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.origin : null;
+    } catch {
+      return null;
+    }
+  }
+
+  static #absoluteCss(html: string, origin: string) {
+    return html.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, (block) =>
+      block.replace(/url\((["']?)\/(?!\/)/g, `url($1${origin}/`),
+    );
+  }
+
+  static #withHead(html: string, origin: string | null) {
+    const embed = JSON.stringify({ kind: "mcp-app", ...(origin ? { origin } : {}) });
+    const preamble = `<script>\nwindow.__AKAN_EMBED__ = ${embed};${McpApps.#runtime}</script>`;
+    const inject = `${origin ? `<base href="${origin}/">` : ""}${preamble}`;
+    const head = /<head(\s[^>]*)?>/i.exec(html);
+    if (!head) return `${inject}${html}`;
+    const headEnd = head.index + head[0].length;
+    const scriptAt = html.indexOf("<script", headEnd);
+    const charset = /<meta\s[^>]*charset[^>]*>/i.exec(html.slice(headEnd, scriptAt < 0 ? undefined : scriptAt));
+    const at = charset ? headEnd + charset.index + charset[0].length : headEnd;
+    return `${html.slice(0, at)}${inject}${html.slice(at)}`;
+  }
+}