@ixo/oracle-runtime-workers 0.2.0 → 0.4.0

package/README.md

@@ -11,6 +11,8 @@ import { createOracleWorker, WeatherPlugin } from '@ixo/oracle-runtime-workers';
 const oracle = createOracleWorker({
   config: { name: 'My Oracle', org: 'IXO', description: '…' },
   plugins: [new WeatherPlugin()],
+  // Optional, as on Node: retune a loaded plugin's manifest without forking it.
+  manifestOverrides: { weather: { visibility: 'always' } },
 });
 
 export const { UserOracleDO, MatrixGatewayDO } = oracle;
@@ -48,7 +50,10 @@ graph LR
   media, the account-room secrets key, the plugins' second device.
 - **The user owns the file.** The object holds a working copy; the durable
   file is `/.oracles/<oracleDid>/state.db.gz` in the user's IXO VFS,
-  exported on a debounced alarm and re-imported on a cold boot.
+  exported on a debounced alarm and re-imported on a cold boot. The oracle
+  reaches it with the one delegation the user deposits for it
+  (`POST /delegation`), which must carry `ixo:filesystem/.oracles` next to
+  the plugin grants — see [architecture](docs/architecture.md#self-sovereign-storage).
 - **Two scripts in production.** The gateway runs in its own Worker script
   so its memory footprint never competes with user objects; the scripts
   talk over cross-script Durable Object bindings.
@@ -62,7 +67,9 @@ graph LR
    (`MATRIX_ORACLE_ADMIN_PASSWORD`, `MATRIX_RECOVERY_PHRASE`,
    `MATRIX_VALUE_PIN`).
 3. Deploy the oracle script with its secrets (`OPEN_ROUTER_API_KEY`, the
-   same Matrix secrets, `ORACLE_SIGNING_MNEMONIC`).
+   same Matrix secrets, and `ORACLE_SIGNING_MNEMONIC` unless the account
+   room already holds the mnemonic the Node runtime or the CLI provisioned —
+   then the runtime reads it from there).
 4. `POST /matrix/start`, then `GET /matrix/status` until `running` and
    `cryptoReady` are true.
 5. Run the feature matrix against it (see [testing](docs/testing.md)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.2.0",
+  "version": "0.4.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": {
@@ -14,12 +14,6 @@
   "engines": {
     "node": ">=22"
   },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:core": "vitest run --config vitest.core.config.ts",
-    "lint": "eslint 'src/**/*.ts'"
-  },
   "main": "src/index.ts",
   "types": "src/index.ts",
   "exports": {
@@ -41,7 +35,6 @@
     "@ixo/editor": "6.0.1",
     "@ixo/matrix-bot-workers-sdk": "0.1.3",
     "@ixo/matrix-crdt": "^1.2.5",
-    "@ixo/ucan": "workspace:*",
     "@langchain/core": "1.1.48",
     "@langchain/langgraph": "1.3.2",
     "@langchain/langgraph-checkpoint": "1.0.2",
@@ -60,18 +53,25 @@
     "superjson": "1.13.3",
     "wa-sqlite": "1.0.0",
     "yjs": "^13.6.27",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@ixo/ucan": "2.2.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",
     "@cloudflare/workers-types": "^5.20260825.1",
-    "@ixo/typescript-config": "workspace:*",
     "happy-dom": "^19.0.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0",
-    "wrangler": "^4.125.0"
+    "wrangler": "^4.125.0",
+    "@ixo/typescript-config": "1.0.0"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:core": "vitest run --config vitest.core.config.ts",
+    "lint": "eslint 'src/**/*.ts'"
   }
-}
+}

package/src/do/contracts.ts

