@czap/astro 0.1.0

package/src/runtime/llm.ts

@@ -0,0 +1,344 @@
+import { Diagnostics } from '@czap/core';
+import type { Receipt } from '@czap/core';
+import type { LLMChunk } from '@czap/web';
+import { createLLMSession } from './llm-session.js';
+import { readRuntimeHtmlPolicy, readRuntimeEndpointPolicy } from './policy.js';
+import { allowRuntimeEndpointUrl } from './url-policy.js';
+
+const SAFE_LLM_TARGET_SELECTOR = /^(?:#[A-Za-z][\w-]*|\.[A-Za-z_][\w-]*|\[data-czap-target="[-:A-Za-z0-9_]+"\])$/;
+
+const parseJSONUnknown = (text: string): unknown => JSON.parse(text);
+
+function normalizeToolDeltaContent(content: unknown, toolArgs: unknown): string | undefined {
+  if (typeof content === 'string') {
+    return content;
+  }
+
+  if (typeof toolArgs === 'string') {
+    return toolArgs;
+  }
+
+  if (toolArgs && typeof toolArgs === 'object') {
+    return JSON.stringify(toolArgs);
+  }
+
+  return undefined;
+}
+
+function firstMeaningfulCharCode(raw: string): number {
+  for (let index = 0; index < raw.length; index++) {
+    const code = raw.charCodeAt(index);
+    if (code !== 32 && code !== 9 && code !== 10 && code !== 13) {
+      return code;
+    }
+  }
+
+  return -1;
+}
+
+function toStructuredChunk(
+  type: LLMChunk['type'],
+  partial: unknown,
+  content: unknown,
+  toolName: unknown,
+  toolArgs: unknown,
+): LLMChunk {
+  const normalizedToolName = typeof toolName === 'string' ? toolName : undefined;
+  const normalizedContent =
+    type === 'tool-call-delta'
+      ? normalizeToolDeltaContent(content, toolArgs)
+      : typeof content === 'string'
+        ? content
+        : undefined;
+
+  return {
+    type,
+    partial: partial === true,
+    content: normalizedContent,
+    toolName: normalizedToolName,
+    toolArgs,
+  };
+}
+
+/**
+ * Parse a raw `MessageEvent` payload into an {@link LLMChunk}. Returns
+ * `null` when the payload is unrecognised so callers can drop
+ * non-chunk events (metrics, heartbeats, ...) silently.
+ */
+export function parseLLMChunk(event: Pick<MessageEvent, 'data'>): LLMChunk | null {
+  const decoded = decodeLLMEventData(event.data);
+  return decoded.type === 'chunk' ? decoded.chunk : null;
+}
+
+function mapDeviceTier(): 'none' | 'transitions' | 'animations' | 'physics' | 'compute' {
+  switch (document.documentElement.getAttribute('data-czap-tier')) {
+    case 'static':
+      return 'none';
+    case 'styled':
+      return 'transitions';
+    case 'gpu':
+      return 'compute';
+    case 'animated':
+      return 'physics';
+    default:
+      return 'animations';
+  }
+}
+
+function parseLLMError(error: { content?: unknown; message?: unknown }): string {
+  if (typeof error.content === 'string') {
+    return error.content;
+  }
+  if (typeof error.message === 'string') {
+    return error.message;
+  }
+
+  return 'unknown error';
+}
+
+type ParsedEventData =
+  | { readonly type: 'receipt'; readonly envelope: Receipt.Envelope }
+  | { readonly type: 'error'; readonly message: string }
+  | { readonly type: 'chunk'; readonly chunk: LLMChunk }
+  | { readonly type: 'ignored' };
+
+interface StructuredLLMEvent {
+  readonly type?: unknown;
+  readonly data?: unknown;
+  readonly content?: unknown;
+  readonly message?: unknown;
+  readonly partial?: unknown;
+  readonly toolName?: unknown;
+  readonly toolArgs?: unknown;
+}
+
+function isStructuredLLMEvent(value: unknown): value is StructuredLLMEvent {
+  return typeof value === 'object' && value !== null;
+}
+
+function decodeStructuredLLMEventData(data: unknown): ParsedEventData {
+  if (!isStructuredLLMEvent(data)) {
+    return { type: 'ignored' };
+  }
+
+  switch (data.type) {
+    case 'receipt':
+      return isReceiptEnvelope(data.data) ? { type: 'receipt', envelope: data.data } : { type: 'ignored' };
+    case 'error': {
+      return { type: 'error', message: parseLLMError(data) };
+    }
+    case 'text':
+    case 'tool-call-start':
+    case 'tool-call-delta':
+    case 'tool-call-end':
+    case 'done':
+      return {
+        type: 'chunk',
+        chunk: toStructuredChunk(data.type, data.partial, data.content, data.toolName, data.toolArgs),
+      };
+    default:
+      return { type: 'ignored' };
+  }
+}
+
+function decodeLLMEventData(data: unknown): ParsedEventData {
+  if (typeof data === 'string') {
+    const firstChar = firstMeaningfulCharCode(data);
+    if (firstChar === -1) {
+      return { type: 'ignored' };
+    }
+
+    if (firstChar !== 123 && firstChar !== 91) {
+      return {
+        type: 'chunk',
+        chunk: {
+          type: 'text',
+          partial: false,
+          content: data,
+          toolName: undefined,
+          toolArgs: undefined,
+        },
+      };
+    }
+
+    let parsed: unknown;
+    let syntaxError = false;
+
+    try {
+      parsed = parseJSONUnknown(data);
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        syntaxError = true;
+      } else {
+        throw error;
+      }
+    }
+
+    if (syntaxError) {
+      return { type: 'ignored' };
+    }
+
+    return decodeStructuredLLMEventData(parsed);
+  }
+
+  return decodeStructuredLLMEventData(data);
+}
+
+function isReceiptEnvelope(value: unknown): value is Receipt.Envelope {
+  if (typeof value !== 'object' || value === null) return false;
+  if (!('hash' in value) || !('previous' in value)) return false;
+  return typeof value.hash === 'string';
+}
+
+function resolveLLMTarget(element: HTMLElement, selector: string | null): HTMLElement {
+  if (!selector || !SAFE_LLM_TARGET_SELECTOR.test(selector)) {
+    return element;
+  }
+
+  try {
+    const found = element.querySelector(selector);
+    return found instanceof HTMLElement ? found : element;
+  } catch {
+    return element;
+  }
+}
+
+/**
+ * Entry point used by the `client:llm` directive to start a streaming
+ * LLM session on `element`. Reads `data-czap-llm-url` (plus optional
+ * target / mode attributes), validates it against the runtime
+ * endpoint policy, opens an SSE stream, and drives an
+ * {@link LLMSessionShape} to completion.
+ */
+export function initLLMDirective(load: () => Promise<unknown>, element: HTMLElement): void {
+  const endpointPolicy = readRuntimeEndpointPolicy();
+  const htmlPolicy = readRuntimeHtmlPolicy();
+  const llmUrl = allowRuntimeEndpointUrl(
+    element.getAttribute('data-czap-llm-url'),
+    'llm',
+    'czap/astro.llm',
+    {
+      crossOriginRejected: 'llm-cross-origin-url-rejected',
+      malformedUrl: 'llm-malformed-url-rejected',
+      originNotAllowed: 'llm-origin-not-allowed',
+      endpointKindNotPermitted: 'llm-endpoint-kind-not-permitted',
+    },
+    endpointPolicy,
+  );
+  if (!llmUrl) {
+    return;
+  }
+
+  const mode = element.getAttribute('data-czap-llm-mode') ?? 'append';
+  const targetSelector = element.getAttribute('data-czap-llm-target');
+  const resolveTarget = (): HTMLElement => resolveLLMTarget(element, targetSelector);
+  const resetTarget = (target: HTMLElement): void => {
+    target.replaceChildren();
+  };
+
+  let source: EventSource | null = null;
+  const session = createLLMSession({
+    element,
+    target: resolveTarget(),
+    mode,
+    getDeviceTier: mapDeviceTier,
+    htmlPolicy: htmlPolicy.llmDefault,
+    allowTrustedHtml: htmlPolicy.allowTrustedHtml,
+  });
+
+  const cleanupSource = (): void => {
+    if (source) {
+      source.onopen = null;
+      source.onmessage = null;
+      source.onerror = null;
+    }
+    source?.close();
+    source = null;
+  };
+
+  const cleanup = (): void => {
+    cleanupSource();
+    session.dispose();
+  };
+
+  const handleDisconnect = (): void => {
+    cleanupSource();
+    session.beginReconnect();
+
+    const strategy = session.replayGap();
+    if (strategy.type === 'replay') {
+      return;
+    }
+
+    element.dispatchEvent(
+      new CustomEvent('czap:llm-error', {
+        detail: { reason: 'connection-error', strategy: strategy.type },
+        bubbles: true,
+      }),
+    );
+  };
+
+  const connect = (): void => {
+    cleanupSource();
+    const target = resolveTarget();
+    resetTarget(target);
+    session.reset(target);
+    source = new EventSource(llmUrl);
+
+    source.onopen = () => {
+      session.activate();
+      element.dispatchEvent(new CustomEvent('czap:llm-start', { bubbles: true }));
+    };
+
+    source.onmessage = (event: MessageEvent) => {
+      const decoded = decodeLLMEventData(event.data);
+      switch (decoded.type) {
+        case 'receipt':
+          session.rememberEnvelope(decoded.envelope);
+          return;
+        case 'error':
+          element.dispatchEvent(
+            new CustomEvent('czap:llm-error', {
+              detail: { message: decoded.message },
+              bubbles: true,
+            }),
+          );
+          cleanupSource();
+          return;
+        case 'ignored':
+          return;
+        case 'chunk':
+          if (session.ingest(decoded.chunk) === 'done') {
+            cleanupSource();
+          }
+          return;
+      }
+    };
+
+    source.onerror = () => {
+      handleDisconnect();
+    };
+  };
+
+  try {
+    connect();
+  } catch (error) {
+    Diagnostics.error({
+      source: 'czap/astro.llm',
+      code: 'llm-runtime-init-failed',
+      message: 'The shared LLM runtime could not initialize.',
+      detail: error instanceof Error ? error.message : String(error),
+    });
+    cleanup();
+  }
+
+  element.addEventListener('czap:reinit', () => {
+    connect();
+  });
+
+  element.addEventListener('czap:dispose', () => {
+    cleanup();
+  });
+
+  load();
+}

