@ixo/oracle-runtime-workers 0.12.0 → 0.15.0

package/src/shell/auth.ts

@@ -5,9 +5,18 @@
  *  - Primary:  `Authorization: Bearer <invocation>` + `X-Auth-Type: ucan` — a
  *    user-self-signed root invocation for `{ can: '*', with: 'ixo:oracle' }`
  *    addressed to this oracle's DID. Proves WHO is calling; short TTL.
- *  - Fallback: `x-ucan-delegation: <base64 CAR>` — accepted alone for legacy
- *    clients and always used for downstream authorization when present. A
- *    delegation is only trusted when its issuer equals the authenticated DID.
+ *  - `x-ucan-delegation: <base64 CAR>` — authorization material for the
+ *    runtime's downstream calls, used when present. It does NOT
+ *    authenticate on its own: a delegation is a grant the user hands to
+ *    this oracle and it travels on as proof in the invocations the runtime
+ *    mints for other services, so anyone who has seen one could otherwise
+ *    present it and act as the user. `UCAN_ALLOW_BARE_DELEGATION_AUTH=true`
+ *    restores the old fallback for clients that do not send an invocation
+ *    yet (the shell logs a deprecation warning per request). A delegation
+ *    is only trusted when its issuer equals the authenticated DID and it
+ *    expires: a delegation with no expiry anywhere in its chain is refused,
+ *    since the runtime stores it and mints on it long after the request,
+ *    and nothing else would ever end it.
  *
  * The returned `userDid` is always the cryptographically recovered signer,
  * never a client-claimed value. `did:ixo` keys resolve through Blocksync.
@@ -18,25 +27,53 @@ import {
   createIxoDIDResolver,
   createUCANValidator,
   defineCapability,
-  InMemoryInvocationStore,
+  type DIDKeyResolver,
+  type InvocationStore,
 } from '@ixo/ucan';
 
 /**
- * One replay-protection store per isolate, WITHOUT the library's hourly
- * `setInterval` sweep: a pending timer keeps a Durable Object resident, and
- * this code also runs inside the user object (socket CONNECT auth), where a
- * leaked interval per CONNECT blocked WebSocket hibernation entirely. Expired
- * entries are dropped lazily on lookup and swept every N validations instead.
+ * The shell keeps no replay marks. An auth invocation is a bearer token the
+ * client reuses for its whole (short, `UCAN_AUTH_MAX_TTL_SECONDS`-bounded)
+ * lifetime, often on several requests at once, so a single-use mark would
+ * refuse legitimate repeats. A no-op store also keeps the library from
+ * creating its default store, whose hourly `setInterval` would keep a Durable
+ * Object resident (this code also runs inside the user object for socket
+ * CONNECT auth) and block WebSocket hibernation.
  */
-const invocationStore = new InMemoryInvocationStore({
-  enableAutoCleanup: false,
-});
-const SWEEP_EVERY = 500;
-let validations = 0;
+const reusableInvocations: InvocationStore = {
+  has: async () => false,
+  add: async () => undefined,
+  addIfAbsent: async () => true,
+};
 
