@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

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

@@ -0,0 +1,110 @@
+import type { BatchMessageRoute, ITrxMsg, Network } from '@ixo/ixo-transaction';
+import type { RuntimeContext } from '../../plugin-api/types';
+import type { ServicePodBlueprint } from './blueprint-types';
+
+/**
+ * The POD creation batch the user's wallet will sign as ONE transaction:
+ * proto-JSON messages the Portal can show and re-validate against the
+ * `@ixo/ixo-transaction` catalog — never encoded bytes.
+ */
+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.
+   */
+  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;
+}
+
+/**
+ * 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).
+ */
+export const POD_BATCH_TYPE_URLS = [
+  '/ixo.entity.v1beta1.MsgCreateEntity',
+  // A collection's payment accounts must be accounts of the entity.
+  '/ixo.entity.v1beta1.MsgCreateEntityAccount',
+  '/ixo.claims.v1beta1.MsgCreateCollection',
+  // Submit / evaluate authorizations from the collection admin account.
+  '/ixo.claims.v1beta1.MsgCreateClaimAuthorization',
+  // Generic or bank-send grants from an entity account.
+  '/ixo.entity.v1beta1.MsgGrantEntityAccountAuthz',
+] as const;
+
+const CREATE_ENTITY = POD_BATCH_TYPE_URLS[0];
+
+/**
+ * Why a validated batch is not a POD creation batch, or null when it is:
+ * exactly one `MsgCreateEntity`, first, and only `POD_BATCH_TYPE_URLS`.
+ */
+export function podBatchProblem(
+  routes: readonly BatchMessageRoute[],
+): string | null {
+  const allowed: readonly string[] = POD_BATCH_TYPE_URLS;
+  const foreign = routes.filter((route) => !allowed.includes(route.typeUrl));
+  if (foreign.length > 0) {
+    return `A POD creation batch carries only ${POD_BATCH_TYPE_URLS.join(', ')}; it had ${foreign
+      .map((route) => route.typeUrl)
+      .join(', ')}`;
+  }
+  const entities = routes.filter((route) => route.typeUrl === CREATE_ENTITY);
+  if (entities.length !== 1 || routes[0]?.typeUrl !== CREATE_ENTITY) {
+    return `A POD creation batch creates exactly one entity, with ${CREATE_ENTITY} as its first message`;
+  }
+  return null;
+}
+
+/** The created POD, resolved from the broadcast transaction. */
+export interface CreatedPod {
+  podDid: string;
+  summary: 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.
+ *
+ * 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.
+ */
+export interface ChainGateway {
+  preparePodBatch(
+    input: { blueprint: ServicePodBlueprint; network: Network },
+    ctx: RuntimeContext,
+  ): Promise<PreparedPodBatch>;
+  confirmPodCreation(
+    input: { txHash: string; network: Network },
+    ctx: RuntimeContext,
+  ): Promise<CreatedPod>;
+}
+
+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.',
+  );
+};
+
+/** Default gateway that errors until a real one is wired. */
+export const notConfiguredChainGateway: ChainGateway = {
+  preparePodBatch: async () => notConfigured(),
+  confirmPodCreation: async () => notConfigured(),
+};

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

