@ixo/oracle-runtime-workers 0.24.0 → 0.25.0

package/src/hub-actions/client.ts

@@ -9,7 +9,9 @@ import {
   type ActionOutcomeV1,
   type ActionReferenceV1,
   type HubActionOptionsV2,
+  type HubActionOptionsV3,
 } from '@ixo/action-protocol';
+import { hubPrepareRefusal } from './transfer';
 
 export interface HubActionStatus {
   reference: ActionReferenceV1;
@@ -27,8 +29,17 @@ export interface HubActionTransport {
   fetcher?: { fetch(request: Request): Promise<Response> };
 }
 
-/** The envelope version this runtime parses (`ixo.auth-outcome/2`, `ixo.auth-capabilities/2`). */
-const HUB_PROTOCOL_QUERY = 'version=2';
+/**
+ * The protocol version this runtime declares on every operation call
+ * (capabilities, POST operations, GET status, options). Version 3 is the
+ * 0.5.0 contract: capabilities `transfer.limits`, any-denom bank sends, v2
+ * receipts with `denom` and `amountBaseUnits`, options with the owner's
+ * tokens. Version 2 callers (runtime 0.23.0) keep the 0.4.1 shapes; the
+ * envelopes are still tagged `ixo.auth-outcome/2` and
+ * `ixo.auth-capabilities/2`, which `@ixo/action-protocol` parses.
+ */
+const HUB_PROTOCOL_VERSION = '3';
+const HUB_PROTOCOL_QUERY = `version=${HUB_PROTOCOL_VERSION}`;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -73,6 +84,22 @@ export class HubActionClient {
     const response = await (this.transport.fetcher
       ? this.transport.fetcher.fetch(request)
       : fetch(request));
+    if (
+      body !== undefined &&
+      (response.status === 400 ||
+        response.status === 409 ||
+        response.status === 503)
+    ) {
+      // A prepare the Hub refused with a typed code (a transfer that would
+      // fail, a fee above the ceiling, not enough funds, a busy or
+      // unavailable transfer path, an operation the account may not use):
+      // the model relays it in words.
+      const refusal = hubPrepareRefusal(
+        response.status,
+        await response.json().catch(() => null),
+      );
+      if (refusal) throw refusal;
+    }
     if (!response.ok)
       throw new Error(`Hub action request returned ${response.status}`);
     return response.json();
@@ -85,9 +112,9 @@ export class HubActionClient {
     expiresAt: number;
     operation: ActionOperationV1;
   }): Promise<ActionReferenceV1> {
-    // `version=2` on the three operation calls: the Hub answers v1 (P1
-    // kinds only, v1-filtered outcomes, a P2 POST refused) without it, and
-    // stores the version per action for the outcomes it pushes.
+    // `version=3` on every operation call: the Hub answers older shapes
+    // (no any-denom sends, no receipt amounts) without it, and stores the
+    // version per action for the outcomes it pushes.
     const response = await this.send(
       `/api/internal/actions/operations?${HUB_PROTOCOL_QUERY}`,
       {
@@ -111,6 +138,32 @@ export class HubActionClient {
   async options(input: {
     bindingId: string;
     bindingRevision: number;
+  }): Promise<HubActionOptionsV3> {
+    // Options version 3: version 2 plus the owner's bank tokens
+    // (`transfer.tokens`), which any-token transfers are chosen from.
+    const query = new URLSearchParams({
+      bindingId: input.bindingId,
+      bindingRevision: String(input.bindingRevision),
+      version: HUB_PROTOCOL_VERSION,
+    });
+    const options = parseActionOptions(
+      await this.send(
+        `/api/internal/actions/operations/options?${query.toString()}`,
+      ),
+    );
+    if (options.version !== 'ixo.auth-options/3')
+      throw new Error('Hub action options require version 3');
+    return options;
+  }
+
+  /**
+   * Options version 2 (connections, targets, resources; no token list),
+   * for the Gmail connection check: it does not make the Hub read the
+   * owner's balances.
+   */
+  async connectionOptions(input: {
+    bindingId: string;
+    bindingRevision: number;
   }): Promise<HubActionOptionsV2> {
     const query = new URLSearchParams({
       bindingId: input.bindingId,

package/src/hub-actions/outcome-signature.ts

@@ -0,0 +1,227 @@
+import {
+  OUTCOME_SIGNATURE_HEADERS,
+  OUTCOME_SIGNATURE_MAX_SKEW_SECONDS,
+  outcomeAudience,
+  publicKeyFromDidDocument,
+  verifyOutcomeRequest,
+} from '@ixo/action-protocol';
+import { boundedBytes } from '../core/domain-context/transport';
+
+/**
+ * Signed Auth Hub outcome callbacks. The Hub signs every callback with the
+ * `#key-0` Ed25519 key of its own did:web document; the key is resolved
+ * from the configured `AUTH_HUB_URL` (never from the request), and the
+ * signature covers this oracle's origin (the audience) so a callback
+ * signed for another oracle never verifies here.
+ */
+
+/** How long a verified Hub key is trusted per isolate. */
+export const HUB_DID_CACHE_MS = 60 * 60_000;
+/**
+ * The soonest the Hub's DID document is read again after any read, whether
+ * it succeeded or failed (a Hub outage or a forged stream must not become a
+ * stream of Hub reads).
+ */
+export const HUB_DID_REFRESH_MIN_MS = 60_000;
+/** The largest DID document read. */
+const HUB_DID_MAX_BYTES = 64 * 1024;
+
+/** Keys from documents that passed the id and key checks, per document URL. */
+const hubKeys = new Map<string, { publicKey: Uint8Array; at: number }>();
+/** When each document URL was last read (success or failure): the negative cache. */
+const lastAttemptAt = new Map<string, number>();
+/** One read per document URL at a time. */
+const inFlight = new Map<string, Promise<Uint8Array | null>>();
+
+/** Tests only: forget every cached Hub key, attempt time and pending read. */
+export function resetHubDidCache(): void {
+  hubKeys.clear();
+  lastAttemptAt.clear();
+  inFlight.clear();
+}
+
+/** The did:web DID of the Hub at `hubUrl` (https only): its key id is `#key-0`. */
+export function hubDidOf(hubUrl: string): string {
+  const url = new URL(hubUrl);
+  if (url.protocol !== 'https:' || url.username || url.password)
+    throw new TypeError('Auth Hub URL must be https');
+  return `did:web:${url.port ? `${url.hostname}%3A${url.port}` : url.hostname}`;
+}
+
+/**
+ * The checks that need no key: the Hub's key id, a well-formed timestamp
+ * within the allowed skew either way, and a signature that decodes to 64
+ * bytes. A callback failing any of them never causes a Hub read.
+ */
+function plausibleSignatureHeaders(
+  headers: Headers,
+  keyId: string,
+  nowSeconds: number,
+): boolean {
+  const timestamp = headers.get(OUTCOME_SIGNATURE_HEADERS.timestamp);
+  const signature = headers.get(OUTCOME_SIGNATURE_HEADERS.signature);
+  if (headers.get(OUTCOME_SIGNATURE_HEADERS.keyId) !== keyId) return false;
+  if (!timestamp || !/^[1-9][0-9]{0,15}$/.test(timestamp)) return false;
+  if (
+    Math.abs(nowSeconds - Number(timestamp)) >
+    OUTCOME_SIGNATURE_MAX_SKEW_SECONDS
+  )
+    return false;
+  // 64 bytes in unpadded base64url is exactly 86 characters.
+  if (!signature || !/^[A-Za-z0-9_-]{86}$/.test(signature)) return false;
+  try {
+    const padded = signature.replace(/-/g, '+').replace(/_/g, '/');
+    return atob(`${padded}==`).length === 64;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the Hub's DID document and return its `#key-0` key, or null. Every
+ * attempt is recorded first, so a read happens at most once per
+ * `HUB_DID_REFRESH_MIN_MS` per URL whatever the outcome; concurrent callers
+ * share one read; only a document that names exactly the Hub's DID and holds
+ * the key is cached.
+ */
+function readHubKey(
+  hubUrl: string,
+  hubDid: string,
+  keyId: string,
+  fetcher: { fetch(request: Request): Promise<Response> } | undefined,
+  nowMs: number,
+): Promise<Uint8Array | null> {
+  const url = new URL('/.well-known/did.json', hubUrl);
+  const pending = inFlight.get(url.href);
+  if (pending) return pending;
+  const last = lastAttemptAt.get(url.href);
+  if (last !== undefined && nowMs - last < HUB_DID_REFRESH_MIN_MS)
+    return Promise.resolve(null);
+  lastAttemptAt.set(url.href, nowMs);
+  const read = (async (): Promise<Uint8Array | null> => {
+    try {
+      const request = new Request(url, {
+        headers: { accept: 'application/did+json, application/json' },
+        // workerd has no `redirect: 'error'`; a redirect is not ok below.
+        redirect: 'manual',
+        signal: AbortSignal.timeout(5_000),
+      });
+      const response = await (fetcher
+        ? fetcher.fetch(request)
+        : fetch(request));
+      if (!response.ok)
+        throw new Error(`Hub DID document returned ${response.status}`);
+      const document: unknown = JSON.parse(
+        new TextDecoder().decode(
+          await boundedBytes(response, HUB_DID_MAX_BYTES),
+        ),
+      );
+      if (
+        !document ||
+        typeof document !== 'object' ||
+        !('id' in document) ||
+        document.id !== hubDid
+      )
+        throw new TypeError('Hub DID document is for another DID');
+      const publicKey = publicKeyFromDidDocument(document, keyId);
+      hubKeys.set(url.href, { publicKey, at: nowMs });
+      return publicKey;
+    } catch (error) {
+      console.warn(
+        `[hub-actions] Hub DID key unavailable: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return null;
+    }
+  })();
+  inFlight.set(url.href, read);
+  void read.finally(() => {
+    if (inFlight.get(url.href) === read) inFlight.delete(url.href);
+  });
+  return read;
+}
+
+async function verifiedWith(
+  publicKey: Uint8Array,
+  input: { rawBody: string; headers: Headers },
+  keyId: string,
+  audience: string,
+  nowSeconds: number,
+): Promise<boolean> {
+  try {
+    return await verifyOutcomeRequest({
+      rawBody: input.rawBody,
+      headers: input.headers,
+      publicKey,
+      expectedKeyId: keyId,
+      expectedAudience: audience,
+      now: nowSeconds,
+    });
+  } catch {
+    // A key WebCrypto refuses to import is a failed check, not a 500.
+    return false;
+  }
+}
+
+/**
+ * Whether `rawBody` with `headers` is a callback the configured Hub signed
+ * for `audience` (this oracle's https origin) within the allowed clock skew.
+ * The cheap header checks run first and need no key. The key comes from the
+ * Hub's DID document, trusted for `HUB_DID_CACHE_MS`. A Hub key rotation
+ * (same `#key-0` id, new key) is picked up by reading the document again
+ * when the cached key does not verify, subject to the same once-a-minute
+ * read limit. Anything that fails is false.
+ */
+export async function verifyHubOutcomeCallback(input: {
+  hubUrl: string;
+  rawBody: string;
+  headers: Headers;
+  audience: string;
+  fetcher?: { fetch(request: Request): Promise<Response> };
+  now?: number;
+}): Promise<boolean> {
+  const nowMs = input.now ?? Date.now();
+  const nowSeconds = Math.floor(nowMs / 1000);
+  let hubDid: string;
+  let audience: string;
+  try {
+    hubDid = hubDidOf(input.hubUrl);
+    audience = outcomeAudience(input.audience);
+  } catch {
+    return false;
+  }
+  const keyId = `${hubDid}#key-0`;
+  if (!plausibleSignatureHeaders(input.headers, keyId, nowSeconds))
+    return false;
+  const href = new URL('/.well-known/did.json', input.hubUrl).href;
+  const cached = hubKeys.get(href);
+  if (cached && nowMs - cached.at < HUB_DID_CACHE_MS) {
+    if (
+      await verifiedWith(cached.publicKey, input, keyId, audience, nowSeconds)
+    )
+      return true;
+    const fresh = await readHubKey(
+      input.hubUrl,
+      hubDid,
+      keyId,
+      input.fetcher,
+      nowMs,
+    );
+    return (
+      !!fresh &&
+      !sameBytes(fresh, cached.publicKey) &&
+      verifiedWith(fresh, input, keyId, audience, nowSeconds)
+    );
+  }
+  const key = await readHubKey(
+    input.hubUrl,
+    hubDid,
+    keyId,
+    input.fetcher,
+    nowMs,
+  );
+  return !!key && verifiedWith(key, input, keyId, audience, nowSeconds);
+}
+
+function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
+  return a.length === b.length && a.every((byte, i) => byte === b[i]);
+}

package/src/hub-actions/request.ts

@@ -36,14 +36,23 @@ export function assertOperationEnabled(
     )
       throw new Error('Hub form does not match the registered target');
   } else if (operation.kind === 'ixo.bank.send.v1') {
-    if (
-      capabilities.network !== operation.network ||
-      !capabilities.transfer ||
-      BigInt(operation.amountBaseUnits) >
-        BigInt(capabilities.transfer.maxAmountUixo) ||
-      BigInt(operation.feeBaseUnits) > BigInt(capabilities.transfer.maxFeeUixo)
-    )
+    if (capabilities.network !== operation.network || !capabilities.transfer)
       throw new Error("Hub transfer is outside this oracle's capability");
+    // A pre-check of the per-denom cap only (the Hub enforces it, and the
+    // fee is the Hub's: it simulates gas and sets it).
+    const transfer = capabilities.transfer;
+    const cap =
+      'limits' in transfer
+        ? transfer.limits.find((limit) => limit.denom === operation.denom)
+            ?.maxAmountBaseUnits
+        : operation.denom === 'uixo'
+          ? transfer.maxAmountUixo
+          : undefined;
+    if (cap !== undefined && BigInt(operation.amountBaseUnits) > BigInt(cap))
+      throw new HubActionRefused(
+        'refused',
+        `This oracle may move at most ${cap} base units of ${operation.denom} per transfer.`,
+      );
   } else if (operation.kind === 'resource.read.v1') {
     if (
       operation.ownerDid !== ownerDid ||

package/src/hub-actions/store.ts

@@ -7,6 +7,23 @@ import {
   type ActionReferenceV1,
 } from '@ixo/action-protocol';
 import type { DoSqliteDatabase } from '../sqlite/database';
+import type { TransferToken } from './transfer';
+
+function isTransferToken(value: unknown): value is TransferToken {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    'denom' in value &&
+    typeof value.denom === 'string' &&
+    'symbol' in value &&
+    typeof value.symbol === 'string' &&
+    'decimals' in value &&
+    typeof value.decimals === 'number' &&
+    Number.isSafeInteger(value.decimals) &&
+    'verified' in value &&
+    typeof value.verified === 'boolean'
+  );
+}
 
 /**
  * Outcomes after which the Hub never reports another for the action
@@ -19,10 +36,6 @@ export const HUB_CHECK_BASE_MS = 15_000;
 export const HUB_CHECK_MAX_MS = 10 * 60_000;
 /** A non-terminal action is no longer refreshed this long after its review expired. */
 export const HUB_CHECK_AFTER_EXPIRY_MS = 24 * 60 * 60_000;
-/** Prepares (Hub POSTs) per agent run, per user per hour and per user per day. */
-export const HUB_ACTIONS_PER_RUN = 2;
-export const HUB_ACTIONS_PER_HOUR = 5;
-export const HUB_ACTIONS_PER_DAY = 10;
 /** Rows are dropped this long after their review expired. */
 const HUB_RETENTION_SECONDS = 30 * 24 * 60 * 60;
 
@@ -108,6 +121,10 @@ export class HubActionStore {
       await this.db.run(
         `ALTER TABLE hub_actions ADD COLUMN check_attempts INTEGER NOT NULL DEFAULT 0`,
       );
+    // The token a transfer was prepared with (symbol, decimals, verified),
+    // for the owner-facing outcome line.
+    if (!actionColumns.some((c) => c.name === 'token'))
+      await this.db.run(`ALTER TABLE hub_actions ADD COLUMN token TEXT`);
     if (!actionColumns.some((c) => c.name === 'expires_at'))
       await this.db.run(
         `ALTER TABLE hub_actions ADD COLUMN expires_at INTEGER NOT NULL DEFAULT 0`,
@@ -185,6 +202,31 @@ export class HubActionStore {
     return row?.action_id ?? null;
   }
 
+  /** Keep the token a transfer was prepared with, for its outcome line. */
+  async setToken(actionId: string, token: TransferToken): Promise<void> {
+    await this.db.run('UPDATE hub_actions SET token = ? WHERE action_id = ?', [
+      JSON.stringify({
+        denom: token.denom,
+        symbol: token.symbol,
+        decimals: token.decimals,
+        verified: token.verified,
+      }),
+      actionId,
+    ]);
+  }
+  async token(
+    ownerDid: string,
+    actionId: string,
+  ): Promise<TransferToken | null> {
+    const row = await this.db.get<{ token: string | null }>(
+      'SELECT token FROM hub_actions WHERE owner_did = ? AND action_id = ?',
+      [ownerDid, actionId],
+    );
+    if (!row?.token) return null;
+    const value: unknown = JSON.parse(row.token);
+    return isTransferToken(value) ? value : null;
+  }
+
   /** The reference already recorded for a request key, if any. */
   async byRequestKey(requestKey: string): Promise<ActionReferenceV1 | null> {
     const row = await this.db.get<{ reference: string }>(
@@ -194,38 +236,6 @@ export class HubActionStore {
     return row ? parseReference(JSON.parse(row.reference)) : null;
   }
 
-  /**
-   * A new request (not a retry of a reserved key) within the caps:
-   * `HUB_ACTIONS_PER_RUN` per run, `HUB_ACTIONS_PER_HOUR` and
-   * `HUB_ACTIONS_PER_DAY` per owner.
-   */
-  private async assertCapacity(origin: HubActionOrigin): Promise<void> {
-    const run = await this.db.get<{ n: number }>(
-      'SELECT COUNT(*) AS n FROM hub_action_requests WHERE owner_did = ? AND session_id = ? AND run_id = ?',
-      [origin.ownerDid, origin.sessionId, origin.runId],
-    );
-    if ((run?.n ?? 0) >= HUB_ACTIONS_PER_RUN)
-      throw new HubActionRefused(
-        'limit',
-        'This request already prepared the most reviews one turn may prepare.',
-      );
-    const now = this.now();
-    const counts = await this.db.get<{ hour: number; day: number }>(
-      'SELECT SUM(created_at > ?) AS hour, COUNT(*) AS day FROM hub_action_requests WHERE owner_did = ? AND created_at > ?',
-      [now - 60 * 60_000, origin.ownerDid, now - 24 * 60 * 60_000],
-    );
-    if ((counts?.hour ?? 0) >= HUB_ACTIONS_PER_HOUR)
-      throw new HubActionRefused(
-        'limit',
-        'Too many reviews were prepared in the last hour; try again later.',
-      );
-    if ((counts?.day ?? 0) >= HUB_ACTIONS_PER_DAY)
-      throw new HubActionRefused(
-        'limit',
-        'Too many reviews were prepared today; try again tomorrow.',
-      );
-  }
-
   async reserve(
     origin: HubActionOrigin,
     operation: ActionOperationV1,
@@ -253,7 +263,6 @@ export class HubActionStore {
           );
         return previous.expires_at;
       }
-      await this.assertCapacity(origin);
       await this.db.run(
         `INSERT INTO hub_action_requests(request_key,owner_did,session_id,run_id,request_id,binding_id,binding_revision,operation,expires_at,created_at)
          VALUES(?,?,?,?,?,?,?,?,?,?)`,
@@ -467,6 +476,21 @@ export class HubActionStore {
     });
   }
 
+  /** The stored outcome of the owner's action at `sequence`, if any. */
+  async outcomeAt(
+    ownerDid: string,
+    actionId: string,
+    sequence: number,
+  ): Promise<ActionOutcomeV1 | null> {
+    const row = await this.db.get<{ outcome: string }>(
+      `SELECT o.outcome FROM hub_action_outcomes o
+         JOIN hub_actions a ON a.action_id = o.action_id
+        WHERE a.owner_did = ? AND o.action_id = ? AND o.sequence = ?`,
+      [ownerDid, actionId, sequence],
+    );
+    return row ? parseOutcome(JSON.parse(row.outcome)) : null;
+  }
+
   async outcomesForRun(
     ownerDid: string,
     sessionId: string,

package/src/hub-actions/transfer.ts

@@ -0,0 +1,182 @@
+import type { ActionReceiptV1, OptionsToken } from '@ixo/action-protocol';
+import { HubActionRefused } from './store';
+
+/**
+ * Any-token bank sends: the model names a token from the owner's
+ * `hub_action_options` list and a decimal amount in that token's display
+ * units; the runtime does the base-unit arithmetic itself, from the decimals
+ * the Hub listed. It never guesses a denom (`ibc/…` hashes included) or a
+ * fee: the Hub simulates gas and sets the fee.
+ */
+
+/** The token as the owner object stores it next to a prepared transfer. */
+export type TransferToken = Pick<
+  OptionsToken,
+  'denom' | 'symbol' | 'decimals' | 'verified'
+>;
+
+const DECIMAL_AMOUNT = /^(0|[1-9][0-9]*)(\.[0-9]+)?$/;
+
+/**
+ * `amount` (a decimal string in display units) as base units for a token
+ * with `decimals`. Refused: not a plain decimal, more fraction digits than
+ * the token has (an unverified token has 0: base units), and zero.
+ */
+export function toBaseUnits(amount: string, decimals: number): bigint {
+  const match = DECIMAL_AMOUNT.exec(amount);
+  if (!match || amount.length > 80)
+    throw new HubActionRefused(
+      'refused',
+      'The amount must be a plain decimal number such as 1.5.',
+    );
+  const whole = match[1]!;
+  // Trailing zeros carry no value: "1.50" of a 1-decimal token is 1.5.
+  const fraction = (match[2] ?? '').slice(1).replace(/0+$/, '');
+  if (fraction.length > decimals)
+    throw new HubActionRefused(
+      'refused',
+      decimals === 0
+        ? 'This token is counted in whole base units: use an amount without decimals.'
+        : `This token has ${decimals} decimals: use at most ${decimals} digits after the point.`,
+    );
+  const base =
+    BigInt(whole) * 10n ** BigInt(decimals) +
+    BigInt(fraction.padEnd(decimals, '0') || '0');
+  if (base <= 0n)
+    throw new HubActionRefused('refused', 'The amount must be above zero.');
+  return base;
+}
+
+/** Base units in display units for `decimals` (no rounding, no trailing zeros). */
+export function fromBaseUnits(base: string | bigint, decimals: number): string {
+  const value = BigInt(base);
+  if (decimals === 0) return value.toString();
+  const scale = 10n ** BigInt(decimals);
+  const whole = value / scale;
+  const fraction = (value % scale)
+    .toString()
+    .padStart(decimals, '0')
+    .replace(/0+$/, '');
+  return fraction ? `${whole}.${fraction}` : whole.toString();
+}
+
+/**
+ * How an amount of `token` reads to the owner: the listed symbol for a
+ * verified token (with the full denom for anything but `uixo`), base units
+ * and the full denom with an unverified marker otherwise.
+ */
+export function describeAmount(
+  amountBaseUnits: string,
+  token: TransferToken,
+): string {
+  if (!token.verified)
+    return `${amountBaseUnits} base units of ${token.denom} (unverified token)`;
+  const display = `${fromBaseUnits(amountBaseUnits, token.decimals)} ${token.symbol}`;
+  return token.denom === 'uixo' ? display : `${display} (${token.denom})`;
+}
+
+/** IXO itself: the chain's staking token, always verified. */
+const IXO_TOKEN: TransferToken = {
+  denom: 'uixo',
+  symbol: 'IXO',
+  decimals: 6,
+  verified: true,
+};
+
+/**
+ * The owner-facing line for a bank receipt (v2 receipts carry `denom` and
+ * `amountBaseUnits`), or null for any other receipt. Without a stored token
+ * for that denom (another runtime prepared it) `uixo` still reads as IXO;
+ * any other denom is shown in base units, unverified.
+ */
+export function bankReceiptSummary(
+  receipt: ActionReceiptV1 | null,
+  token: TransferToken | null,
+): string | null {
+  if (!receipt || receipt.kind !== 'ixo.bank.send.v1') return null;
+  const amount =
+    receipt.amountBaseUnits && receipt.denom
+      ? describeAmount(
+          receipt.amountBaseUnits,
+          token && token.denom === receipt.denom
+            ? token
+            : receipt.denom === IXO_TOKEN.denom
+              ? IXO_TOKEN
+              : {
+                  denom: receipt.denom,
+                  symbol: receipt.denom,
+                  decimals: 0,
+                  verified: false,
+                },
+        )
+      : null;
+  const what = amount ? `Transfer of ${amount}` : 'Transfer';
+  if (receipt.height === null)
+    return `${what} was not included on chain${receipt.reason ? ` (${receipt.reason.replaceAll('_', ' ')})` : ''}. Transaction ${receipt.txHash}.`;
+  return `${what} ${receipt.code === 0 ? 'confirmed' : 'failed'} on chain. Transaction ${receipt.txHash}, block ${receipt.height}.`;
+}
+
+/** What the model is told when Auth Hub refuses a transfer at preparation (400). */
+const HUB_TRANSFER_REFUSALS: Record<string, string> = {
+  simulation_failed:
+    'Auth Hub simulated this transfer and it would fail on chain',
+  fee_above_ceiling:
+    "The network fee for this transfer is above this oracle's fee limit",
+  insufficient_funds:
+    'The account does not hold enough to cover this transfer and its network fee',
+};
+/** Hub codes that pass with time (a sequence race, the transfer path down). */
+const HUB_TRANSIENT_CODES: Readonly<Record<number, readonly string[]>> = {
+  409: ['sequence_mismatch'],
+  503: ['transfer_unavailable'],
+};
+
+function hubErrorBody(
+  body: unknown,
+): { error: string; reason?: string } | null {
+  if (!body || typeof body !== 'object' || !('error' in body)) return null;
+  const error = body.error;
+  if (typeof error !== 'string' || !/^[a-z][a-z0-9_]{0,63}$/.test(error))
+    return null;
+  const reason =
+    'reason' in body && typeof body.reason === 'string' && body.reason.trim()
+      ? body.reason.trim().slice(0, 200)
+      : undefined;
+  return reason ? { error, reason } : { error };
+}
+
+/**
+ * A Hub refusal of a prepare (`{error, reason?}` with status 400, 409 or
+ * 503) as a refusal the model can relay, or null when the status and code
+ * are not one of those it maps:
+ * - 400 `simulation_failed`, `fee_above_ceiling`, `insufficient_funds`: the
+ *   transfer as asked cannot go ahead (with the Hub's reason);
+ * - 409 `sequence_mismatch`, 503 `transfer_unavailable`: temporary, try
+ *   again shortly;
+ * - any other 409: the account may not use this operation (deterministic,
+ *   a retry gets the same answer).
+ */
+export function hubPrepareRefusal(
+  status: number,
+  body: unknown,
+): HubActionRefused | null {
+  const parsed = hubErrorBody(body);
+  if (!parsed) return null;
+  const detail = parsed.reason ? `: ${parsed.reason}` : '';
+  if (status === 400 && Object.hasOwn(HUB_TRANSFER_REFUSALS, parsed.error))
+    return new HubActionRefused(
+      'refused',
+      `${HUB_TRANSFER_REFUSALS[parsed.error]}${detail}.`,
+    );
+  if (HUB_TRANSIENT_CODES[status]?.includes(parsed.error))
+    return new HubActionRefused(
+      'refused',
+      `Auth Hub is temporarily unavailable for this (${parsed.error}); try again shortly.`,
+    );
+  if (status === 409)
+    return new HubActionRefused(
+      'refused',
+      `This operation is not available for this account (${parsed.error}${detail}).`,
+    );
+  return null;
+}