@ixo/oracle-runtime-workers 0.30.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {
@@ -21,7 +21,8 @@
     "./gateway": "./src/gateway-worker.ts",
     "./hub-actions/client": "./src/hub-actions/client.ts",
     "./hub-actions/request": "./src/hub-actions/request.ts",
-    "./prompt": "./src/core/prompt-composer.ts"
+    "./prompt": "./src/core/prompt-composer.ts",
+    "./plugins/yoma": "./src/plugins/yoma/index.ts"
   },
   "files": [
     "src",
@@ -33,7 +34,7 @@
     "!src/plugins/pod-creator/test-fixtures.ts"
   ],
   "dependencies": {
-    "@ixo/action-protocol": "0.6.0",
+    "@ixo/action-protocol": "0.8.0",
     "@blocknote/server-util": "0.29.1",
     "@composio/core": "0.10.0",
     "@composio/langchain": "0.9.2",
@@ -65,9 +66,10 @@
     "@ixo/impactxclient-sdk": "^3.0.0",
     "protobufjs": "^7.6.5",
     "@ixo/topic-protocol": "1.0.0-rc.8",
+    "survey-core": "2.3.11",
     "@ixo/common": "1.7.1",
-    "@ixo/ixo-transaction": "0.2.0",
-    "@ixo/ucan": "2.3.0"
+    "@ixo/ucan": "2.3.0",
+    "@ixo/ixo-transaction": "0.2.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

package/src/attachments/channel-links.ts

@@ -0,0 +1,135 @@
+/**
+ * The links behind a session's channel files (`channel.ts`), kept in the
+ * user's own SQLite file in their own table, apart from the messages: the
+ * messages, the model and the transcript carry only the `channel:`
+ * reference, and `view_attachment` resolves it here once the turn that
+ * brought the file has ended. A row lives until its link expires (the
+ * gateway signs links for 30 days; `exp` in the link) and goes with its
+ * session (`forgetSession`). Failures are logged and treated as a miss: a
+ * missing link makes the file unavailable, never the turn.
+ */
+import type { DoSqliteDatabase } from '../sqlite/database';
+import type { Logger } from '../plugin-api/types';
+import type { ChannelMediaLink } from './channel';
+
+/** The gateway's link lifetime, for a link that carries no readable `exp`. */
+export const CHANNEL_LINK_DEFAULT_TTL_MS = 30 * 24 * 3600 * 1000;
+
+/** When `url` stops working: its `exp` (unix seconds), else 30 days from `now`. */
+export function channelLinkExpiry(url: string, now: number): number {
+  let exp: string | null = null;
+  try {
+    exp = new URL(url).searchParams.get('exp');
+  } catch {
+    exp = null;
+  }
+  return exp && /^\d{1,12}$/.test(exp)
+    ? Number(exp) * 1000
+    : now + CHANNEL_LINK_DEFAULT_TTL_MS;
+}
+
+export class ChannelAttachmentLinkStore {
+  private setupPromise: Promise<void> | undefined;
+
+  constructor(
+    private readonly db: Pick<DoSqliteDatabase, 'run' | 'get'>,
+    private readonly log: Pick<Logger, 'warn'>,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  private setup(): Promise<void> {
+    this.setupPromise ??= this.createTables().catch((error: unknown) => {
+      this.setupPromise = undefined;
+      throw error;
+    });
+    return this.setupPromise;
+  }
+
+  private async createTables(): Promise<void> {
+    await this.db.run(
+      `CREATE TABLE IF NOT EXISTS channel_attachment_links (
+         session_id TEXT NOT NULL,
+         ref TEXT NOT NULL,
+         binding_id TEXT NOT NULL,
+         url TEXT NOT NULL,
+         sha256 TEXT NOT NULL,
+         expires_at INTEGER NOT NULL,
+         UNIQUE (session_id, ref)
+       )`,
+    );
+    await this.db.run(
+      `CREATE INDEX IF NOT EXISTS idx_channel_attachment_links_expiry
+       ON channel_attachment_links(expires_at)`,
+    );
+  }
+
+  /** Keep the links of a turn's files for its session (a resend refreshes them). */
+  async put(
+    sessionId: string,
+    links: ReadonlyArray<ChannelMediaLink & { ref: string }>,
+  ): Promise<void> {
+    if (links.length === 0) return;
+    try {
+      await this.setup();
+      const now = this.now();
+      for (const link of links)
+        await this.db.run(
+          `INSERT OR REPLACE INTO channel_attachment_links
+             (session_id, ref, binding_id, url, sha256, expires_at)
+           VALUES (?, ?, ?, ?, ?, ?)`,
+          [
+            sessionId,
+            link.ref,
+            link.bindingId,
+            link.url,
+            link.sha256,
+            channelLinkExpiry(link.url, now),
+          ],
+        );
+      await this.db.run(
+        'DELETE FROM channel_attachment_links WHERE expires_at <= ?',
+        [now],
+      );
+    } catch (error) {
+      this.log.warn(
+        `[attachments] could not keep the channel file links of ${sessionId}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  /** The unexpired link behind `ref` in `sessionId`, if one is kept. */
+  async get(
+    sessionId: string,
+    ref: string,
+  ): Promise<ChannelMediaLink | undefined> {
+    try {
+      await this.setup();
+      const row = await this.db.get<{
+        url: string;
+        sha256: string;
+        binding_id: string;
+      }>(
+        `SELECT url, sha256, binding_id FROM channel_attachment_links
+         WHERE session_id = ? AND ref = ? AND expires_at > ?`,
+        [sessionId, ref, this.now()],
+      );
+      return row
+        ? { url: row.url, sha256: row.sha256, bindingId: row.binding_id }
+        : undefined;
+    } catch (error) {
+      this.log.warn(
+        `[attachments] channel file link read failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return undefined;
+    }
+  }
+
+  /** Drop every link of a deleted session. */
+  async forgetSession(sessionId: string): Promise<void> {
+    await this.setup();
+    await this.db.run(
+      'DELETE FROM channel_attachment_links WHERE session_id = ?',
+      [sessionId],
+    );
+  }
+}

package/src/attachments/channel.ts

@@ -0,0 +1,203 @@
+/**
+ * Files the person sent on an IXO Channels turn. The channel gateway keeps
+ * each file and serves it from a signed link of its own,
+ * `https://<gateway host>/media/<binding id>/<object id>?exp=…&kid=…&sig=…`,
+ * valid for 30 days. That link is a bearer capability: it never enters
+ * model context, hidden notes, stored message metadata or traces. The model,
+ * the transcript and `view_attachment` name a channel file by an opaque
+ * reference, `channel:<the first 16 hex digits of its sha256>`, and the
+ * owner object resolves it to the link server-side (`ChannelMediaSource`):
+ * from the turn's own list, else from the links it keeps for the session
+ * (`ChannelAttachmentLinkStore`).
+ *
+ * A link is fetched only when it is the gateway's own (its origin is the
+ * host of a `did:web` in `CHANNEL_SERVICE_DID` and its path lies under
+ * `/media/<the binding the file came on>/`), without following redirects,
+ * and the bytes are kept only when their SHA-256 is the one the gateway
+ * sent. The file always goes to a model as these bytes, never by URL.
+ */
+import {
+  AttachmentRejectedError,
+  AttachmentTooLargeError,
+  downloadFromUrl,
+} from './download';
+
+export const CHANNEL_REF_PREFIX = 'channel:';
+
+/**
+ * The gateway's per-file bound for a video or a document
+ * (`maxLargeMediaBytes`, 50 MiB); photos are at most 16 MB there. A file
+ * above `MAX_FILE_SIZE` is archived to the sandbox but never handed to a
+ * model (see the pipeline).
+ */
+export const CHANNEL_MAX_FILE_BYTES = 52_428_800;
+
+/** The opaque reference of a channel file: `channel:` + 16 hex digits of its sha256. */
+export function channelAttachmentRef(sha256: string): string {
+  return `${CHANNEL_REF_PREFIX}${sha256.slice(0, 16)}`;
+}
+
+export function isChannelAttachmentRef(ref: string): boolean {
+  return /^channel:[0-9a-f]{16}$/.test(ref);
+}
+
+/** What the owner object knows of a channel file: never shown to a model. */
+export interface ChannelMediaLink {
+  url: string;
+  /** Lowercase hex SHA-256 of the bytes the gateway serves. */
+  sha256: string;
+  /** The binding the file arrived on: its link lies under `/media/<bindingId>/`. */
+  bindingId: string;
+}
+
+/**
+ * A channel file the gateway could not serve as sent (the link expired,
+ * was refused, or is not the gateway's own): noted, never retried, and
+ * described without its link.
+ */
+export class ChannelFileUnavailableError extends AttachmentRejectedError {
+  override readonly name: string = 'ChannelFileUnavailableError';
+}
+
+/** The https origins of the gateways allowed to call this deployment. */
+export function channelMediaOrigins(
+  channelServiceDids: readonly string[],
+): string[] {
+  const origins = new Set<string>();
+  for (const did of channelServiceDids) {
+    const host = /^did:web:([a-z0-9.-]+)$/.exec(did)?.[1];
+    if (host) origins.add(`https://${host}`);
+  }
+  return [...origins];
+}
+
+/** Whether `link.url` is the gateway's own link for a file of `link.bindingId`. */
+export function isGatewayMediaUrl(
+  link: Pick<ChannelMediaLink, 'url' | 'bindingId'>,
+  origins: readonly string[],
+): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(link.url);
+  } catch {
+    return false;
+  }
+  const prefix = `/media/${link.bindingId}/`;
+  return (
+    parsed.protocol === 'https:' &&
+    !parsed.username &&
+    !parsed.password &&
+    origins.includes(parsed.origin) &&
+    parsed.pathname.startsWith(prefix) &&
+    parsed.pathname.length > prefix.length &&
+    !parsed.pathname.slice(prefix.length).includes('/')
+  );
+}
+
+function hex(bytes: ArrayBuffer): string {
+  return Array.from(new Uint8Array(bytes), (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('');
+}
+
+/**
+ * The bytes of a channel file. Every failure is described without the
+ * link: a refused or expired link, a redirect or a transport error is
+ * `ChannelFileUnavailableError`, and so are bytes whose SHA-256 is not the
+ * one the gateway sent; a file over `maxBytes` stays an
+ * `AttachmentTooLargeError`, and an abort keeps its reason.
+ */
+export async function downloadChannelFile(
+  link: ChannelMediaLink,
+  opts: {
+    origins: readonly string[];
+    maxBytes: number;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+  },
+): Promise<{ bytes: Uint8Array; contentType?: string }> {
+  if (!isGatewayMediaUrl(link, opts.origins))
+    throw new ChannelFileUnavailableError(
+      'its link is not one this channel gateway serves',
+    );
+  let result: Awaited<ReturnType<typeof downloadFromUrl>>;
+  try {
+    result = await downloadFromUrl(link.url, {
+      ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+      ...(opts.signal ? { signal: opts.signal } : {}),
+      ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+      maxBytes: opts.maxBytes,
+      maxRedirects: 0,
+    });
+  } catch (error) {
+    if (opts.signal?.aborted) throw error;
+    if (error instanceof AttachmentTooLargeError) throw error;
+    const status =
+      error instanceof Error ? /^HTTP (\d{3}) /.exec(error.message)?.[1] : '';
+    throw new ChannelFileUnavailableError(
+      status
+        ? `the channel gateway answered ${status}`
+        : 'the channel gateway could not be reached',
+    );
+  }
+  const digest = hex(await crypto.subtle.digest('SHA-256', result.data));
+  if (digest !== link.sha256)
+    throw new ChannelFileUnavailableError(
+      'its bytes do not match the digest the channel sent',
+    );
+  return {
+    bytes: result.data,
+    ...(result.contentType ? { contentType: result.contentType } : {}),
+  };
+}
+
+/** How the attachment layer reads a `channel:` reference (built by the owner object). */
+export interface ChannelMediaSource {
+  load(
+    ref: string,
+    opts: {
+      maxBytes: number;
+      fetchImpl?: typeof fetch;
+      signal?: AbortSignal;
+      timeoutMs?: number;
+    },
+  ): Promise<{ bytes: Uint8Array; contentType?: string }>;
+}
+
+/**
+ * A `ChannelMediaSource` over `resolve` (the turn's files, then the
+ * session's stored links) for the gateways in `origins`.
+ */
+export function createChannelMediaSource(input: {
+  resolve: (ref: string) => Promise<ChannelMediaLink | undefined>;
+  origins: readonly string[];
+}): ChannelMediaSource {
+  return {
+    load: async (ref, opts) => {
+      const link = await input.resolve(ref);
+      if (!link)
+        throw new ChannelFileUnavailableError(
+          'it is no longer available here; ask the person to send it again',
+        );
+      return downloadChannelFile(link, { ...opts, origins: input.origins });
+    },
+  };
+}
+
+/**
+ * The sandbox archive name of a channel file: the cleaned name with the
+ * first 12 hex digits of its digest before the extension
+ * (`photo-0123456789ab.jpg`), so two photos the gateway names alike never
+ * overwrite each other.
+ */
+export function channelArchiveName(safeName: string, ref: string): string {
+  const tag = ref.slice(
+    CHANNEL_REF_PREFIX.length,
+    CHANNEL_REF_PREFIX.length + 12,
+  );
+  const dot = safeName.lastIndexOf('.');
+  return dot > 0
+    ? `${safeName.slice(0, dot)}-${tag}${safeName.slice(dot)}`
+    : `${safeName}-${tag}`;
+}

package/src/attachments/download.ts

@@ -1,9 +1,11 @@
 /**
  * Fetching attachment bytes — Matrix media (through the gateway, which holds
- * the authenticated client and the room keys) and plain `http(s)` URLs with
- * the Node runtime's SSRF guard, manual redirect validation and streaming
- * size cap.
+ * the authenticated client and the room keys), channel files (through the
+ * owner object's `ChannelMediaSource`, see `channel.ts`) and plain `http(s)`
+ * URLs with the Node runtime's SSRF guard, manual redirect validation and
+ * streaming size cap.
  */
+import type { ChannelMediaSource } from './channel';
 import { containerMatchesClaim, detectMimeFromMagicBytes } from './magic';
 import type { AttachmentInput } from './types';
 
@@ -142,6 +144,10 @@ export interface DownloadOptions {
   signal?: AbortSignal;
   timeoutMs?: number;
   maxBytes?: number;
+  /** Redirects followed (each hop SSRF-checked); default `MAX_REDIRECT_COUNT`. */
+  maxRedirects?: number;
+  /** Where a `channelRef` attachment's bytes come from; absent = none can be read. */
+  channel?: ChannelMediaSource;
 }
 
 /**
@@ -248,7 +254,7 @@ export async function downloadFromUrl(
   try {
     let currentUrl = url;
     let response: Response | undefined;
-    for (let i = 0; i <= MAX_REDIRECT_COUNT; i += 1) {
+    for (let i = 0; i <= (opts.maxRedirects ?? MAX_REDIRECT_COUNT); i += 1) {
       response = await fetchImpl(currentUrl, {
         signal: bound.signal,
         redirect: 'manual',
@@ -307,7 +313,7 @@ export async function loadAttachmentBytes(
   source: MatrixMediaSource,
   opts: DownloadOptions = {},
 ): Promise<{ bytes: Uint8Array; mimetype: string; sniffed: boolean }> {
-  if (!attachment.eventId && !attachment.mxcUri) {
+  if (!attachment.eventId && !attachment.mxcUri && !attachment.channelRef) {
     throw new Error('Either mxcUri or eventId must be provided');
   }
   if (attachment.mxcUri && !ALLOWED_URI_SCHEMES.test(attachment.mxcUri)) {
@@ -320,7 +326,18 @@ export async function loadAttachmentBytes(
 
   let bytes: Uint8Array;
   let httpType: string | undefined;
-  if (attachment.eventId || attachment.mxcUri!.startsWith('mxc://')) {
+  if (attachment.channelRef) {
+    if (!opts.channel)
+      throw new Error('Channel files cannot be read on this host');
+    const loaded = await opts.channel.load(attachment.channelRef, {
+      maxBytes,
+      ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+      ...(opts.signal ? { signal: opts.signal } : {}),
+      ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+    });
+    bytes = loaded.bytes;
+    httpType = loaded.contentType;
+  } else if (attachment.eventId || attachment.mxcUri!.startsWith('mxc://')) {
     const bound = boundedSignal(
       opts.signal,
       opts.timeoutMs ?? DOWNLOAD_TIMEOUT_MS,

package/src/attachments/index.ts

@@ -1,3 +1,22 @@
+export {
+  CHANNEL_MAX_FILE_BYTES,
+  CHANNEL_REF_PREFIX,
+  channelArchiveName,
+  channelAttachmentRef,
+  ChannelFileUnavailableError,
+  channelMediaOrigins,
+  createChannelMediaSource,
+  downloadChannelFile,
+  isChannelAttachmentRef,
+  isGatewayMediaUrl,
+  type ChannelMediaLink,
+  type ChannelMediaSource,
+} from './channel';
+export {
+  CHANNEL_LINK_DEFAULT_TTL_MS,
+  ChannelAttachmentLinkStore,
+  channelLinkExpiry,
+} from './channel-links';
 export { classifyAttachment, type AttachmentKind } from './classify';
 export {
   buildUserMessageContent,
@@ -40,6 +59,7 @@ export {
   type FileCategory,
 } from './magic';
 export {
+  attachmentMetaFor,
   nativeAttachmentNote,
   prepareAttachments,
   SANDBOX_TRUNCATE_LIMIT,
@@ -61,8 +81,11 @@ export {
   type SandboxUploadResult,
 } from './sandbox-archive';
 export {
+  NOTE_FILENAME_MAX,
+  NOTE_MIMETYPE_MAX,
   SANDBOX_OUTPUT_PREFIX,
   sanitizeAttachmentFilename,
+  sanitizeNoteField,
   sanitizeSandboxPath,
 } from './sanitize';
 export {