@ixo/oracle-runtime-workers 0.17.1 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.17.1",
+  "version": "0.19.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": {
@@ -59,8 +59,8 @@
     "yjs": "13.6.32",
     "zod": "^4.4.3",
     "@ixo/ixo-transaction": "0.1.0",
-    "@ixo/common": "1.6.0",
-    "@ixo/ucan": "2.2.1"
+    "@ixo/ucan": "2.2.1",
+    "@ixo/common": "1.7.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

package/src/channels/auth.ts

@@ -41,7 +41,8 @@ export const ChannelInvoke = defineCapability({
 
 export interface ChannelAuthConfig {
   oracleDid: string;
-  channelDid: string;
+  /** Every channel service DID allowed to invoke this deployment. */
+  channelDids: readonly string[];
   didResolver: DIDKeyResolver;
 }
 
@@ -85,12 +86,16 @@ export async function authenticateChannel(
   );
   const chain = result.proofChain;
   const userDid = chain?.[0];
+  // The invoker is the one listed channel service that signed this
+  // invocation; the user's grant must be addressed to that same service.
+  const channelDid = result.invoker;
   if (
     !result.ok ||
     !userDid?.startsWith('did:ixo:') ||
     chain?.length !== 2 ||
-    chain[1] !== config.channelDid ||
-    result.invoker !== config.channelDid
+    !channelDid ||
+    !config.channelDids.includes(channelDid) ||
+    chain[1] !== channelDid
   )
     throw new ChannelError(
       401,
@@ -106,7 +111,7 @@ export async function authenticateChannel(
     !('issuer' in proof) ||
     proof.proofs.length !== 0 ||
     proof.issuer.did() !== userDid ||
-    proof.audience.did() !== config.channelDid ||
+    proof.audience.did() !== channelDid ||
     proof.capabilities.length !== 1 ||
     proof.capabilities[0]?.can !== 'ixo:channel/invoke' ||
     proof.capabilities[0]?.with !== `ixo:channel:${input.bindingId}` ||
@@ -159,7 +164,7 @@ export async function authenticateChannel(
   return {
     userDid,
     channel: {
-      callerDid: config.channelDid,
+      callerDid: channelDid,
       provider: input.provider,
       bindingId: input.bindingId,
       bindingRevision: input.bindingRevision,
@@ -176,13 +181,30 @@ const channelWebResolver = createWebDIDResolver({
   cacheTtlMs: IXO_DID_RESOLUTION_CACHE_TTL_MS,
 });
 
+/**
+ * `CHANNEL_SERVICE_DID` is one DID or a comma-separated list (one channel
+ * service per messaging provider, or a rotation overlap): entries are
+ * trimmed, empty ones dropped and duplicates removed, order kept.
+ */
+export function parseChannelServiceDids(raw: string | undefined): string[] {
+  return [
+    ...new Set(
+      (raw ?? '')
+        .split(',')
+        .map((did) => did.trim())
+        .filter((did) => did !== ''),
+    ),
+  ];
+}
+
 export function channelAuthConfig(
   env: Pick<
     OracleWorkerEnv,
     'CHANNEL_SERVICE_DID' | 'BLOCKSYNC_GRAPHQL_URL' | 'ORACLE_DID'
   >,
 ): ChannelAuthConfig {
-  if (!env.CHANNEL_SERVICE_DID)
+  const channelDids = parseChannelServiceDids(env.CHANNEL_SERVICE_DID);
+  if (channelDids.length === 0)
     throw new ChannelError(
       503,
       'Channels are not configured',
@@ -194,10 +216,10 @@ export function channelAuthConfig(
   ]);
   return {
     oracleDid: env.ORACLE_DID,
-    channelDid: env.CHANNEL_SERVICE_DID,
+    channelDids,
     didResolver: async (did) => {
       if (
-        did === env.CHANNEL_SERVICE_DID ||
+        channelDids.includes(did) ||
         did === env.ORACLE_DID ||
         did.startsWith('did:ixo:')
       )
@@ -289,6 +311,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

@@ -1,22 +1,34 @@
 import { z } from 'zod';
 import type { ReplyPlan } from '../delivery/types';
 
+/**
+ * A channel provider id (`whatsapp`, later others): lower-case, starts with a
+ * letter, at most 32 characters. The runtime does not enumerate providers;
+ * the gateway and the Auth Hub do. An unknown provider is delivered with the
+ * default delivery profile.
+ */
+export const ChannelProviderId = z.string().regex(/^[a-z][a-z0-9_-]{0,31}$/);
+
 export const ChannelTurnBody = z.strictObject({
-  provider: z.literal('whatsapp'),
+  provider: ChannelProviderId,
   bindingId: z.string().regex(/^chb_[A-Za-z0-9_-]{1,120}$/),
   bindingRevision: z.number().int().positive().safe(),
   requestId: z.string().min(1).max(180),
   remoteMessageRef: z.string().regex(/^hmac:[a-f0-9]{64}$/),
   sessionId: z.string().min(1).max(255).optional(),
   message: z.string().min(1).max(16_000),
-  context: z.strictObject({ kind: z.literal('companion') }),
+  /**
+   * Which kind of oracle the gateway believes it addresses. `companion` is
+   * the legacy value; the gateway sends `oracle`. Both are accepted.
+   */
+  context: z.strictObject({ kind: z.enum(['companion', 'oracle']) }),
 });
 
 export type ChannelTurnInput = z.infer<typeof ChannelTurnBody>;
 
 export const ChannelOrigin = z.strictObject({
   v: z.literal(1),
-  transport: z.literal('whatsapp'),
+  transport: ChannelProviderId,
   binding_id: ChannelTurnBody.shape.bindingId,
   remote_ref: ChannelTurnBody.shape.remoteMessageRef,
 });
@@ -39,7 +51,7 @@ export function channelOrigin(
 
 export interface ChannelIdentity {
   callerDid: string;
-  provider: 'whatsapp';
+  provider: string;
   bindingId: string;
   bindingRevision: number;
 }
@@ -82,7 +94,7 @@ export type ChannelErrorStatus =
  * The machine-readable reason a channel turn was refused. The gateway maps
  * a refusal by `code` first and by HTTP status second. 428 (Precondition
  * Required) means a precondition on the user's side is missing: fix it
- * (authorize the oracle again, finish setting up the Companion room) and
+ * (authorize the oracle again, finish setting up the user's oracle room) and
  * retry; it is never a transient outage.
  *
  * | code                              | status | meaning                                               |
@@ -94,13 +106,16 @@ export type ChannelErrorStatus =
  * | `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         |
- * | `session_not_found`               | 404    | the session is not the user's Companion session       |
+ * | `storage_unauthorized`            | 403    | the user's file storage rejected the oracle (final)   |
+ * | `session_not_found`               | 404    | the session is not the user's oracle session          |
  * | `request_conflict`                | 409    | the request id already belongs to another message     |
- * | `session_conflict`                | 409    | the channel is already bound to another session       |
- * | `room_not_encrypted`              | 409    | the Companion room is not end-to-end encrypted        |
+ * | `session_conflict`                | 409    | another session is bound, or the named one is gone:   |
+ * |                                   |        | resend the same request without `sessionId`           |
+ * | `room_not_encrypted`              | 409    | the user's oracle room is not end-to-end encrypted    |
+ * | `room_unavailable`                | 409    | the oracle cannot use the user's oracle 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                    |
+ * | `room_not_ready`                  | 428    | the user has no oracle room yet                       |
  * | `delegation_required`             | 428    | no usable delegation to this oracle (see below)       |
  * | `rate_limited`                    | 429    | too many requests for this user                       |
  * | `not_configured`                  | 503    | channels or binding validation are not configured     |
@@ -115,10 +130,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 +165,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 = 'Oracle 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
@@ -165,7 +208,7 @@ export interface ChannelDelegation {
 export function delegationRequiredError(): ChannelError {
   return new ChannelError(
     428,
-    'Companion delegation required: the user must authorize this oracle again',
+    'Delegation required: the user must authorize this oracle again',
     'delegation_required',
   );
 }

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 user's oracle 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 oracle cannot load the user's data",
+      'storage_unauthorized',
+    );
+  if (isRoomForbidden(error))
+    return new ChannelError(
+      409,
+      "The oracle cannot use the user's oracle room (it is not a member or was refused)",
+      'room_unavailable',
+    );
+  return null;
+}