@@ -0,0 +1,85 @@
+import {
+  DEFAULT_CHAIN_IDS,
+  NetworkSchema,
+  type Network,
+} from '@ixo/ixo-transaction';
+import { z } from 'zod';
+import type { RuntimeContext } from '../../plugin-api/types';
+import {
+  chainIdConfigSchema,
+  chainIdsFromConfig,
+} from '../ixo-transaction/chain-ids';
+
+/**
+ * The network every pod-creator surface falls back to when the merged config
+ * carries no readable `NETWORK` — the safe one. On a Workers oracle the base
+ * env schema always fills `NETWORK` (default `mainnet`), so in practice the
+ * mainnet opt-in below is what keeps an unconfigured oracle off mainnet.
+ */
+export const DEFAULT_NETWORK: Network = 'testnet';
+
+/**
+ * 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),
+ * so they are intentionally NOT redeclared here — two plugins declaring one
+ * key with different schemas would collide in the config-schema registry.
+ * The chain ids are the ixo-transaction plugin's own schema objects, which
+ * both plugins declare (one set of variables for every wallet-signing
+ * plugin; the composition treats the shared objects as one key).
+ */
+export const podCreatorConfigSchema = z.object({
+  /**
+   * Must be explicitly enabled before a mainnet creation batch can be
+   * prepared. Testnet / devnet require no opt-in. Accepts a real boolean
+   * (tests / programmatic config) or the string `'true'` / `'false'` (a
+   * Worker var).
+   */
+  POD_CREATOR_ALLOW_MAINNET: z
+    .union([
+      z.boolean(),
+      z.enum(['true', 'false']).transform((value) => value === 'true'),
+    ])
+    .default(false),
+  /** The chain id each network's signing request names. */
+  ...chainIdConfigSchema.shape,
+});
+
+/** 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,
+});
+
+export interface PodCreatorConfig {
+  network: Network;
+  mainnetAllowed: boolean;
+  /** The chain id each network's signing request names. */
+  chainIds: Readonly<Record<Network, string>>;
+}
+
+/**
+ * Network routing + the mainnet opt-in, read from the merged config. Falls
+ * back to testnet with mainnet disabled when the config is unreadable — and
+ * says so, since a silent network fallback on the create path would mask
+ * misconfiguration.
+ */
+export function readPodCreatorConfig(ctx: RuntimeContext): PodCreatorConfig {
+  const parsed = configReadSchema.safeParse(ctx.config);
+  if (!parsed.success) {
+    ctx.logger.warn(
+      '[pod-creator] config unreadable; defaulting to testnet with mainnet disabled',
+    );
+    return {
+      network: DEFAULT_NETWORK,
+      mainnetAllowed: false,
+      chainIds: DEFAULT_CHAIN_IDS,
+    };
+  }
+  return {
+    network: parsed.data.NETWORK ?? DEFAULT_NETWORK,
+    mainnetAllowed: parsed.data.POD_CREATOR_ALLOW_MAINNET ?? false,
+    chainIds: chainIdsFromConfig(parsed.data),
+  };
+}

