@ixo/oracle-runtime-workers 0.3.0 → 0.4.0

package/README.md

@@ -67,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.3.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": {

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/user-oracle-do.ts

@@ -566,6 +566,32 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       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
@@ -654,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

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/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(' ');
+}