@ixo/oracle-runtime-workers 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.17.0",
+  "version": "0.18.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": {
@@ -58,9 +58,9 @@
     "wa-sqlite": "1.0.0",
     "yjs": "13.6.32",
     "zod": "^4.4.3",
-    "@ixo/ixo-transaction": "0.1.0",
+    "@ixo/ucan": "2.2.1",
     "@ixo/common": "1.6.0",
-    "@ixo/ucan": "2.2.1"
+    "@ixo/ixo-transaction": "0.1.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

package/src/channels/auth.ts

@@ -289,6 +289,71 @@ export async function assertActiveChannelBinding(
     );
 }
 
+/**
+ * How long an isolate trusts an Auth Hub "active" verdict for one binding
+ * revision and user. A revoked binding is therefore noticed by new
+ * admissions at most this late: inside the lifetime of the channel grant
+ * that authorized the request (at most 300 s, `authenticateChannel`), and
+ * attempts that start later (dequeued, recovered) check again uncached.
+ */
+export const CHANNEL_BINDING_CACHE_TTL_MS = 60_000;
+/** Verdicts an isolate keeps at most; the oldest makes room. */
+export const CHANNEL_BINDING_CACHE_MAX_ENTRIES = 1_000;
+
+/** Positive verdicts only (key → epoch ms it expires); a refusal is never kept. */
+const activeBindings = new Map<string, number>();
+
+/** Forget every cached verdict (tests). */
+export function clearChannelBindingCache(): void {
+  activeBindings.clear();
+}
+
+/**
+ * `assertActiveChannelBinding` for an admission through the shell, with an
+ * "active" verdict cached per isolate for `CHANNEL_BINDING_CACHE_TTL_MS`,
+ * keyed by the oracle, provider, binding, binding revision and user. An
+ * inactive binding (403) or an unavailable Auth Hub (503) is never cached.
+ * Returns whether the Auth Hub was asked.
+ */
+export async function assertActiveChannelBindingCached(
+  identity: TurnIdentity,
+  env: Parameters<typeof assertActiveChannelBinding>[1],
+  now: number = Date.now(),
+): Promise<'cached' | 'checked'> {
+  const channel = identity.channel;
+  const key = channel
+    ? JSON.stringify([
+        env.ORACLE_DID,
+        channel.provider,
+        channel.bindingId,
+        channel.bindingRevision,
+        identity.userDid,
+      ])
+    : null;
+  if (key) {
+    const until = activeBindings.get(key);
+    if (until !== undefined) {
+      if (until > now) return 'cached';
+      activeBindings.delete(key);
+    }
+  }
+  await assertActiveChannelBinding(identity, env);
+  if (!key) return 'checked';
+  if (activeBindings.size >= CHANNEL_BINDING_CACHE_MAX_ENTRIES) {
+    for (const [cached, until] of activeBindings)
+      if (until <= now) activeBindings.delete(cached);
+    // Still full: drop the oldest entry (Map keeps insertion order).
+    const oldest = activeBindings.keys().next();
+    if (
+      activeBindings.size >= CHANNEL_BINDING_CACHE_MAX_ENTRIES &&
+      !oldest.done
+    )
+      activeBindings.delete(oldest.value);
+  }
+  activeBindings.set(key, now + CHANNEL_BINDING_CACHE_TTL_MS);
+  return 'checked';
+}
+
 /**
  * The binding check before a channel attempt executes (a queued run being
  * dequeued, a recovery attempt). An inactive binding (403) ends the run. An

package/src/channels/contract.ts

@@ -93,11 +93,13 @@ export type ChannelErrorStatus =
  * | `identity_mismatch`               | 403    | the channel identity does not match the request       |
  * | `identity_required`               | 403    | the binding check got no channel identity             |
  * | `binding_inactive`                | 403    | the Auth Hub reports the binding inactive             |
- * | `channel_grant_not_tool_authority`| 403    | a channel request carried a delegation header         |
+ * | `channel_grant_not_tool_authority`| 403    | a channel request carried a delegation header         | * | `storage_unauthorized`            | 403    | the user's file storage rejected the oracle (final)   |
  * | `session_not_found`               | 404    | the session is not the user's Companion session       |
  * | `request_conflict`                | 409    | the request id already belongs to another message     |
- * | `session_conflict`                | 409    | the channel is already bound to another session       |
+ * | `session_conflict`                | 409    | another session is bound, or the named one is gone:   |
+ * |                                   |        | resend the same request without `sessionId`           |
  * | `room_not_encrypted`              | 409    | the Companion room is not end-to-end encrypted        |
+ * | `room_unavailable`                | 409    | the oracle cannot use the Companion room (final)      |
  * | `response_expired`                | 410    | the run was pruned; the request cannot run again      |
  * | `request_too_large`               | 413    | the body is over 64 kB                                |
  * | `room_not_ready`                  | 428    | the user has no Companion room yet                    |
@@ -115,10 +117,12 @@ export type ChannelErrorCode =
   | 'identity_required'
   | 'binding_inactive'
   | 'channel_grant_not_tool_authority'
+  | 'storage_unauthorized'
   | 'session_not_found'
   | 'request_conflict'
   | 'session_conflict'
   | 'room_not_encrypted'
+  | 'room_unavailable'
   | 'response_expired'
   | 'request_too_large'
   | 'room_not_ready'
@@ -148,6 +152,32 @@ export class ChannelError extends Error {
   }
 }
 
+/**
+ * The session a channel request would run in does not exist in the user's
+ * object (deleted in Qi.Space, or never created there). It answers like
+ * `session_not_found` wherever it escapes, but admission handles it first:
+ * the binding forgets the session and the request is answered with
+ * `session_conflict` (or, when the request named no session, opens a new
+ * one at once).
+ */
+export class StaleSessionError extends ChannelError {
+  constructor(message = 'Companion session not found') {
+    super(404, message, 'session_not_found');
+    this.name = 'StaleSessionError';
+  }
+}
+
+/**
+ * The run of one channel request: fixed by the binding and the request id,
+ * so every retry, poll and object restart lands on the same run.
+ */
+export async function channelRunId(
+  bindingId: string,
+  requestId: string,
+): Promise<string> {
+  return `channel_${await channelRequestHash(JSON.stringify([bindingId, requestId]))}`;
+}
+
 /**
  * The least lifetime a delegation must have left for a channel turn to be
  * admitted (seconds): a turn, its tool calls and its owner-copy flush must

package/src/channels/failures.ts

@@ -0,0 +1,64 @@
+/**
+ * Failures on the channel path that retrying cannot fix. Everything else a
+ * channel turn throws stays a `503 unavailable` the gateway retries with
+ * backoff; these two are answered as final refusals instead, so the gateway
+ * sends its failure reply at once rather than after hours of retries.
+ *
+ * Errors cross Durable Object RPC as a plain `Error` carrying only its
+ * message (the class, `name` and custom fields are gone on the caller's
+ * side), so both are recognised by what survives: the owner-copy failure's
+ * JSON envelope (`parseOwnerCopyFailure`) and matrix-js-sdk's
+ * `MatrixError: [<status>] …` message wording.
+ */
+import { parseOwnerCopyFailure } from '../owner-store/owner-copy-errors';
+import { ChannelError } from './contract';
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+/**
+ * The homeserver refused the oracle in the user's room: the bot was kicked
+ * or left (`M_FORBIDDEN`, HTTP 403), or the SDK knows the room as one the
+ * bot has not joined.
+ */
+export function isRoomForbidden(error: unknown): boolean {
+  if (
+    error instanceof Error &&
+    (error.name === 'M_FORBIDDEN' ||
+      ('errcode' in error && error.errcode === 'M_FORBIDDEN'))
+  )
+    return true;
+  const message = errorMessage(error);
+  return (
+    /\bM_FORBIDDEN\b/.test(message) ||
+    /MatrixError: \[403\]/.test(message) ||
+    /is not a joined room known to the bot/.test(message) ||
+    /\bnot (in|a member of) (the |this )?room\b/i.test(message)
+  );
+}
+
+/**
+ * The final refusal for a failure retrying cannot fix, or null when the
+ * failure stays a transient `503 unavailable`:
+ *
+ * - the Companion room refused the oracle → `409 room_unavailable`;
+ * - the user's file storage rejected the oracle's credentials while the
+ *   owner copy loaded (`VFS_AUTH_FAILED`; `NO_VFS_DELEGATION` is a
+ *   `428 delegation_required` and is handled before this) →
+ *   `403 storage_unauthorized`.
+ */
+export function classifyChannelFailure(error: unknown): ChannelError | null {
+  if (parseOwnerCopyFailure(error)?.code === 'VFS_AUTH_FAILED')
+    return new ChannelError(
+      403,
+      "The user's file storage rejected the oracle; the Companion cannot load the user's data",
+      'storage_unauthorized',
+    );
+  if (isRoomForbidden(error))
+    return new ChannelError(
+      409,
+      'The oracle cannot use the Companion room (it is not a member or was refused)',
+      'room_unavailable',
+    );
+  return null;
+}