-function sweepInvocationStore(): void {
-  validations += 1;
-  if (validations % SWEEP_EVERY === 0) void invocationStore.cleanup();
+/**
+ * did:ixo key lookups are cached per isolate for this long. A key rotated out
+ * of, or removed from, a DID document on-chain is still trusted for up to
+ * this long after the change. Failed lookups are never cached.
+ */
+export const IXO_DID_RESOLUTION_CACHE_TTL_MS = 60_000;
+/** Distinct Blocksync URLs that keep a resolver; a deployment uses one. */
+const MAX_IXO_RESOLVERS = 8;
+const ixoResolvers = new Map<string, DIDKeyResolver>();
+
+/**
+ * The isolate's did:ixo resolver for one Blocksync GraphQL URL, built once and
+ * reused so its resolution cache and in-flight de-duplication span requests.
+ * Each lookup keeps the library's default timeout.
+ */
+export function sharedIxoDIDResolver(indexerUrl: string): DIDKeyResolver {
+  const existing = ixoResolvers.get(indexerUrl);
+  if (existing) return existing;
+  if (ixoResolvers.size >= MAX_IXO_RESOLVERS) {
+    const oldest = ixoResolvers.keys().next().value;
+    if (oldest !== undefined) ixoResolvers.delete(oldest);
+  }
+  const resolver = createIxoDIDResolver({
+    indexerUrl,
+    cacheTtlMs: IXO_DID_RESOLUTION_CACHE_TTL_MS,
+  });
+  ixoResolvers.set(indexerUrl, resolver);
+  return resolver;
 }
 
 export const DEFAULT_UCAN_AUTH_MAX_TTL_SECONDS = 900;
@@ -48,8 +85,34 @@ export interface AuthConfig {
   oracleDid: string;
   blocksyncUri: string;
   maxTtlSeconds?: number;
+  /**
+   * Accept a bare `x-ucan-delegation` (no invocation) as authentication, the
+   * legacy fallback. Off unless `UCAN_ALLOW_BARE_DELEGATION_AUTH=true`.
+   */
+  allowBareDelegation?: boolean;
+}
+
+/** The auth config of a deployment, from its raw Worker env (shell and user object alike). */
+export function authConfigFromEnv(env: {
+  ORACLE_DID: string;
+  BLOCKSYNC_GRAPHQL_URL: string;
+  UCAN_AUTH_MAX_TTL_SECONDS?: string;
+  UCAN_ALLOW_BARE_DELEGATION_AUTH?: string;
+}): AuthConfig {
+  return {
+    oracleDid: env.ORACLE_DID,
+    blocksyncUri: env.BLOCKSYNC_GRAPHQL_URL,
+    ...(env.UCAN_AUTH_MAX_TTL_SECONDS
+      ? { maxTtlSeconds: Number(env.UCAN_AUTH_MAX_TTL_SECONDS) }
+      : {}),
+    allowBareDelegation: env.UCAN_ALLOW_BARE_DELEGATION_AUTH === 'true',
+  };
 }
 
+/** The 401 a bare delegation gets while the fallback is off. */
+export const INVOCATION_REQUIRED_ERROR =
+  'UCAN invocation required: send Authorization: Bearer <invocation> with X-Auth-Type: ucan. An x-ucan-delegation alone no longer authenticates; send it beside the invocation.';
+
 export interface AuthResult {
   userDid: string;
   /** Raw delegation CAR when the client supplied a valid one for this user. */
@@ -91,10 +154,7 @@ class TtlCache<T> {
 }
 
 const invocationCache = new TtlCache<{ userDid: string; expiration: number }>();
-const delegationCache = new TtlCache<{
-  userDid: string;
-  expiration?: number;
-}>();
+const delegationCache = new TtlCache<{ userDid: string; expiration: number }>();
 
 async function sha256(text: string): Promise<string> {
   const digest = await crypto.subtle.digest(
@@ -106,23 +166,45 @@ async function sha256(text: string): Promise<string> {
     .join('');
 }
 
+type InvocationVerdict =
+  | { ok: true; userDid: string; expiration: number }
+  | { ok: false; error: string };
+
+/**
+ * Verifications in progress, by token hash. Concurrent requests carrying one
+ * invocation (a page load firing several queries with the same token) share
+ * one verification; the entry is dropped as soon as it settles, so a failure
+ * reaches only the callers that were already waiting on it.
+ */
+const pendingInvocations = new Map<string, Promise<InvocationVerdict>>();
+
 async function validateInvocation(
   invocation: string,
   cfg: AuthConfig,
-): Promise<
-  | { ok: true; userDid: string; expiration: number }
-  | { ok: false; error: string }
-> {
+): Promise<InvocationVerdict> {
   const key = await sha256(invocation);
   const cached = invocationCache.get(key);
   if (cached) return { ok: true, ...cached };
 
-  sweepInvocationStore();
+  const pending = pendingInvocations.get(key);
+  if (pending) return pending;
+  const verification = verifyInvocation(invocation, key, cfg).finally(() => {
+    pendingInvocations.delete(key);
+  });
+  pendingInvocations.set(key, verification);
+  return verification;
+}
+
+async function verifyInvocation(
+  invocation: string,
+  key: string,
+  cfg: AuthConfig,
+): Promise<InvocationVerdict> {
   const validator = await createUCANValidator({
     serverDid: cfg.oracleDid,
     rootIssuers: ['*'],
-    didResolver: createIxoDIDResolver({ indexerUrl: cfg.blocksyncUri }),
-    invocationStore,
+    didResolver: sharedIxoDIDResolver(cfg.blocksyncUri),
+    invocationStore: reusableInvocations,
   });
   const result = await validator.validate(
     invocation,
@@ -156,23 +238,28 @@ async function validateInvocation(
   return { ok: true, ...verdict };
 }
 
-async function validateDelegation(
+/**
+ * Validate a delegation for this oracle: signatures, audience, proof chain,
+ * not expired, and a bounded expiry (the earliest across the chain).
+ * `userDid` is the delegation's issuer.
+ */
+export async function validateDelegation(
   header: string,
   cfg: AuthConfig,
 ): Promise<
-  | { ok: true; userDid: string; expiration?: number }
+  | { ok: true; userDid: string; expiration: number }
   | { ok: false; error: string }
 > {
   const key = await sha256(header);
   const cached = delegationCache.get(key);
   if (cached) return { ok: true, ...cached };
 
-  sweepInvocationStore();
   const validator = await createUCANValidator({
     serverDid: cfg.oracleDid,
     rootIssuers: [],
-    didResolver: createIxoDIDResolver({ indexerUrl: cfg.blocksyncUri }),
-    invocationStore,
+    didResolver: sharedIxoDIDResolver(cfg.blocksyncUri),
+    invocationStore: reusableInvocations,
+    requireExpiration: true,
   });
   const result = await validator.validateDelegation(header);
   if (!result.ok)
@@ -182,11 +269,13 @@ async function validateDelegation(
     };
   if (!result.invoker)
     return { ok: false, error: 'Delegation validated without an invoker DID' };
+  // The validator refuses an unbounded chain; this also covers a validator
+  // that reported success without the effective expiry.
+  if (typeof result.expiration !== 'number' || !isFinite(result.expiration)) {
+    return { ok: false, error: 'Delegation must declare an expiration' };
+  }
   const verdict = { userDid: result.invoker, expiration: result.expiration };
-  const ttlMs =
-    typeof result.expiration === 'number'
-      ? Math.max(1000, result.expiration * 1000 - Date.now())
-      : THREE_MINUTES_MS;
+  const ttlMs = Math.max(1000, result.expiration * 1000 - Date.now());
   delegationCache.set(key, verdict, Math.min(ttlMs, THREE_MINUTES_MS));
   return { ok: true, ...verdict };
 }
@@ -216,6 +305,11 @@ export async function authenticate(
         'Missing Authorization (UCAN invocation) or x-ucan-delegation header',
     };
   }
+  // A delegation proves what the user granted this oracle, not who is
+  // calling; it authenticates only through the opt-in legacy fallback.
+  if (!invocation && !cfg.allowBareDelegation) {
+    return { ok: false, status: 401, error: INVOCATION_REQUIRED_ERROR };
+  }
 
   let userDid: string | null = null;
   let via: AuthResult['via'] = 'delegation';

package/src/shell/turn-body-cap.ts

@@ -1,19 +1,17 @@
 /**
  * Upper bound on a chat turn's request body (`POST /messages/:sessionId`).
  *
- * The cap bounds the memory one request can pin: the shell reads the body in
- * full before forwarding it to the user object. It no longer mirrors the Node
- * runtime, which keeps Express body-parser's 100 kb default — a normal Portal
- * turn now exceeds that. Every turn carries the browser-tool catalogue (26–32
- * tools, 65–70 KiB of JSON schema) and the AG-UI action schemas (~27 KiB)
- * before the message text, and a compose-topic turn adds the pinned text in
+ * The cap bounds the memory one request can pin: the shell enforces it
+ * before reading the body (`bodyLimit` — the declared length, or a count of
+ * the streamed bytes), so an oversized body is refused with 413 without
+ * ever being buffered. It no longer mirrors the Node runtime, which keeps
+ * Express body-parser's 100 kb default — a normal Portal turn now exceeds
+ * that. Every turn carries the browser-tool catalogue (26–32 tools, 65–70
+ * KiB of JSON schema) and the AG-UI action schemas (~27 KiB) before the
+ * message text, and a compose-topic turn adds the pinned text in
  * `metadata.contextToolCall`; on devnet turns of 102–115 KiB were refused.
- * 256 KiB leaves room for those. Attachments never count: files go to Matrix
- * media first and the body carries only their references.
+ * 256 KiB leaves room for those. Attachments never count: files go to
+ * Matrix media first and the body carries only their references. The cap
+ * counts UTF-8 bytes, as the wire carries them.
  */
 export const MAX_TURN_BODY_BYTES = 256 * 1024;
-
-/** Whether a raw body is over the cap, measured as the UTF-8 bytes the wire carried. */
-export function turnBodyTooLarge(body: string): boolean {
-  return new TextEncoder().encode(body).byteLength > MAX_TURN_BODY_BYTES;
-}

package/src/sqlite/blob-compactor.ts

@@ -6,7 +6,11 @@
  * which is what makes multi-GB users multi-GB — only shrinks if rewritten.
  * `compactStep` rewrites a bounded batch per call so the user object's alarm
  * can chip away at arbitrarily large files without ever hogging a tick;
- * `finishCompaction` reclaims the freed pages once nothing is left.
+ * `finishCompaction` reclaims the freed pages once nothing is left. A step
+ * is bounded by rows AND by legacy bytes (`COMPACT_STEP_MAX_BYTES`): it
+ * reads one blob at a time and holds every page it rewrites until its
+ * COMMIT, so a batch of tool outputs with embedded media must not be able
+ * to exhaust the isolate's memory.
  *
  * Lossless by construction: each row's blob is read, gzipped, and written
  * back — the read path decompresses transparently, so the decoded value is
@@ -36,6 +40,12 @@ const TARGETS: readonly CompactTarget[] = [
 
 const textEncoder = new TextEncoder();
 
+/**
+ * Legacy bytes one step reads and rewrites at most — except that a step
+ * always takes at least one row, however large, so it never stalls.
+ */
+export const COMPACT_STEP_MAX_BYTES = 8 * 1024 * 1024;
+
 /** Highest rowid examined per table; persist between calls, `{}` to start. */
 export type CompactCursors = Record<string, number>;
 
@@ -46,6 +56,8 @@ export interface CompactStepResult {
   savedBytes: number;
   /** Rows examined (incl. incompressible ones passed over). */
   examined: number;
+  /** Legacy bytes of the rows examined. */
+  examinedBytes: number;
   /** True once every table's scan is exhausted. */
   done: boolean;
   /** Updated cursors — persist and pass into the next call. */
@@ -53,73 +65,94 @@ export interface CompactStepResult {
 }
 
 /**
- * Examine up to `batch` legacy rows and rewrite the compressible ones as
- * gzipped blobs. Call repeatedly (persisting `cursors`) until `done`.
+ * Examine up to `batch` legacy rows — and at most `maxBytes` of them (at
+ * least one row) — and rewrite the compressible ones as gzipped blobs.
+ * Call repeatedly (persisting `cursors`) until `done`. Where the steps end
+ * changes nothing about the result: rows are visited in the same order and
+ * each is rewritten exactly as an unbounded run would.
  */
 export async function compactStep(
   db: DoSqliteDatabase,
   batch = 200,
   cursors: CompactCursors = {},
+  opts: { maxBytes?: number } = {},
 ): Promise<CompactStepResult> {
+  const maxBytes = opts.maxBytes ?? COMPACT_STEP_MAX_BYTES;
   // One transaction per step: the batch lands atomically and cannot
   // interleave with a turn's own checkpoint transaction.
-  return db.transaction(() => compactStepInTx(db, batch, cursors));
+  return db.transaction(() => compactStepInTx(db, batch, maxBytes, cursors));
 }
 
 async function compactStepInTx(
   db: DoSqliteDatabase,
   batch: number,
+  maxBytes: number,
   cursors: CompactCursors,
 ): Promise<CompactStepResult> {
   let budget = batch;
   let rewritten = 0;
   let savedBytes = 0;
   let examined = 0;
+  let examinedBytes = 0;
+  let full = false;
   let exhausted = true;
   const next: CompactCursors = { ...cursors };
 
   for (const { table, column } of TARGETS) {
     let cursor = next[table] ?? 0;
     while (budget > 0) {
-      const rows = await db.exec<{ rowid: number; data: Uint8Array | string }>(
+      // One candidate at a time: the filter loads each value it examines,
+      // so a batched query would read every candidate behind the budget.
+      const row = await db.get<{ rowid: number; data: Uint8Array | string }>(
         `SELECT rowid, ${column} AS data FROM ${table}
          WHERE rowid > ?
            AND ${column} IS NOT NULL
            AND length(${column}) >= ?
            AND substr(${column}, 1, 2) != X'1F8B'
          ORDER BY rowid
-         LIMIT ?`,
-        [cursor, MIN_COMPRESS_BYTES, budget],
+         LIMIT 1`,
+        [cursor, MIN_COMPRESS_BYTES],
       );
-      if (rows.length === 0) break;
-      for (const { rowid, data } of rows) {
-        cursor = Math.max(cursor, rowid);
-        budget -= 1;
-        examined += 1;
-        const bytes =
-          typeof data === 'string' ? textEncoder.encode(data) : data;
-        if (isGzip(bytes)) continue;
-        const compressed = await gzipBytes(bytes);
-        // Incompressible (already-compressed media): leave as-is; the cursor
-        // has moved past it, so it is never re-attempted.
-        if (compressed.length >= bytes.length) continue;
-        await db.run(`UPDATE ${table} SET ${column} = ? WHERE rowid = ?`, [
-          compressed,
-          rowid,
-        ]);
-        rewritten += 1;
-        savedBytes += bytes.length - compressed.length;
+      if (row === undefined) break;
+      const bytes =
+        typeof row.data === 'string' ? textEncoder.encode(row.data) : row.data;
+      if (examined > 0 && examinedBytes + bytes.length > maxBytes) {
+        // Left for the next step, which starts with it.
+        full = true;
+        break;
       }
+      cursor = Math.max(cursor, row.rowid);
+      budget -= 1;
+      examined += 1;
+      examinedBytes += bytes.length;
+      if (isGzip(bytes)) continue;
+      const compressed = await gzipBytes(bytes);
+      // Incompressible (already-compressed media): leave as-is; the cursor
+      // has moved past it, so it is never re-attempted.
+      if (compressed.length >= bytes.length) continue;
+      await db.run(`UPDATE ${table} SET ${column} = ? WHERE rowid = ?`, [
+        compressed,
+        row.rowid,
+      ]);
+      rewritten += 1;
+      savedBytes += bytes.length - compressed.length;
     }
     next[table] = cursor;
-    if (budget <= 0) {
-      // Budget ran out mid-table — cannot know whether scans are exhausted.
+    if (budget <= 0 || full) {
+      // A budget ran out mid-table — cannot know whether scans are exhausted.
       exhausted = false;
       break;
     }
   }
 
-  return { rewritten, savedBytes, examined, done: exhausted, cursors: next };
+  return {
+    rewritten,
+    savedBytes,
+    examined,
+    examinedBytes,
+    done: exhausted,
+    cursors: next,
+  };
 }
 
 /**