@@ -502,6 +502,16 @@ export interface MatrixGatewayObject extends Rpc.DurableObjectBranded {
    * objects fetch it once at boot and seat it into their secrets service.
    */
   getOracleSecretsKey(): Promise<JsonString | null>;
+  /**
+   * The oracle's Ed25519 UCAN signing mnemonic, read the way the Node
+   * runtime stores it: the account room's `ixo.room.state.secure` /
+   * `encrypted_mnemonic_ed_signing` state event, whose `encrypted_mnemonic`
+   * is AES-256-CBC encrypted with `MATRIX_VALUE_PIN`. Read-only (the Node
+   * runtime provisions it). Null when the env vars are unset, the event is
+   * missing or the PIN does not decrypt it — each logged, never thrown.
+   * User objects call this at boot when `ORACLE_SIGNING_MNEMONIC` is unset.
+   */
+  getOracleSigningMnemonic(): Promise<string | null>;
 }
 
 export interface BotCredentials {

package/src/do/ucan-service.ts

@@ -36,7 +36,8 @@ function toSupportedDid(did: string): SupportedDID {
   throw new Error(`Unsupported oracle DID method: ${did}`);
 }
 
-function abilityCovers(granted: string, required: string): boolean {
+/** Does a granted ability (`*`, `ns/*`, or an exact ability) cover `required`? */
+export function abilityCovers(granted: string, required: string): boolean {
   if (granted === '*' || granted === required) return true;
   if (granted.endsWith('/*')) {
     const ns = granted.slice(0, -2);
@@ -45,8 +46,35 @@ function abilityCovers(granted: string, required: string): boolean {
   return false;
 }
 
+/** One capability of a delegation, as the wire carries it. */
+export interface DelegatedCapability {
+  can: string;
+  with: string;
+  nb?: Record<string, unknown>;
+}
+
+/**
+ * The capabilities a serialized delegation grants, without validating it
+ * (the shell validated it when it was deposited; callers that mint from it
+ * are checked again by the service that receives the invocation).
+ */
+export async function listDelegationCapabilities(
+  delegationCar: string,
+): Promise<DelegatedCapability[]> {
+  const delegation = await parseDelegation(delegationCar);
+  return delegation.capabilities.map((c) => ({
+    can: c.can,
+    with: c.with,
+    ...(c.nb !== undefined && c.nb !== null
+      ? { nb: c.nb as Record<string, unknown> }
+      : {}),
+  }));
+}
+
 /** Upper bound on a delegated invocation's lifetime (mirrors the Node runtime). */
 const MAX_INVOCATION_TTL_SECONDS = 60 * 60;
+/** Parsed capability lists kept per raw delegation (the owner store asks per request). */
+const DELEGATION_CAPABILITIES_CACHE_SIZE = 8;
 
 export class WorkersUcanService {
   private readonly serviceDidCache = new Map<
@@ -57,6 +85,7 @@ export class WorkersUcanService {
     string,
     { value: { token: string; with: string }; expiresAt: number }
   >();
+  private readonly capabilitiesCache = new Map<string, DelegatedCapability[]>();
 
   constructor(private readonly opts: UcanServiceOptions) {}
 
@@ -64,6 +93,21 @@ export class WorkersUcanService {
     return Boolean(this.opts.signingMnemonic);
   }
 
+  /** `listDelegationCapabilities`, memoised on the raw token. */
+  async delegationCapabilities(
+    delegationCar: string,
+  ): Promise<DelegatedCapability[]> {
+    const cached = this.capabilitiesCache.get(delegationCar);
+    if (cached) return cached;
+    const capabilities = await listDelegationCapabilities(delegationCar);
+    if (this.capabilitiesCache.size >= DELEGATION_CAPABILITIES_CACHE_SIZE) {
+      const oldest = this.capabilitiesCache.keys().next().value;
+      if (oldest !== undefined) this.capabilitiesCache.delete(oldest);
+    }
+    this.capabilitiesCache.set(delegationCar, capabilities);
+    return capabilities;
+  }
+
   async resolveServiceDid(serviceUrl: string): Promise<string | null> {
     try {
       const origin = new URL(serviceUrl).origin;

package/src/do/user-oracle-do.ts

@@ -121,7 +121,6 @@ import {
 } from './debug-timers';
 import {
   IxoVfsOwnerStore,
-  UCAN_STORE_DEFAULT_URLS,
   VFS_DEFAULT_BASE_URLS,
 } from '../owner-store/ixo-vfs-store';
 import type { OwnerStore } from '../owner-store/types';
@@ -529,7 +528,14 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
     private async ready(identity: TurnIdentity): Promise<void> {
       this.installDebugTimerTracker();
       this.adoptHibernatedSockets();
+      let delegationReplaced = false;
       if (identity.ucanDelegation) {
+        // Clients (the Portal's SDK) send their cached delegation with every
+        // request; a token this object has not seen is a re-authorization.
+        const known =
+          this.delegations.get(identity.userDid)?.raw ??
+          (await this.ctx.storage.get<StoredDelegation>(META_DELEGATION))?.raw;
+        delegationReplaced = known !== identity.ucanDelegation;
         this.delegations.set(identity.userDid, {
           raw: identity.ucanDelegation,
         });
@@ -557,6 +563,51 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         );
       }
       await this.ctx.storage.put(META_LAST_ACCESS, Date.now());
+      if (delegationReplaced) await this.onDelegationReplaced();
+    }
+
+    /**
+     * The mnemonic the oracle signs downstream UCAN invocations with:
+     * `ORACLE_SIGNING_MNEMONIC` when set, otherwise the one the Node runtime
+     * keeps in the Matrix account room (read and decrypted by the gateway,
+     * memoised there). Undefined leaves the object without a signing key —
+     * plugins that need one degrade with their usual "no signing key" result
+     * — and never fails the boot.
+     */
+    private async resolveSigningMnemonic(): Promise<string | undefined> {
+      const fromEnv = this.env.ORACLE_SIGNING_MNEMONIC;
+      if (typeof fromEnv === 'string' && fromEnv.trim().length > 0)
+        return fromEnv;
+      try {
+        const fromRoom = await this.gateway.getOracleSigningMnemonic();
+        if (fromRoom) return fromRoom;
+      } catch (err) {
+        console.warn(
+          `[user-do] signing mnemonic unavailable from the account room: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      console.warn(
+        '[user-do] no UCAN signing key: ORACLE_SIGNING_MNEMONIC is unset and the account room holds no readable mnemonic — downstream minting is off',
+      );
+      return undefined;
+    }
+
+    /**
+     * The object holds a delegation it had not seen before (a header on this
+     * request, or a deposit through the shell). A fresh delegation is the one
+     * thing that turns a "no file-storage grant" flush failure into a
+     * success: forget the failure streak and, with unsaved turns, flush now
+     * instead of at the next 10-minute retry.
+     */
+    private async onDelegationReplaced(): Promise<void> {
+      await this.ctx.storage.delete(META_FLUSH_FAILURES);
+      if (!this.db) return;
+      if (
+        !this.dirty &&
+        (await this.ctx.storage.get<boolean>(META_DIRTY)) === true
+      )
+        this.dirty = true;
+      if (this.dirty) void this.flushToOwnerStore().catch(() => undefined);
     }
 
     /**
@@ -629,22 +680,20 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       this.userDid = userDid;
 
       const env = this.env;
-      this.ucan = new WorkersUcanService({
-        oracleDid: env.ORACLE_DID,
-        signingMnemonic:
-          typeof env.ORACLE_SIGNING_MNEMONIC === 'string'
-            ? env.ORACLE_SIGNING_MNEMONIC
-            : undefined,
-        logger: console,
-      });
-      this.ownerStore = await this.createOwnerStore(userDid);
       // The gateway lazily starts on first use; make sure it is up before the
-      // owner store or room lookups need it (idempotent, cheap once running).
+      // signing mnemonic, the owner store or room lookups need it (idempotent,
+      // cheap once running).
       await this.gateway.ensureStarted().catch((err) => {
         console.warn(
           `[user-do] matrix gateway not available yet: ${err instanceof Error ? err.message : String(err)}`,
         );
       });
+      this.ucan = new WorkersUcanService({
+        oracleDid: env.ORACLE_DID,
+        signingMnemonic: await this.resolveSigningMnemonic(),
+        logger: console,
+      });
+      this.ownerStore = await this.createOwnerStore(userDid);
 
       // Per-room JWE secrets: seat the oracle's P-256 key (fetched once from
       // the gateway, which reads the Matrix account room). Without a key the
@@ -1003,10 +1052,9 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           env.VFS_BASE_URL ??
           VFS_DEFAULT_BASE_URLS[network] ??
           VFS_DEFAULT_BASE_URLS.devnet!,
-        ucanStoreUrl:
-          env.UCAN_STORE_URL ??
-          UCAN_STORE_DEFAULT_URLS[network] ??
-          UCAN_STORE_DEFAULT_URLS.devnet!,
+        // The user's one delegation to this oracle — hydrated by `ready()`
+        // before boot, replaced at once by `setDelegation` / `clearDelegation`.
+        delegation: () => this.delegations.get(userDid)?.raw,
       });
       return new MigratingOwnerStore({
         primary: vfsStore,
@@ -1506,6 +1554,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         at: Date.now(),
         ...(typeof expiration === 'number' ? { expiration } : {}),
       } satisfies StoredDelegation);
+      await this.onDelegationReplaced();
     }
 
     /**

package/src/index.ts

@@ -35,7 +35,11 @@ export * from './plugins';
 export * from './do/contracts';
 export type { OwnerStore } from './owner-store/types';
 export { MigratingOwnerStore } from './owner-store/migrating-store';
-export { IxoVfsOwnerStore } from './owner-store/ixo-vfs-store';
+export {
+  IxoVfsOwnerStore,
+  VFS_OWNER_COPY_RESOURCE,
+  ownerCopyCapability,
+} from './owner-store/ixo-vfs-store';
 export { MatrixMediaOwnerStore } from './owner-store/matrix-media-store';
 export { MatrixGatewayDO } from './matrix/gateway-do';
 export {
@@ -131,6 +135,16 @@ export interface CreateOracleWorkerOptions {
   config: OracleConfig;
   plugins?: OraclePlugin[];
   features?: RuntimeCoreOptions['features'];
+  /**
+   * Per-plugin manifest overrides, shallow-merged over each loaded plugin's
+   * own `manifest` at boot (the Node runtime's `createOracleApp` option of
+   * the same name): retune a bundled plugin's summary, hints or
+   * `visibility` — e.g. `{ portal: { visibility: 'always' } }` binds the
+   * Portal's browser tools on every turn instead of behind
+   * `load_capability`. Keys naming no loaded plugin are logged and ignored;
+   * the merged manifest is validated like an authored one.
+   */
+  manifestOverrides?: RuntimeCoreOptions['manifestOverrides'];
   /** Extra host routes mounted on the shell. */
   routes?: PluginRoute[];
   /** Host routes exempt from UCAN auth. */
@@ -179,6 +193,7 @@ export function createOracleWorker(
         config: opts.config,
         plugins: opts.plugins ?? [],
         features: opts.features,
+        manifestOverrides: opts.manifestOverrides,
         env,
         logger: console,
       });

package/src/matrix/gateway-do.ts

@@ -44,6 +44,12 @@ import {
   type UserOracleObject,
 } from '../do/contracts';
 import { decryptWithPin } from '../secrets/pin-cipher';
+import {
+  encryptedMnemonicOf,
+  parseSigningMnemonic,
+  SIGNING_MNEMONIC_STATE_KEY,
+  SIGNING_MNEMONIC_STATE_TYPE,
+} from '../secrets/signing-mnemonic';
 import {
   IngestPipeline,
   type InboundAttachment,
@@ -202,6 +208,7 @@ export class MatrixGatewayDO
   private pluginDevice: BotCredentials | null = null;
   /** Memoised `getOracleSecretsKey` result (private JWK JSON). */
   private oracleSecretsKeyJson: string | null = null;
+  private oracleSigningMnemonic: string | null = null;
 
   // -------------------------------------------------------------------------
   // Configuration
@@ -644,6 +651,75 @@ export class MatrixGatewayDO
     return jwkJson;
   }
 
+  /**
+   * The oracle's UCAN signing mnemonic from the account room — the Node
+   * runtime's storage (`setup-claim-signing-mnemonics.ts`): state event
+   * `ixo.room.state.secure` / `encrypted_mnemonic_ed_signing`, content
+   * `{ encrypted_mnemonic: 'ivHex:cipherHex' }`, AES-256-CBC with
+   * `MATRIX_VALUE_PIN` (the same cipher as the secrets key above). Read-only:
+   * provisioning (generate, store, publish the verification method on chain)
+   * stays with the Node runtime and the CLI. Memoised for the life of this
+   * object. Every failure is logged and yields null — a user object then
+   * runs without a signing key, exactly as with no `ORACLE_SIGNING_MNEMONIC`.
+   */
+  async getOracleSigningMnemonic(): Promise<string | null> {
+    if (this.oracleSigningMnemonic !== null) return this.oracleSigningMnemonic;
+    const roomId = this.env.MATRIX_ACCOUNT_ROOM_ID;
+    const pin = this.env.MATRIX_VALUE_PIN;
+    if (!roomId || !pin) {
+      this.log(
+        'warn',
+        'signing mnemonic unavailable: ORACLE_SIGNING_MNEMONIC is unset and MATRIX_ACCOUNT_ROOM_ID / MATRIX_VALUE_PIN are not set',
+      );
+      return null;
+    }
+    await this.ensureStarted();
+    const stateJson = await this.getRoomStateEvent(
+      roomId,
+      SIGNING_MNEMONIC_STATE_TYPE,
+      SIGNING_MNEMONIC_STATE_KEY,
+    );
+    if (!stateJson) {
+      this.log(
+        'warn',
+        `no ${SIGNING_MNEMONIC_STATE_TYPE}/${SIGNING_MNEMONIC_STATE_KEY} in the account room — set ORACLE_SIGNING_MNEMONIC or provision the mnemonic with the Node runtime / CLI; downstream UCAN minting stays off`,
+      );
+      return null;
+    }
+    const encrypted = encryptedMnemonicOf(stateJson);
+    if (!encrypted) {
+      this.log(
+        'warn',
+        `${SIGNING_MNEMONIC_STATE_KEY} in the account room carries no encrypted_mnemonic — downstream UCAN minting stays off`,
+      );
+      return null;
+    }
+    let plain: string;
+    try {
+      plain = await decryptWithPin(encrypted, pin);
+    } catch (err) {
+      this.log(
+        'error',
+        `could not decrypt ${SIGNING_MNEMONIC_STATE_KEY} with MATRIX_VALUE_PIN (wrong PIN?): ${err instanceof Error ? err.message : String(err)} — downstream UCAN minting stays off`,
+      );
+      return null;
+    }
+    const mnemonic = parseSigningMnemonic(plain);
+    if (!mnemonic) {
+      this.log(
+        'error',
+        `${SIGNING_MNEMONIC_STATE_KEY} decrypted to something that is not a BIP-39 mnemonic (wrong PIN?) — downstream UCAN minting stays off`,
+      );
+      return null;
+    }
+    this.oracleSigningMnemonic = mnemonic;
+    this.log(
+      'info',
+      `oracle signing mnemonic loaded from the account room (${mnemonic.split(' ').length} words)`,
+    );
+    return mnemonic;
+  }
+
   // -------------------------------------------------------------------------
   // User snapshots (SQLite files as room media) and media downloads
   // -------------------------------------------------------------------------

package/src/owner-store/ixo-vfs-store.ts

@@ -5,14 +5,18 @@
  * The file lives at `/.oracles/<oracleDid>/state.db.gz` in the user's own
  * namespace — they can list, download, share or delete it like any file.
  * Every request carries a fresh single-use UCAN invocation minted from the
- * delegation the user deposited for this oracle in the UCAN store worker
- * (two-hop flow, same as the Node runtime's VFS plugin):
+ * ONE delegation the user deposited for this oracle (`POST /delegation`,
+ * the `ucan_delegation` room state — the same delegation Matrix turns and
+ * every plugin mint from). That delegation must carry a capability over the
+ * user's own filesystem covering the `/.oracles` folder:
  *
- *   store worker `GET /api/delegations?rootIssuer=<user>` (oracle self-signed)
- *   → delegation over `ixo:filesystem` granting `can: '*'` (the VFS grant
- *     lattice has no `fs/*` — `'*'` is the owner grant covering
- *     read/write/list/delete)
- *   → invocation attenuated to the one ability, proved by that delegation.
+ *   `{ can: '*', with: 'ixo:filesystem/.oracles', nb: { hidden: ['/.oracles'] } }`
+ *
+ * (`with: 'ixo:filesystem'`, the whole personal library, also qualifies; the
+ * VFS grant lattice has no `fs/*`, so `'*'` is the owner grant covering
+ * read/write/list/delete.) The invocation is attenuated to the one ability
+ * and proved by that delegation. There is no other source of file access:
+ * without that capability the user is "not on VFS" (`VfsNoDelegationError`).
  *
  * Endpoints are the VFS worker's `/api/fs/*` (see the Node runtime's
  * `plugins/vfs/vfs-client.ts`): `GET /files?path=` (stat via a SHORT prefix —
@@ -34,7 +38,7 @@
  *     `stat()` lists under the short literal `/.oracles` prefix and matches
  *     the exact path client-side.
  */
-import type { WorkersUcanService } from '../do/ucan-service';
+import { abilityCovers, type WorkersUcanService } from '../do/ucan-service';
 import { isNetworkError, withRetry } from './retry';
 import { tusUpload } from './tus-upload';
 import {
@@ -52,12 +56,15 @@ const VFS_RESOURCE = 'ixo:filesystem';
 const INVOCATION_TTL_SECONDS = 60;
 /** Root folder for per-oracle state files — also the short stat prefix. */
 const ORACLES_ROOT = '/.oracles';
+/** The `with` a user's delegation needs at minimum: the personal `/.oracles` folder. */
+export const VFS_OWNER_COPY_RESOURCE = `${VFS_RESOURCE}${ORACLES_ROOT}`;
 
 export const VFS_DEFAULT_BASE_URLS: Record<string, string> = {
   mainnet: 'https://vfs.ixo.earth',
   testnet: 'https://testnet.vfs.ixo.earth',
   devnet: 'https://devnet.vfs.ixo.earth',
 };
+/** UCAN store worker per network — used by the VFS plugin's file tools, not by this store. */
 export const UCAN_STORE_DEFAULT_URLS: Record<string, string> = {
   mainnet: 'https://store.ucan.ixo.earth',
   testnet: 'https://testnet.store.ucan.ixo.earth',
@@ -65,32 +72,49 @@ export const UCAN_STORE_DEFAULT_URLS: Record<string, string> = {
 };
 
 /**
- * The user has not deposited an `ixo:filesystem` delegation for this oracle
- * in the UCAN store (yet). Distinguished from transient store/VFS failures so
- * the migrating store can treat "not on VFS yet" as *no VFS copy* (and read
- * the legacy Matrix media) instead of failing the whole boot — while genuine
- * outages still fail loudly rather than silently serving a stale legacy copy.
+ * The user's delegation to this oracle (if any) grants no `ixo:filesystem`
+ * capability covering `/.oracles`. Distinguished from transient VFS failures
+ * so the migrating store can treat "not on VFS yet" as *no VFS copy* (and
+ * read the legacy Matrix media) instead of failing the whole boot — while
+ * genuine outages still fail loudly rather than silently serving a stale
+ * legacy copy.
  */
 export class VfsNoDelegationError extends Error {
-  constructor(userDid: string) {
+  constructor(userDid: string, reason: VfsNoDelegationReason) {
     super(
-      `No active ixo:filesystem delegation from ${userDid} in the UCAN store`,
+      reason === 'no-delegation'
+        ? `${userDid} has not deposited a delegation for this oracle (POST /delegation)`
+        : `${userDid}'s delegation to this oracle carries no ixo:filesystem capability covering ${ORACLES_ROOT}`,
     );
     this.name = 'VfsNoDelegationError';
   }
 }
+export type VfsNoDelegationReason = 'no-delegation' | 'no-capability';
 
 /**
- * The UCAN store (which holds the user's delegation) was unreachable or
- * failing — transient, unlike a missing delegation. Retried like a 5xx.
+ * The capability of a user's delegation that lets this store reach the
+ * `/.oracles` folder with `ability`, or null. A qualifying `with` is the
+ * whole personal filesystem or exactly its `/.oracles` subtree — a narrower
+ * scope (say `/.oracles/<oracleDid>`) cannot list `/.oracles`, which the
+ * store must do because a full path with the DID embedded is too long for
+ * the VFS's filter (see `listOracleFiles()`). Domain namespaces
+ * (`ixo:filesystem/did:…`) never qualify.
  */
-export class VfsStoreUnavailableError extends Error {
-  readonly retryable = true as const;
-
-  constructor(detail: string) {
-    super(`UCAN store unavailable while resolving VFS access: ${detail}`);
-    this.name = 'VfsStoreUnavailableError';
-  }
+export function ownerCopyCapability<C extends { can: string; with: string }>(
+  capabilities: readonly C[],
+  ability: string,
+): C | null {
+  const qualifyingScope = (resource: string): boolean => {
+    if (resource === VFS_RESOURCE) return true;
+    if (!resource.startsWith(`${VFS_RESOURCE}/`)) return false;
+    const scope = resource.slice(VFS_RESOURCE.length).replace(/\/+$/, '');
+    return scope === '' || scope === ORACLES_ROOT;
+  };
+  return (
+    capabilities.find(
+      (c) => qualifyingScope(c.with) && abilityCovers(c.can, ability),
+    ) ?? null
+  );
 }
 
 /** A non-2xx VFS response, with the status and body for callers that recover. */
@@ -134,7 +158,6 @@ function describe(error: unknown): string {
 export function isRetryableRequest(error: unknown): boolean {
   if (error instanceof VfsRequestError)
     return error.status >= 500 || error.status === 429;
-  if (error instanceof VfsStoreUnavailableError) return true;
   return isNetworkError(error);
 }
 
@@ -144,7 +167,12 @@ export interface IxoVfsOwnerStoreOptions {
   oracleDid: string;
   /** VFS worker origin, e.g. `https://devnet.vfs.ixo.earth`. */
   vfsBaseUrl: string;
-  ucanStoreUrl: string;
+  /**
+   * The user's current delegation to this oracle (serialized CAR), or
+   * undefined when none is deposited. Read on every request so a delegation
+   * deposited or revoked mid-life takes effect at once.
+   */
+  delegation: () => string | undefined;
   fetchImpl?: typeof fetch;
   timeoutMs?: number;
   /** Backoff between retries of a failed request (tests: zeros). */
@@ -468,30 +496,23 @@ export class IxoVfsOwnerStore implements OwnerStore {
   private async bearer(
     ability: 'fs/list' | 'fs/read' | 'fs/write' | 'fs/delete',
   ): Promise<string> {
-    const delegation = await this.opts.ucan.getServiceDelegation(
-      this.opts.userDid,
-      {
-        storeUrl: this.opts.ucanStoreUrl,
-        resource: VFS_RESOURCE,
-        requiredAbility: ability,
-      },
+    const raw = this.opts.delegation();
+    if (!raw)
+      throw new VfsNoDelegationError(this.opts.userDid, 'no-delegation');
+    const capability = ownerCopyCapability(
+      await this.opts.ucan.delegationCapabilities(raw),
+      ability,
     );
-    if ('error' in delegation) {
-      if (delegation.error === 'no-delegation')
-        throw new VfsNoDelegationError(this.opts.userDid);
-      // 'store-error': the UCAN store itself failed (5xx, network) — transient.
-      throw new VfsStoreUnavailableError(
-        `${delegation.error}${delegation.detail ? ` (${delegation.detail})` : ''}`,
-      );
-    }
+    if (!capability)
+      throw new VfsNoDelegationError(this.opts.userDid, 'no-capability');
     const minted = await this.opts.ucan.createInvocationFromDelegation(
-      delegation.token,
+      raw,
       this.opts.vfsBaseUrl,
       // `nb.hidden: ['*']` imposes NO widening — the VFS intersects reveal
       // sets across the chain, so the effective reveal is exactly what the
       // user's delegation granted. Omitting it would zero the reveal and make
       // the dot-folder state file invisible to its own writer.
-      { can: ability, with: delegation.with, nb: { hidden: ['*'] } },
+      { can: ability, with: capability.with, nb: { hidden: ['*'] } },
       { maxTtlSeconds: INVOCATION_TTL_SECONDS },
     );
     if ('error' in minted)

package/src/owner-store/owner-copy-errors.ts

@@ -3,22 +3,19 @@
  * the object retries only what can succeed on its own and the shell can
  * answer with an honest status code:
  *
- *   - `NO_VFS_DELEGATION` (403, not retryable): the user has not deposited an
- *     `ixo:filesystem` delegation for this oracle. Retrying cannot help; the
- *     client must deposit the grant and try again.
+ *   - `NO_VFS_DELEGATION` (403, not retryable): the user's delegation to this
+ *     oracle (or the lack of one) grants no `ixo:filesystem` capability over
+ *     `/.oracles`. Retrying cannot help; the client must authorize the oracle
+ *     again with file storage included and try again.
  *   - `VFS_AUTH_FAILED` (403, not retryable): the VFS rejected the oracle's
  *     credentials (401/403). Something is misconfigured; retrying cannot help.
- *   - `OWNER_COPY_UNAVAILABLE` (503, retryable): the UCAN store or the VFS was
- *     unreachable or failing (network, 5xx, 429, timeout). The object already
- *     retried with backoff; the next request tries again from scratch.
+ *   - `OWNER_COPY_UNAVAILABLE` (503, retryable): the VFS was unreachable or
+ *     failing (network, 5xx, 429, timeout). The object already retried with
+ *     backoff; the next request tries again from scratch.
  *
  * In every case nothing was written — the boot is not memoised on failure.
  */
-import {
-  VfsNoDelegationError,
-  VfsRequestError,
-  VfsStoreUnavailableError,
-} from './ixo-vfs-store';
+import { VfsNoDelegationError, VfsRequestError } from './ixo-vfs-store';
 
 export type OwnerCopyErrorCode =
   | 'NO_VFS_DELEGATION'
@@ -73,7 +70,7 @@ function messageFor(
 ): string {
   switch (code) {
     case 'NO_VFS_DELEGATION':
-      return `Your oracle data cannot be loaded because this oracle has no file-storage permission from you yet. Deposit an ixo:filesystem delegation for it, then try again. Nothing was changed. (${detail})`;
+      return `Your oracle data cannot be loaded because your authorization for this oracle does not include file storage (ixo:filesystem over /.oracles). Authorize the oracle again to grant it, then try again. Nothing was changed. (${detail})`;
     case 'VFS_AUTH_FAILED':
       return `Your oracle data cannot be loaded because your file storage rejected the oracle's credentials. Nothing was changed. (${detail})`;
     default:
@@ -81,9 +78,6 @@ function messageFor(
   }
 }
 
-// Re-exported so the shell can map the transient store failure too.
-export { VfsStoreUnavailableError };
-
 /** What the shell needs to answer a request whose owner copy could not load. */
 export interface OwnerCopyFailure {
   code: OwnerCopyErrorCode;
@@ -163,13 +157,5 @@ export function parseOwnerCopyFailure(error: unknown): OwnerCopyFailure | null {
       message: error.message,
     };
   }
-  if (error.name === 'VfsStoreUnavailableError') {
-    return {
-      code: 'OWNER_COPY_UNAVAILABLE',
-      httpStatus: 503,
-      retryable: true,
-      message: error.message,
-    };
-  }
   return null;
 }

package/src/realtime/realtime-endpoint.ts

@@ -97,6 +97,14 @@ const SERVER_EVENTS = [
   'message_cache_invalidation',
 ] as const;
 
+/** Socket event every runtime event travels under, carrying `{ eventName, payload }` (Node's wire). */
+const ENVELOPE_EVENT = 'event';
+/** Frontend calls the client SDK listens for by name with the raw payload. */
+const RAW_NAMED_EVENTS: ReadonlySet<string> = new Set([
+  'browser_tool_call',
+  'action_call',
+]);
+
 /** Close codes in the 4000–4999 application range. */
 const CLOSE_UNAUTHORIZED = 4401;
 const CLOSE_HANDSHAKE_TIMEOUT = 4408;
@@ -547,11 +555,25 @@ export class RealtimeEndpoint {
 
   // ── outbound ────────────────────────────────────────────────────────────
 
+  /**
+   * Mirror a runtime event to the sockets of the session it belongs to, on
+   * the Node runtime's wire: the socket event is `event` and its argument is
+   * the `@ixo/oracles-events` envelope `{ eventName, payload }`. The client
+   * SDK's catch-all listener validates exactly that (`payload.sessionId` and
+   * `payload.requestId`) and drops a bare payload, while its named
+   * `tool_call` / `render_component` listeners crash on one. The two calls
+   * the SDK answers (`browser_tool_call`, `action_call`) are the exception:
+   * it listens for them by name with the raw payload, on both runtimes.
+   */
   private fanOut(eventName: string, payload: RawEventPayload): void {
     const sessionId =
       typeof payload.sessionId === 'string' ? payload.sessionId : undefined;
     if (!sessionId) return;
-    this.hub.emitToSession(sessionId, eventName, payload);
+    if (RAW_NAMED_EVENTS.has(eventName)) {
+      this.hub.emitToSession(sessionId, eventName, payload);
+      return;
+    }
+    this.hub.emitToSession(sessionId, ENVELOPE_EVENT, { eventName, payload });
   }
 
   private call(

package/src/secrets/signing-mnemonic.ts

@@ -0,0 +1,42 @@
+/**
+ * Where the Node runtime keeps the oracle's UCAN signing mnemonic, and how
+ * to read it (`oracles-chain-client`'s `setup-claim-signing-mnemonics.ts`):
+ * the account room's state event `ixo.room.state.secure` /
+ * `encrypted_mnemonic_ed_signing` with content
+ * `{ encrypted_mnemonic: 'ivHex:cipherHex' }`, AES-256-CBC under
+ * `MATRIX_VALUE_PIN` (`decryptWithPin`). The Workers runtime only reads it —
+ * provisioning stays with the Node runtime and the CLI.
+ */
+
+export const SIGNING_MNEMONIC_STATE_TYPE = 'ixo.room.state.secure';
+export const SIGNING_MNEMONIC_STATE_KEY = 'encrypted_mnemonic_ed_signing';
+
+/** The `encrypted_mnemonic` of a state-event content JSON, or null. */
+export function encryptedMnemonicOf(contentJson: string): string | null {
+  let content: unknown;
+  try {
+    content = JSON.parse(contentJson);
+  } catch {
+    return null;
+  }
+  if (typeof content !== 'object' || content === null) return null;
+  const value = (content as { encrypted_mnemonic?: unknown })
+    .encrypted_mnemonic;
+  return typeof value === 'string' && /^[0-9a-f]+:[0-9a-f]+$/i.test(value)
+    ? value
+    : null;
+}
+
+const WORD_COUNTS = new Set([12, 15, 18, 21, 24]);
+
+/**
+ * A decrypted value that looks like a BIP-39 mnemonic (12–24 lowercase
+ * words), normalised to single spaces — or null. A wrong PIN decrypts to
+ * bytes that never pass this, which keeps garbage out of the signer.
+ */
+export function parseSigningMnemonic(plain: string): string | null {
+  const words = plain.trim().split(/\s+/);
+  if (!WORD_COUNTS.has(words.length)) return null;
+  if (!words.every((w) => /^[a-z]+$/.test(w))) return null;
+  return words.join(' ');
+}

package/src/shell/app.ts

@@ -16,6 +16,10 @@ import {
   decodeRoomStateContent,
   encodeRoomStateContent,
 } from '../matrix/room-state-codec';
+import {
+  listDelegationCapabilities,
+  type DelegatedCapability,
+} from '../do/ucan-service';
 import {
   authenticate,
   isExcluded,
@@ -358,9 +362,23 @@ export function createShell(
     const authorized =
       Boolean(state?.raw) &&
       (exp === undefined || exp > Math.floor(Date.now() / 1000));
+    // The stored delegation's capabilities, so a client can tell an older
+    // delegation (minted before a capability existed — e.g. the file-storage
+    // grant the owner copy needs) from a current one and re-authorize.
+    let capabilities: DelegatedCapability[] | undefined;
+    if (authorized && state?.raw) {
+      try {
+        capabilities = await listDelegationCapabilities(state.raw);
+      } catch (err) {
+        console.warn(
+          `[shell] stored delegation for ${auth.userDid} could not be parsed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
     return c.json({
       authorized,
       ...(exp !== undefined && { expiration: exp }),
+      ...(capabilities !== undefined && { capabilities }),
     });
   });
   app.delete('/delegation', async (c) => {