package/src/runtime/policy.ts

@@ -0,0 +1,229 @@
+/**
+ * Runtime security-policy data model: how `@czap/astro`'s client
+ * directives decide which endpoints they may fetch and how to treat
+ * HTML returned from those endpoints.
+ *
+ * @module
+ */
+import type { HtmlPolicy, RuntimeEndpointKind, RuntimeEndpointPolicy } from '@czap/web';
+import { readRuntimeGlobal, writeRuntimeGlobal } from './globals.js';
+
+/**
+ * User-supplied HTML policy. Directives fall back to conservative
+ * defaults (`text` for LLM output, `sanitized-html` for stream
+ * payloads) when individual fields are omitted.
+ */
+export interface RuntimeHtmlPolicy {
+  /** Default HTML trust level for `client:llm` text sinks. */
+  readonly llmDefault?: HtmlPolicy;
+  /** Default HTML trust level for `client:stream` payloads. */
+  readonly streamDefault?: HtmlPolicy;
+  /** Opt-in to `trusted-html` system-wide. */
+  readonly allowTrustedHtml?: boolean;
+}
+
+/**
+ * Combined runtime security policy (endpoint + HTML). Passed to
+ * {@link configureRuntimePolicy} and persisted on `window` for
+ * directive consumption.
+ */
+export interface RuntimeSecurityPolicy {
+  /** Endpoint allowlist configuration. */
+  readonly endpointPolicy?: RuntimeEndpointPolicy;
+  /** HTML policy configuration. */
+  readonly htmlPolicy?: RuntimeHtmlPolicy;
+}
+
+/**
+ * Frozen, fully-populated form of {@link RuntimeEndpointPolicy}. Every
+ * `RuntimeEndpointKind` has an allowlist (possibly empty) so callers
+ * can index safely without presence checks.
+ */
+export interface NormalizedRuntimeEndpointPolicy {
+  readonly mode: RuntimeEndpointPolicy['mode'];
+  readonly allowOrigins: readonly string[];
+  readonly byKind: Readonly<Record<RuntimeEndpointKind, readonly string[]>>;
+}
+
+/**
+ * Frozen form of {@link RuntimeSecurityPolicy} with every optional
+ * field materialised to its default. Produced by
+ * {@link normalizeRuntimeSecurityPolicy}.
+ */
+export interface NormalizedRuntimeSecurityPolicy {
+  readonly endpointPolicy: NormalizedRuntimeEndpointPolicy;
+  readonly htmlPolicy: {
+    readonly llmDefault: HtmlPolicy;
+    readonly streamDefault: HtmlPolicy;
+    readonly allowTrustedHtml: boolean;
+  };
+}
+
+function isNormalizedRuntimeSecurityPolicy(value: unknown): value is NormalizedRuntimeSecurityPolicy {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'endpointPolicy' in value &&
+    'htmlPolicy' in value &&
+    typeof value.endpointPolicy === 'object' &&
+    value.endpointPolicy !== null &&
+    typeof value.htmlPolicy === 'object' &&
+    value.htmlPolicy !== null
+  );
+}
+
+const DEFAULT_ENDPOINT_POLICY: NormalizedRuntimeEndpointPolicy = Object.freeze({
+  mode: 'same-origin',
+  allowOrigins: Object.freeze([]),
+  byKind: Object.freeze({
+    stream: Object.freeze([]),
+    snapshot: Object.freeze([]),
+    replay: Object.freeze([]),
+    llm: Object.freeze([]),
+    'gpu-shader': Object.freeze([]),
+    wasm: Object.freeze([]),
+  }),
+});
+
+const DEFAULT_HTML_POLICY: {
+  readonly llmDefault: HtmlPolicy;
+  readonly streamDefault: HtmlPolicy;
+  readonly allowTrustedHtml: boolean;
+} = Object.freeze({
+  llmDefault: 'text',
+  streamDefault: 'sanitized-html',
+  allowTrustedHtml: false,
+});
+
+function freezeOrigins(origins?: readonly string[]): readonly string[] {
+  return Object.freeze((origins ?? []).map((origin) => origin.trim()).filter((origin) => origin.length > 0));
+}
+
+function freezeEndpointPolicy(policy?: RuntimeEndpointPolicy): NormalizedRuntimeEndpointPolicy {
+  if (!policy) {
+    return DEFAULT_ENDPOINT_POLICY;
+  }
+
+  // Fully populate every kind up-front so the record is typed correctly
+  // from the initializer, without an empty-literal cast.
+  const byKind: Record<RuntimeEndpointKind, readonly string[]> = {
+    stream: freezeOrigins(policy.byKind?.stream),
+    snapshot: freezeOrigins(policy.byKind?.snapshot),
+    replay: freezeOrigins(policy.byKind?.replay),
+    llm: freezeOrigins(policy.byKind?.llm),
+    'gpu-shader': freezeOrigins(policy.byKind?.['gpu-shader']),
+    wasm: freezeOrigins(policy.byKind?.wasm),
+  };
+
+  return Object.freeze({
+    mode: policy.mode,
+    allowOrigins: freezeOrigins(policy.allowOrigins),
+    byKind: Object.freeze(byKind),
+  });
+}
+
+/**
+ * Freeze a user-supplied security policy into the fully-populated
+ * {@link NormalizedRuntimeSecurityPolicy} form. Applies conservative
+ * defaults for any missing fields.
+ */
+export function normalizeRuntimeSecurityPolicy(policy?: RuntimeSecurityPolicy): NormalizedRuntimeSecurityPolicy {
+  return Object.freeze({
+    endpointPolicy: freezeEndpointPolicy(policy?.endpointPolicy),
+    htmlPolicy: Object.freeze({
+      llmDefault: policy?.htmlPolicy?.llmDefault ?? DEFAULT_HTML_POLICY.llmDefault,
+      streamDefault: policy?.htmlPolicy?.streamDefault ?? DEFAULT_HTML_POLICY.streamDefault,
+      allowTrustedHtml: policy?.htmlPolicy?.allowTrustedHtml ?? DEFAULT_HTML_POLICY.allowTrustedHtml,
+    }),
+  });
+}
+
+/**
+ * Module-private source of truth for the active runtime policy. Lives
+ * in a closure no external script can `Object.defineProperty` past;
+ * the window global is a discoverable broadcast and a cross-bundle
+ * bridge, not the canonical store. Production callers always go
+ * through `configureRuntimePolicy` / `readRuntimePolicy`, both of
+ * which read the closure first.
+ *
+ * @internal
+ */
+let _currentPolicy: NormalizedRuntimeSecurityPolicy | null = null;
+
+/**
+ * Tracks whether the cross-bundle window broadcast has been published.
+ * The broadcast happens once per realm with `configurable: false` so
+ * an attacker with script execution cannot redefine the property on
+ * later loaders. Subsequent `configureRuntimePolicy` calls (HMR,
+ * tests) update the module-private store but skip a re-broadcast,
+ * which would throw against the locked descriptor. The broadcast is
+ * informational; consumers in the same module-graph see updates
+ * through the closure regardless.
+ *
+ * @internal
+ */
+let _windowGlobalPublished = false;
+
+/**
+ * Normalise `policy` and install it as the active runtime configuration.
+ *
+ * The first call in a given realm publishes the value to
+ * `window.__CZAP_RUNTIME_POLICY__` with `configurable: false` and
+ * `writable: false`, so an attacker cannot redefine the global via
+ * `Object.defineProperty` to install a permissive policy. Subsequent
+ * calls (HMR, test re-initialisation) update the module-private store
+ * only — the window global stays locked at the first published value.
+ *
+ * Production callers run `configureRuntimePolicy` once during the
+ * integration boot script. Test harnesses re-call it freely; reads
+ * via `readRuntimePolicy()` return the latest configured value
+ * because the module-private store is checked first.
+ */
+export function configureRuntimePolicy(policy?: RuntimeSecurityPolicy): NormalizedRuntimeSecurityPolicy {
+  const normalized = normalizeRuntimeSecurityPolicy(policy);
+  _currentPolicy = normalized;
+
+  if (!_windowGlobalPublished) {
+    writeRuntimeGlobal('__CZAP_RUNTIME_POLICY__', normalized, { configurable: false });
+    _windowGlobalPublished = true;
+  }
+
+  return normalized;
+}
+
+/**
+ * Read the active runtime policy. Prefers the module-private store
+ * (the canonical source of truth), falls back to the cross-bundle
+ * window broadcast for consumers loaded as a separate bundle, and
+ * finally to a default normalised policy when nothing has been
+ * configured (e.g. in tests that haven't called
+ * `configureRuntimePolicy` yet).
+ */
+export function readRuntimePolicy(): NormalizedRuntimeSecurityPolicy {
+  if (_currentPolicy) return _currentPolicy;
+  return (
+    readRuntimeGlobal('__CZAP_RUNTIME_POLICY__', isNormalizedRuntimeSecurityPolicy) ?? normalizeRuntimeSecurityPolicy()
+  );
+}
+
+/**
+ * Reset the module-private policy store to its uninitialised state.
+ * Test-only: production code must not call this. The window-global
+ * broadcast is intentionally NOT cleared (the descriptor is
+ * non-configurable and cannot be redefined within a single realm).
+ *
+ * @internal
+ */
+export function _resetRuntimePolicyForTests(): void {
+  _currentPolicy = null;
+}
+
+/** Convenience accessor for the endpoint sub-policy. */
+export function readRuntimeEndpointPolicy(): NormalizedRuntimeEndpointPolicy {
+  return readRuntimePolicy().endpointPolicy;
+}
+
+/** Convenience accessor for the HTML sub-policy. */
+export function readRuntimeHtmlPolicy(): NormalizedRuntimeSecurityPolicy['htmlPolicy'] {
+  return readRuntimePolicy().htmlPolicy;
+}

