@ixo/oracle-runtime-workers 0.41.3 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.41.3",
+  "version": "0.42.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": {
@@ -67,9 +67,9 @@
     "protobufjs": "^7.6.5",
     "@ixo/topic-protocol": "1.0.0-rc.8",
     "survey-core": "2.3.11",
+    "@ixo/common": "1.8.0",
     "@ixo/ixo-transaction": "0.2.0",
     "@ixo/ucan": "2.3.0",
-    "@ixo/common": "1.8.0",
     "@ixo/action-interactions": "0.1.1"
   },
   "devDependencies": {

package/src/attachments/download.ts

@@ -168,7 +168,7 @@ export class HomeserverUnauthorizedError extends Error {
 }
 
 /** `mxc://<server>/<media id>`, the parts checked before they go into a URL. */
-const MXC_PATTERN = /^mxc:\/\/([A-Za-z0-9.:[\]-]+)\/([A-Za-z0-9_-]+)$/;
+export const MXC_PATTERN = /^mxc:\/\/([A-Za-z0-9.:[\]-]+)\/([A-Za-z0-9_-]+)$/;
 
 /**
  * Open the media behind `mxc` on the homeserver as the account behind

package/src/core/runtime-context.ts

@@ -95,7 +95,7 @@ export interface MatrixAdapter {
   getRoomState(roomId: string): Promise<RoomStateSnapshot>;
   getEventById(roomId: string, eventId: string): Promise<MatrixEvent>;
   /** See `MatrixGatewayObject.botCredentials`. */
-  botCredentials(): Promise<BotCredentials>;
+  botCredentials(opts?: { rejected?: string }): Promise<BotCredentials>;
   /** Group rooms: room kind and channel memory (see `plugin-api/types.ts`). Hosts without a gateway omit them. */
   roomInfo?: RuntimeContext['matrix']['roomInfo'];
   channelMemory?: RuntimeContext['matrix']['channelMemory'];
@@ -497,7 +497,7 @@ export function buildRuntimeContext<TConfig = MergedConfig>(
     matrix: {
       postToRoom: (roomId, content, opts) =>
         ambient.matrix.postToRoom(roomId, content, opts),
-      botCredentials: () => ambient.matrix.botCredentials(),
+      botCredentials: (opts) => ambient.matrix.botCredentials(opts),
       postEvent: (roomId, eventType, content, opts) =>
         ambient.matrix.postEvent(roomId, eventType, content, opts),
       getRoomState: (roomId) => ambient.matrix.getRoomState(roomId),

package/src/do/ambient.ts

@@ -183,7 +183,8 @@ export function createMatrixAdapter(
       ),
     postEvent: (roomId, eventType, content, opts) =>
       gateway.sendEvent(roomId, eventType, JSON.stringify(content), opts ?? {}),
-    botCredentials: () => gateway.botCredentials(),
+    botCredentials: (opts?: { rejected?: string }) =>
+      gateway.botCredentials(opts?.rejected ? { rejected: opts.rejected } : {}),
     roomInfo: (roomId) => gateway.groupChatRoomInfo(roomId),
     channelMemory: {
       recall: async (roomId, limit) =>

package/src/plugin-api/types.ts

@@ -818,8 +818,11 @@ export interface RuntimeContext<TConfig = MergedConfig> {
     /**
      * Credentials of the oracle's own crypto-less device for plugins that run
      * their own Matrix client (editor, flows). Minted and kept by the gateway.
+     * A caller whose request the homeserver answered 401 passes the token it
+     * used as `rejected`: the host then re-validates the device (or logs it
+     * in again) and answers with fresh credentials, so one retry can succeed.
      */
-    botCredentials: () => Promise<{
+    botCredentials: (opts?: { rejected?: string }) => Promise<{
       baseUrl: string;
       userId: string;
       accessToken: string;

package/src/plugins/domain-indexer/domain-indexer.plugin.ts

@@ -14,7 +14,7 @@ import { createDomainIndexerTools } from './domain-indexer-tools';
  * the core `NETWORK` env var. Operators can override with the optional
  * `DOMAIN_INDEXER_URL` env var (useful for local/staging deployments).
  */
-const DOMAIN_INDEXER_URLS = {
+export const DOMAIN_INDEXER_URLS = {
   mainnet: 'https://domain-indexer.ixo.earth',
   testnet: 'https://domain-indexer.testnet.ixo.earth',
   devnet: 'https://domain-indexer.devnet.ixo.earth',

package/src/plugins/ixo-chain/http.ts

@@ -151,6 +151,8 @@ export interface ChainCall {
   deadline: number;
   signal: AbortSignal;
   fetch: typeof fetch;
+  /** How the call waits before a retry; {@link sleep} unless a test injects its own clock. */
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
 }
 
 /**
@@ -192,7 +194,7 @@ export type Outcome<T> =
   | { ok: false; failure: Failure };
 
 /** The turn's abort reason as an error (a non-error reason becomes an `AbortError`). */
-function abortReason(signal: AbortSignal): Error {
+export function abortReason(signal: AbortSignal): Error {
   return signal.reason instanceof Error
     ? signal.reason
     : new DOMException('Aborted', 'AbortError');
@@ -288,7 +290,7 @@ export class ReadsInFlight<T> {
 }
 
 /** Resolves after `ms`; rejects with the turn's abort reason if it ends first. */
-function sleep(ms: number, signal: AbortSignal): Promise<void> {
+export function sleep(ms: number, signal: AbortSignal): Promise<void> {
   return new Promise((resolve, reject) => {
     if (signal.aborted) {
       reject(abortReason(signal));
@@ -394,7 +396,7 @@ export async function withRetry<T>(
       : { ok: false, failure: first.failure };
   if (!first.retry || Date.now() + wait + MIN_ATTEMPT_MS > call.deadline)
     return giveUp();
-  await sleep(wait, call.signal);
+  await (call.sleep ?? sleep)(wait, call.signal);
   const second = await attempt();
   recordHealth(read.upstream, second);
   if (second.ok) {
@@ -518,7 +520,9 @@ const outOfBudget = (note: string): Attempt<never> => ({
  * The body of an error answer as text, or undefined when it is longer than
  * {@link ERROR_BODY_MAX_BYTES} (the rest is not read).
  */
-async function errorBodyOf(response: Response): Promise<string | undefined> {
+export async function errorBodyOf(
+  response: Response,
+): Promise<string | undefined> {
   const reader = response.body?.getReader();
   if (!reader) return '';
   const decoder = new TextDecoder();

package/src/plugins/ixo-chain/ixo-chain.plugin.ts

@@ -79,12 +79,25 @@ function networkOf(config: MergedConfig): Network {
 
 /** The REST base URL: `CHAIN_REST_URL` when set, else the network's default. */
 export function chainRestUrl(config: MergedConfig): string {
+  return chainRestUrlFor(networkOf(config), config);
+}
+
+/**
+ * The REST base URL for `network`: `CHAIN_REST_URL` when set (the
+ * operator's node for the oracle's network), else that network's default.
+ * For a caller that already knows its network rather than reading
+ * `NETWORK` itself.
+ */
+export function chainRestUrlFor(
+  network: Network,
+  config: MergedConfig,
+): string {
   const override = configSchema.shape.CHAIN_REST_URL.safeParse(
     config.CHAIN_REST_URL,
   );
   return override.success && override.data
     ? override.data
-    : CHAIN_REST_URLS[networkOf(config)];
+    : CHAIN_REST_URLS[network];
 }
 
 /** The names worker's origin: `IXO_NAMES_URL` when set, else the network's default. */

package/src/plugins/ixo-chain/queries.ts

@@ -221,6 +221,32 @@ export function isBech32(address: string, prefix: string): boolean {
   return padding < 5 && (last & ((1 << padding) - 1)) === 0;
 }
 
+/**
+ * The bytes a valid bech32 `address` with the prefix `prefix` carries (for
+ * an account, the 20-byte hash of its public key); null when
+ * {@link isBech32} refuses it.
+ */
+export function bech32Bytes(
+  address: string,
+  prefix: string,
+): Uint8Array | null {
+  if (!isBech32(address, prefix)) return null;
+  const data = address.slice(prefix.length + 1, -BECH32_CHECKSUM);
+  const bytes: number[] = [];
+  let buffer = 0;
+  let bits = 0;
+  for (const char of data) {
+    buffer = (buffer << 5) | BECH32_CHARSET.indexOf(char);
+    bits += 5;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push((buffer >>> bits) & 0xff);
+    }
+  }
+  // The leftover bits are the zero padding isBech32 checked.
+  return Uint8Array.from(bytes);
+}
+
 /**
  * The account an account field names: the user's own address when the
  * field is omitted, else an `ixo1…` address or the address a

package/src/plugins/pod-creator/chain-gateway.ts

@@ -9,24 +9,87 @@ import type { ServicePodBlueprint } from './blueprint-types';
  */
 export interface PreparedPodBatch {
   /**
-   * The messages, in execution order: `MsgCreateEntity` first, then the
-   * claim collection(s), entity accounts and grants (`POD_BATCH_TYPE_URLS`).
-   * Each is `{ typeUrl, value }` in proto-JSON (camelCase fields, integer
-   * amounts as strings, bytes as base64) with exactly its catalog fields.
+   * The messages, in execution order: `MsgCreateEntity` first, then only
+   * `POD_BATCH_TYPE_URLS` (the bundled gateway sends `MsgCreateEntity`
+   * alone). Each is `{ typeUrl, value }` in proto-JSON (camelCase fields,
+   * integer amounts as strings, bytes as base64, timestamps as RFC 3339
+   * strings) with exactly its catalog fields.
    */
   messages: ITrxMsg[];
   /** Human-readable summary of what the batch creates (at most 1000 characters). */
   summary: string;
   /** Estimated cost, when the gateway can compute it. */
   estimatedCost?: string;
+  /**
+   * Public documents the messages name (by URL and SHA-256 proof) that are
+   * not published yet: `publishDocuments` publishes them once the user
+   * approved, before the wallet is asked to sign. Empty when every document
+   * the messages name is already public.
+   */
+  documents: PendingDocument[];
+}
+
+/**
+ * A public document a batch names (the POD's profile, its domain card),
+ * reserved on the oracle's homeserver when the batch is prepared and
+ * uploaded only after the user approved it.
+ */
+export interface PendingDocument {
+  /** The reserved media it is uploaded as: `mxc://<server>/<media id>`. */
+  mxc: string;
+  /** Its media type, e.g. `application/ld+json`. */
+  contentType: string;
+  /** The file name the homeserver records. */
+  filename: string;
+  /** The exact text: the message carries the SHA-256 of these bytes as its proof. */
+  text: string;
+}
+
+/**
+ * An expected refusal (a missing identity, a homeserver that is down), which
+ * the tools report to the model as a result instead of throwing.
+ */
+export interface GatewayRefusal {
+  ok: false;
+  message: string;
+  /** Whether the same call can succeed later unchanged (something was down). */
+  retryable: boolean;
+}
+
+/** A gateway answer: the value, or why there is none. */
+export type GatewayResult<T extends object> =
+  | ({ ok: true } & T)
+  | GatewayRefusal;
+
+/**
+ * What a broadcast transaction says about the POD. `pending`: not on chain
+ * (or not indexed) within the lookup's time, ask again later with the same
+ * hash; `failed`: it failed, or it is not the POD this conversation sent, so
+ * asking again cannot help; `unavailable`: the chain could not be read.
+ */
+export type PodConfirmation =
+  | { status: 'created'; podDid: string; summary: string }
+  | {
+      status: 'pending' | 'failed' | 'unavailable';
+      message: string;
+      retryable: boolean;
+    };
+
+/** What the user's wallet was asked to sign, as the create session records it. */
+export interface SentPodBatch {
+  /** The messages exactly as sent (proto-JSON, catalog-validated). */
+  messages: ITrxMsg[];
+  /** The profile the POD was prepared with (for its domain card). */
+  profile: PodProfile;
 }
 
 /**
  * The message types a POD creation batch may carry. The chain runs the
  * messages of one transaction in order, all or nothing, so a later message
  * can name what an earlier one creates — the entity DID, its admin account,
- * the collection id — as long as the gateway predicts those values right
- * (otherwise the whole transaction fails and nothing is created).
+ * the collection id — only by predicting those values (otherwise the whole
+ * transaction fails and nothing is created). The bundled gateway does not
+ * predict: it sends `MsgCreateEntity` alone.
  */
 export const POD_BATCH_TYPE_URLS = [
   '/ixo.entity.v1beta1.MsgCreateEntity',
@@ -62,49 +125,78 @@ export function podBatchProblem(
   return null;
 }
 
-/** The created POD, resolved from the broadcast transaction. */
-export interface CreatedPod {
-  podDid: string;
-  summary: string;
+/** What the user agreed to call the POD, for its on-chain profile. */
+export interface PodProfile {
+  /** The POD's name: plain text, 1 to 100 characters. */
+  name: string;
+  /** What the POD does, in plain text (at most 600 characters). */
+  description?: string;
 }
 
 /**
- * The chain-facing seam for the create path. The planned concrete implementation
- * calls the IXO MCP server (hosted on Cloudflare) to compose the POD-creation
- * batch (`MsgCreateEntity` + the claim collection + authz grants) and to read a
- * broadcast transaction back. The oracle never signs creation — the user's
- * wallet does — so the gateway only ever returns proto-JSON messages, which
- * the plugin validates against the `@ixo/ixo-transaction` catalog before
- * storing them, and resolves results.
+ * The chain-facing seam for the create path. The oracle never signs
+ * creation — the user's wallet does — so a gateway only ever returns
+ * proto-JSON messages, which the plugin validates against the
+ * `@ixo/ixo-transaction` catalog before storing them, and resolves the
+ * broadcast transaction afterwards.
  *
- * Both methods receive the request `RuntimeContext` because reaching the IXO MCP
- * server follows the runtime's remote-MCP pattern (see the sandbox plugin):
- * resolve the server DID via did:web and mint a per-user `ixo:*` UCAN invocation
- * through `ctx.ucan` for the `Authorization` header, with the MCP URL read from
- * `ctx.config`. The seam is injected so the create path stays unit-testable
- * without a live server or chain.
+ * The bundled implementation is `createIxoChainGateway()`
+ * (`ixo-chain-gateway.ts`): one `MsgCreateEntity` owned by the user, its
+ * profile reserved on the oracle's homeserver and published after approval,
+ * read back from chain REST; then the POD's domain card. Every method
+ * receives the request `RuntimeContext` (the user, the config, the turn's
+ * abort signal, the oracle's Matrix device) and answers an expected refusal
+ * as a result; a throw is a programming error. The seam is injected so the
+ * create path stays unit-testable without a live homeserver or chain, and
+ * so a fork can compose a different batch.
  */
 export interface ChainGateway {
   preparePodBatch(
-    input: { blueprint: ServicePodBlueprint; network: Network },
+    input: {
+      blueprint: ServicePodBlueprint;
+      network: Network;
+      profile: PodProfile;
+    },
     ctx: RuntimeContext,
-  ): Promise<PreparedPodBatch>;
+  ): Promise<GatewayResult<PreparedPodBatch>>;
+  /** Publish a prepared batch's pending documents; publishing one twice is a success. */
+  publishDocuments(
+    input: { documents: readonly PendingDocument[] },
+    ctx: RuntimeContext,
+  ): Promise<GatewayResult<object>>;
+  /** Read the transaction back and check it is the POD `sent` describes. */
   confirmPodCreation(
-    input: { txHash: string; network: Network },
+    input: { txHash: string; network: Network; sent: SentPodBatch },
+    ctx: RuntimeContext,
+  ): Promise<PodConfirmation>;
+  /** The batch that adds a confirmed POD's public domain card (one message). */
+  prepareDomainCard(
+    input: { network: Network; podDid: string; profile: PodProfile },
+    ctx: RuntimeContext,
+  ): Promise<GatewayResult<PreparedPodBatch>>;
+  /** Ask the domain indexer to index the POD now; best effort, never throws. */
+  requestIndexing(
+    input: { network: Network; podDid: string },
     ctx: RuntimeContext,
-  ): Promise<CreatedPod>;
+  ): Promise<void>;
 }
 
 const notConfigured = (): never => {
   throw new Error(
-    'ChainGateway not configured: the POD create path needs a chain gateway ' +
-      'wired to the IXO MCP server before it can prepare or confirm ' +
-      'transactions.',
+    'ChainGateway not configured: this oracle was built without a chain ' +
+      'gateway, so it cannot prepare or confirm POD creation transactions.',
   );
 };
 
-/** Default gateway that errors until a real one is wired. */
+/**
+ * A gateway that refuses every call, for a fork that wants the design
+ * pipeline without on-chain creation: the create tools report creation as
+ * unavailable without calling it.
+ */
 export const notConfiguredChainGateway: ChainGateway = {
   preparePodBatch: async () => notConfigured(),
+  publishDocuments: async () => notConfigured(),
   confirmPodCreation: async () => notConfigured(),
+  prepareDomainCard: async () => notConfigured(),
+  requestIndexing: async () => notConfigured(),
 };

package/src/plugins/pod-creator/config.ts

@@ -5,6 +5,7 @@ import {
 } from '@ixo/ixo-transaction';
 import { z } from 'zod';
 import type { RuntimeContext } from '../../plugin-api/types';
+import { DOMAIN_INDEXER_URLS } from '../domain-indexer/domain-indexer.plugin';
 import {
   chainIdConfigSchema,
   chainIdsFromConfig,
@@ -18,6 +19,9 @@ import {
  */
 export const DEFAULT_NETWORK: Network = 'testnet';
 
+/** An IXO entity DID as the chain derives it. */
+const ENTITY_DID = /^did:ixo:entity:[0-9a-f]{32}$/;
+
 /**
  * Plugin-owned env vars. The capsules registry URL and `NETWORK` are read as
  * siblings from the merged config (owned by the skills plugin / base schema),
@@ -42,14 +46,49 @@ export const podCreatorConfigSchema = z.object({
     .default(false),
   /** The chain id each network's signing request names. */
   ...chainIdConfigSchema.shape,
+  /**
+   * The relayer node a created POD names, instead of the network's default
+   * ({@link POD_RELAYER_NODE_DIDS}).
+   */
+  POD_CREATOR_RELAYER_NODE_DID: z
+    .string()
+    .regex(ENTITY_DID, 'expected an entity DID: did:ixo:entity:<32 hex>')
+    .optional(),
+  /**
+   * The Portal a created POD is linked to, instead of the network's default
+   * ({@link PORTAL_URLS}).
+   */
+  POD_CREATOR_PORTAL_URL: z.url().optional(),
 });
 
+/**
+ * The relayer node each network's Portal names on the domains (and PODs) it
+ * creates: its `NEXT_PUBLIC_DAO_DID` (ixo-portal `lib/entity/createEntity.ts`),
+ * as read from the Portal's recent "Create domain:" transactions. The
+ * mainnet Portal lists only entities of this relayer that are verified.
+ * Not the oracles' relayer (`lib/oracle/networkConfig.ts`), which only
+ * oracle entities name.
+ */
+export const POD_RELAYER_NODE_DIDS: Readonly<Record<Network, string>> = {
+  mainnet: 'did:ixo:entity:47d9c64891e77cb8e588d33b83ab3042',
+  testnet: 'did:ixo:entity:3d079ebc0b332aad3305bb4a51c72edb',
+  devnet: 'did:ixo:entity:ac12c6f8f299071eb24f2a10591d7ab7',
+};
+
+/** The Portal each network's PODs are opened in. */
+export const PORTAL_URLS: Readonly<Record<Network, string>> = {
+  mainnet: 'https://portal.qi.space',
+  testnet: 'https://test.portal.qi.space',
+  devnet: 'https://dev.portal.qi.space',
+};
+
 /** Sibling env + plugin flags the tools read at request time. */
 const configReadSchema = z.object({
   NETWORK: NetworkSchema.optional(),
   POD_CREATOR_ALLOW_MAINNET:
     podCreatorConfigSchema.shape.POD_CREATOR_ALLOW_MAINNET.optional(),
   ...chainIdConfigSchema.shape,
+  POD_CREATOR_PORTAL_URL: podCreatorConfigSchema.shape.POD_CREATOR_PORTAL_URL,
 });
 
 export interface PodCreatorConfig {
@@ -57,8 +96,12 @@ export interface PodCreatorConfig {
   mainnetAllowed: boolean;
   /** The chain id each network's signing request names. */
   chainIds: Readonly<Record<Network, string>>;
+  /** The Portal of `network`, without a trailing slash. */
+  portalUrl: string;
 }
 
+const withoutSlash = (url: string): string => url.replace(/\/+$/, '');
+
 /**
  * Network routing + the mainnet opt-in, read from the merged config. Falls
  * back to testnet with mainnet disabled when the config is unreadable — and
@@ -75,11 +118,48 @@ export function readPodCreatorConfig(ctx: RuntimeContext): PodCreatorConfig {
       network: DEFAULT_NETWORK,
       mainnetAllowed: false,
       chainIds: DEFAULT_CHAIN_IDS,
+      portalUrl: PORTAL_URLS[DEFAULT_NETWORK],
     };
   }
+  const network = parsed.data.NETWORK ?? DEFAULT_NETWORK;
   return {
-    network: parsed.data.NETWORK ?? DEFAULT_NETWORK,
+    network,
     mainnetAllowed: parsed.data.POD_CREATOR_ALLOW_MAINNET ?? false,
     chainIds: chainIdsFromConfig(parsed.data),
+    portalUrl: withoutSlash(
+      parsed.data.POD_CREATOR_PORTAL_URL ?? PORTAL_URLS[network],
+    ),
   };
 }
+
+const relayerReadSchema = z.object({
+  POD_CREATOR_RELAYER_NODE_DID:
+    podCreatorConfigSchema.shape.POD_CREATOR_RELAYER_NODE_DID,
+});
+
+/** The relayer node a POD created on `network` names: the operator's, else the network's Portal's. */
+export function relayerNodeDidFor(
+  ctx: RuntimeContext,
+  network: Network,
+): string {
+  const parsed = relayerReadSchema.safeParse(ctx.config);
+  return (
+    (parsed.success ? parsed.data.POD_CREATOR_RELAYER_NODE_DID : undefined) ??
+    POD_RELAYER_NODE_DIDS[network]
+  );
+}
+
+/** `DOMAIN_INDEXER_URL` is the domain-indexer plugin's; read here as a sibling. */
+const indexerReadSchema = z.object({ DOMAIN_INDEXER_URL: z.url().optional() });
+
+/** The domain indexer of `network`, without a trailing slash. */
+export function domainIndexerUrlFor(
+  ctx: RuntimeContext,
+  network: Network,
+): string {
+  const parsed = indexerReadSchema.safeParse(ctx.config);
+  return withoutSlash(
+    (parsed.success ? parsed.data.DOMAIN_INDEXER_URL : undefined) ??
+      DOMAIN_INDEXER_URLS[network],
+  );
+}