package/src/plugins/pod-creator/create-session-store.ts

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+import type { RuntimeContext, UserKvSurface } from '../../plugin-api/types';
+
+/**
+ * Per-(user, thread) state machine for the create path's propose → approve →
+ * commit handoff. Exactly one batch can be pending per key: `prepared`
+ * supersedes anything before it, `approve` binds the user's go-ahead to that
+ * exact blobId, and `consume` spends the approval — so every wallet sign
+ * dispatch requires a fresh, explicit approval and a sign request can never be
+ * replayed from a stale one. Keyed by user DID as well as thread so a batch
+ * prepared in another thread (or by another user in a shared thread) can never
+ * be approved here.
+ *
+ * The session also records the request (turn) that prepared the batch, and
+ * approval is refused within that same request: the user has to send a new
+ * message after seeing the batch before it can be approved, so a single model
+ * turn — steered, say, by injected text in the brief or a section — cannot run
+ * prepare → approve → sign on its own.
+ */
+export interface CreateSessionStore {
+  /** Record a freshly prepared batch; any prior approval is superseded. */
+  prepared(
+    userDid: string,
+    threadId: string,
+    blobId: string,
+    requestId: string,
+  ): Promise<void>;
+  /**
+   * Approve the pending batch from request `requestId`. `not-prepared` when
+   * `blobId` is not the batch prepared for this user+thread; `same-request`
+   * when the approval comes from the request that prepared it.
+   */
+  approve(
+    userDid: string,
+    threadId: string,
+    blobId: string,
+    requestId: string,
+  ): Promise<ApproveOutcome>;
+  /**
+   * Spend the approval for a sign dispatch. Returns true only when `blobId`
+   * is the approved pending batch; the approval is cleared when it matches, so
+   * a second dispatch needs a fresh approve.
+   */
+  consume(userDid: string, threadId: string, blobId: string): Promise<boolean>;
+  /** Drop the session (after on-chain confirmation). */
+  clear(userDid: string, threadId: string): Promise<void>;
+}
+
+/** Resolves the create-session store for one request (it lives in the user's database). */
+export type CreateSessionStoreFor = (ctx: RuntimeContext) => CreateSessionStore;
+
+export type ApproveOutcome = 'approved' | 'not-prepared' | 'same-request';
+
+/** `ctx.kv` namespace holding one create session per (user, thread). */
+export const CREATE_SESSION_NAMESPACE = 'pod-creator/create-sessions';
+
+const createSessionSchema = z.object({
+  preparedBlobId: z.string(),
+  /** The request (turn) that prepared the batch. */
+  preparedRequestId: z.string(),
+  approved: z.boolean(),
+});
+
+type CreateSession = z.infer<typeof createSessionSchema>;
+
+/** Mirrors the blob store's default TTL — the approval is useless without the blob. */
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_MAX_ENTRIES = 1000;
+
+export interface KvCreateSessionStoreOptions {
+  maxEntries?: number;
+  ttlMs?: number;
+}
+
+/** A JSON pair cannot collide the way a joined string could. */
+const key = (userDid: string, threadId: string): string =>
+  JSON.stringify([userDid, threadId]);
+
+/**
+ * A stored session that no longer parses is treated as no session: the only
+ * consequence is that the user has to prepare the batch again, which is the
+ * safe direction for an approval gate.
+ */
+function parseSession(value: unknown): CreateSession | undefined {
+  const parsed = createSessionSchema.safeParse(value);
+  return parsed.success ? parsed.data : undefined;
+}
+
+/**
+ * {@link CreateSessionStore} over the host's `ctx.kv` rows in the user's own
+ * database, so a prepared or approved batch survives the user object being
+ * evicted between the user's "yes" and the sign request. Each transition is
+ * one atomic read-modify-write.
+ */
+export class KvCreateSessionStore implements CreateSessionStore {
+  private readonly writeOptions: { idleTtlMs: number; maxEntries: number };
+
+  constructor(
+    private readonly kv: UserKvSurface,
+    options: KvCreateSessionStoreOptions = {},
+  ) {
+    this.writeOptions = {
+      idleTtlMs: options.ttlMs ?? DEFAULT_TTL_MS,
+      maxEntries: options.maxEntries ?? DEFAULT_MAX_ENTRIES,
+    };
+  }
+
+  async prepared(
+    userDid: string,
+    threadId: string,
+    blobId: string,
+    requestId: string,
+  ): Promise<void> {
+    const session: CreateSession = {
+      preparedBlobId: blobId,
+      preparedRequestId: requestId,
+      approved: false,
+    };
+    await this.kv.set(
+      CREATE_SESSION_NAMESPACE,
+      key(userDid, threadId),
+      session,
+      this.writeOptions,
+    );
+  }
+
+  async approve(
+    userDid: string,
+    threadId: string,
+    blobId: string,
+    requestId: string,
+  ): Promise<ApproveOutcome> {
+    let outcome: ApproveOutcome = 'not-prepared';
+    await this.kv.update(
+      CREATE_SESSION_NAMESPACE,
+      key(userDid, threadId),
+      (current) => {
+        const session = parseSession(current);
+        if (!session || session.preparedBlobId !== blobId) {
+          outcome = 'not-prepared';
+          return session;
+        }
+        if (session.preparedRequestId === requestId) {
+          outcome = 'same-request';
+          return session;
+        }
+        outcome = 'approved';
+        return { ...session, approved: true };
+      },
+      this.writeOptions,
+    );
+    return outcome;
+  }
+
+  async consume(
+    userDid: string,
+    threadId: string,
+    blobId: string,
+  ): Promise<boolean> {
+    let spent = false;
+    await this.kv.update(
+      CREATE_SESSION_NAMESPACE,
+      key(userDid, threadId),
+      (current) => {
+        const session = parseSession(current);
+        spent =
+          session !== undefined &&
+          session.preparedBlobId === blobId &&
+          session.approved;
+        return session && spent ? { ...session, approved: false } : session;
+      },
+      this.writeOptions,
+    );
+    return spent;
+  }
+
+  async clear(userDid: string, threadId: string): Promise<void> {
+    await this.kv.delete(CREATE_SESSION_NAMESPACE, key(userDid, threadId));
+  }
+}