package/src/runtime/receipt-chain.ts

@@ -0,0 +1,106 @@
+import { DAG, Diagnostics } from '@czap/core';
+import type { Receipt, UIFrame } from '@czap/core';
+
+type ReceiptEnvelope = Receipt.Envelope;
+type ReceiptTrustMode = 'advisory-unverified';
+
+interface ReceiptChainShape {
+  rememberFrame(frame: UIFrame): void;
+  ingestEnvelope(envelope: ReceiptEnvelope): boolean;
+  hasFramesAfter(receiptId: string | null): boolean;
+  getFramesAfter(receiptId: string | null): readonly UIFrame[];
+  latestReceiptId(): string | null;
+  trustMode(): ReceiptTrustMode;
+}
+
+/**
+ * Build a new in-memory receipt chain. Owns a DAG of ingested receipt
+ * envelopes plus a map of remembered frames keyed by receipt id, so
+ * the LLM directive can replay gaps when the SSE stream reconnects.
+ *
+ * The chain currently treats signatures as advisory; a diagnostic is
+ * emitted when signed envelopes arrive without a configured verifier.
+ */
+export function createReceiptChain(): ReceiptChainShape {
+  let dag = DAG.empty();
+  const framesByReceipt = new Map<string, UIFrame>();
+  const orderedReceipts: string[] = [];
+
+  const orderedFrameIds = (): readonly string[] => {
+    if (DAG.size(dag) > 0) {
+      const ids = DAG.linearize(dag)
+        .map((envelope) => envelope.hash)
+        .filter((hash) => framesByReceipt.has(hash));
+      if (ids.length > 0) {
+        return ids;
+      }
+    }
+
+    return orderedReceipts;
+  };
+
+  return {
+    rememberFrame(frame) {
+      framesByReceipt.set(frame.receiptId, frame);
+      if (!orderedReceipts.includes(frame.receiptId)) {
+        orderedReceipts.push(frame.receiptId);
+      }
+    },
+
+    ingestEnvelope(envelope) {
+      if (envelope.signature) {
+        Diagnostics.warnOnce({
+          source: 'czap/astro.receipt-chain',
+          code: 'receipt-signature-unverified',
+          message:
+            'Receipt signatures are present but runtime ingestion treats them as advisory metadata until verification is configured.',
+        });
+      }
+
+      dag = DAG.ingest(dag, envelope);
+      return true;
+    },
+
+    hasFramesAfter(receiptId) {
+      const ids = orderedFrameIds();
+      if (ids.length === 0) {
+        return false;
+      }
+
+      if (receiptId === null) {
+        return ids.length > 0;
+      }
+
+      const index = ids.indexOf(receiptId);
+      if (index === -1) {
+        return false;
+      }
+
+      return index < ids.length - 1;
+    },
+
+    getFramesAfter(receiptId) {
+      const ids = orderedFrameIds();
+      if (receiptId === null) {
+        return ids.map((id) => framesByReceipt.get(id)!).filter(Boolean);
+      }
+      const index = ids.indexOf(receiptId);
+      if (index === -1) {
+        return [];
+      }
+      return ids
+        .slice(index + 1)
+        .map((id) => framesByReceipt.get(id)!)
+        .filter(Boolean);
+    },
+
+    latestReceiptId() {
+      const ids = orderedFrameIds();
+      return ids.length > 0 ? ids[ids.length - 1]! : null;
+    },
+
+    trustMode() {
+      return 'advisory-unverified';
+    },
+  };
+}