@ixo/oracle-runtime-workers 0.24.0 → 0.25.0

package/src/plugin-api/types.ts

@@ -762,7 +762,26 @@ export interface RuntimeContext<TConfig = MergedConfig> {
       provider: string;
       bindingId: string;
       bindingRevision: number;
-    }): Promise<import('@ixo/action-protocol').HubActionOptionsV2>;
+    }): Promise<import('@ixo/action-protocol').HubActionOptionsV3>;
+    /**
+     * A bank send of a token from the owner's options list: `amount` is a
+     * decimal in the token's display units; the host converts it to base
+     * units from the listed decimals and builds the operation (no fee).
+     */
+    transfer(input: {
+      ownerDid: string;
+      sessionId: string;
+      runId: string;
+      requestId: string;
+      provider: string;
+      bindingId: string;
+      bindingRevision: number;
+      requestKey: string;
+      toAddress: string;
+      denom: string;
+      amount: string;
+      memo: string;
+    }): Promise<ActionReferenceV1>;
     request(input: {
       ownerDid: string;
       sessionId: string;
@@ -774,7 +793,11 @@ export interface RuntimeContext<TConfig = MergedConfig> {
       requestKey: string;
       operation: ActionOperationV1;
     }): Promise<ActionReferenceV1>;
-    status(ownerDid: string, actionId: string): Promise<ActionOutcomeV1 | null>;
+    /** The latest authenticated outcome and, for a transfer, its owner-facing line. */
+    status(
+      ownerDid: string,
+      actionId: string,
+    ): Promise<{ outcome: ActionOutcomeV1 | null; summary: string | null }>;
   };
 
   decisions: {

package/src/plugins/hub-actions/hub-actions.plugin.ts

@@ -24,9 +24,37 @@ const statusSchema = z.strictObject({
   actionId: z.string().regex(/^[A-Za-z0-9_-]{32}$/),
 });
 const discoverSchema = z.strictObject({});
+const transferSchema = z.strictObject({
+  toAddress: z
+    .string()
+    .min(1)
+    .max(100)
+    .describe('The recipient address the user gave, exactly.'),
+  denom: z
+    .string()
+    .min(1)
+    .max(128)
+    .describe(
+      'The token, copied exactly from a `denom` in hub_action_options `transfer.tokens` (never guessed).',
+    ),
+  amount: z
+    .string()
+    .regex(/^(0|[1-9][0-9]*)(\.[0-9]+)?$/)
+    .max(80)
+    .describe(
+      "A decimal amount in the token's listed units (its `decimals`); for an unverified token (decimals 0) a whole number of base units.",
+    ),
+  memo: z.string().max(256).optional(),
+});
 
 export type HubActionRequestResult =
-  | { status: 'prepared'; actionReference: ActionReferenceV1; summary: string }
+  | {
+      status: 'prepared';
+      actionReference: ActionReferenceV1;
+      summary: string;
+      /** How the review reaches the user; set on a chat surface only. */
+      note?: string;
+    }
   | {
       status: 'unavailable' | 'expired';
       reason: string;
@@ -34,6 +62,34 @@ export type HubActionRequestResult =
       priorActionId?: string;
     };
 
+/**
+ * What a prepared result tells the model on a chat surface. There the
+ * finished run's Reply Plan carries the review as its own `hub-action` part
+ * (a card with the title and a review button; its title linked to the review
+ * in a plain-text rendering), so text that repeats it reaches the user twice.
+ */
+export const HUB_ACTION_CARD_NOTE =
+  'The user is shown this action automatically as a card with its title and a Review action button that opens it in Auth Hub. Do not repeat the link or the title, and do not say that you have not executed or signed anything. Reply with one short line, or nothing.';
+
+/**
+ * A prepared result. Only a chat turn's reply is a Reply Plan, so only a
+ * chat surface gets the note: on the Portal stream no card is added and the
+ * model's own text is the whole reply.
+ */
+function preparedResult(
+  reference: ActionReferenceV1,
+  ctx: RuntimeContext,
+): HubActionRequestResult {
+  return {
+    status: 'prepared',
+    actionReference: reference,
+    summary: reference.title,
+    ...(ctx.session.surface?.kind === 'chat'
+      ? { note: HUB_ACTION_CARD_NOTE }
+      : {}),
+  };
+}
+
 /**
  * The idempotency key the Hub sees: a fixed-length digest of the run and
  * tool call (the Hub allows 120 characters; a run id alone is 72).
@@ -74,6 +130,15 @@ async function requestHubAction(
   let operation;
   try {
     operation = parseOperation(parsed.data.operation);
+    if (operation.kind === 'ixo.bank.send.v1')
+      // A transfer is built by the runtime from a listed token and a
+      // display amount (request_hub_transfer): the model never supplies
+      // base units, a denom it chose or a fee.
+      return {
+        status: 'unavailable',
+        reason:
+          'Use request_hub_transfer with a token from hub_action_options for a transfer.',
+      };
   } catch (error) {
     // The protocol's own words ("Invalid fromAddress"): the model can fix
     // the field instead of guessing.
@@ -96,28 +161,83 @@ async function requestHubAction(
       operation,
     });
   } catch (error) {
-    // A cap reached, a request that expired, a run no user message
-    // started: the runtime's own words, so the model can tell the user.
+    // A request that expired, a run no user message started, a Hub
+    // refusal: the runtime's own words, so the model can tell the user.
     // Anything else stays an error.
-    if (
-      error instanceof Error &&
-      error.name === 'HubActionRefused' &&
-      'kind' in error
-    )
-      return {
-        status: error.kind === 'expired' ? 'expired' : 'unavailable',
-        reason: error.message,
-        ...('priorActionId' in error && typeof error.priorActionId === 'string'
-          ? { priorActionId: error.priorActionId }
-          : {}),
-      };
+    const refused = refusalOf(error);
+    if (refused) return refused;
     throw error;
   }
-  return {
-    status: 'prepared',
-    actionReference: reference,
-    summary: reference.title,
-  };
+  return preparedResult(reference, ctx);
+}
+
+async function requestHubTransfer(
+  input: unknown,
+  ctx: RuntimeContext,
+): Promise<HubActionRequestResult> {
+  const parsed = transferSchema.safeParse(input);
+  if (!parsed.success)
+    return {
+      status: 'unavailable',
+      reason:
+        'A recipient, a listed token denom and a plain decimal amount are required.',
+    };
+  if (ctx.config.HUB_ACTIONS_ENABLED !== 'true' || !ctx.hubActions)
+    return {
+      status: 'unavailable',
+      reason: 'Hub actions are not enabled for this oracle.',
+    };
+  const channel = ctx.session.channel;
+  if (
+    ctx.session.client !== 'channel' ||
+    !channel ||
+    !ctx.session.runId ||
+    !ctx.toolCallId
+  )
+    return {
+      status: 'unavailable',
+      reason: 'A verified channel turn is required.',
+    };
+  try {
+    const reference = await ctx.hubActions.transfer({
+      ownerDid: ctx.user.did,
+      sessionId: ctx.session.id,
+      runId: ctx.session.runId,
+      requestId: ctx.session.requestId,
+      provider: channel.provider,
+      bindingId: channel.bindingId,
+      bindingRevision: channel.bindingRevision,
+      requestKey: await hubRequestKey(ctx.session.runId, ctx.toolCallId),
+      toAddress: parsed.data.toAddress,
+      denom: parsed.data.denom,
+      amount: parsed.data.amount,
+      memo: parsed.data.memo ?? '',
+    });
+    return preparedResult(reference, ctx);
+  } catch (error) {
+    // The owner object turns the protocol refusing the operation built
+    // from the model's fields into a refusal; anything else is an error.
+    const refused = refusalOf(error);
+    if (refused) return refused;
+    throw error;
+  }
+}
+
+/** A typed runtime refusal as a result the model can relay, else null. */
+function refusalOf(error: unknown): HubActionRequestResult | null {
+  if (
+    error instanceof Error &&
+    error.name === 'HubActionRefused' &&
+    'kind' in error
+  )
+    return {
+      status: error.kind === 'expired' ? 'expired' : 'unavailable',
+      reason: error.message,
+      ...('priorActionId' in error && typeof error.priorActionId === 'string'
+        ? { priorActionId: error.priorActionId }
+        : {}),
+    };
+  return null;
 }
 
 async function hubActionStatus(
@@ -131,10 +251,11 @@ async function hubActionStatus(
     ctx.config.HUB_ACTIONS_ENABLED !== 'true'
   )
     return { status: 'unavailable' };
-  return {
-    status: 'known',
-    outcome: await ctx.hubActions.status(ctx.user.did, parsed.data.actionId),
-  };
+  const { outcome, summary } = await ctx.hubActions.status(
+    ctx.user.did,
+    parsed.data.actionId,
+  );
+  return { status: 'known', outcome, ...(summary ? { summary } : {}) };
 }
 
 async function hubActionCapabilities(
@@ -218,7 +339,7 @@ export class HubActionsPlugin extends OraclePlugin {
       {
         name: 'hub_action_options',
         description:
-          'Read this authenticated owner’s confirmed Gmail and Calendar connections, requestable documents and action resources. Use each returned service, identifier and label before preparing a related Hub review. A Gmail profile connection does not authorize sending.',
+          'Read this authenticated owner’s confirmed Gmail and Calendar connections, requestable documents, action resources and bank tokens (`transfer.tokens`: denom, symbol, decimals, verified, balance in base units). Use each returned service, identifier and label before preparing a related Hub review. A Gmail profile connection does not authorize sending. For a token that is not verified, name its full denom and say it is unverified; its amounts are base units.',
         schema: discoverSchema,
         effect: 'read',
         handler: hubActionOptions,
@@ -231,6 +352,14 @@ export class HubActionsPlugin extends OraclePlugin {
         effect: 'write',
         handler: requestHubAction,
       },
+      {
+        name: 'request_hub_transfer',
+        description:
+          'Prepare a bank transfer of one of the owner’s listed tokens for review in Auth Hub. Never signs or executes. Read hub_action_options first and copy the token `denom` exactly; give the amount as the user said it in that token’s units (no base-unit math, no fee: Auth Hub sets the fee). Name the full denom for anything but IXO, and say when a token is unverified.',
+        schema: transferSchema,
+        effect: 'write',
+        handler: requestHubTransfer,
+      },
       {
         name: 'hub_action_status',
         description:

package/src/shell/app.ts

@@ -78,22 +78,7 @@ import {
 } from '../feedback/submit';
 import { z } from 'zod';
 import { parseOutcome } from '@ixo/action-protocol';
-
-async function equalOutcomeKeys(
-  provided: string | null,
-  expected: string | undefined,
-): Promise<boolean> {
-  if (!provided || !expected || expected.length < 32 || provided.length > 512)
-    return false;
-  const digest = async (value: string) =>
-    new Uint8Array(
-      await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value)),
-    );
-  const [a, b] = await Promise.all([digest(provided), digest(expected)]);
-  let difference = 0;
-  for (let i = 0; i < a.length; i++) difference |= (a[i] ?? 0) ^ (b[i] ?? 0);
-  return difference === 0;
-}
+import { verifyHubOutcomeCallback } from '../hub-actions/outcome-signature';
 
 const DebugEventBody = z.object({
   type: z
@@ -217,6 +202,22 @@ export const BYO_LLM_BODY_BYTES = 64 * 1024;
 export const DEBUG_BODY_BYTES = 64 * 1024;
 
 /** A body cap enforced before the body is buffered: over it, 413 and the handler never runs. */
+/**
+ * The audience a signed Hub outcome callback must be signed for: the origin
+ * of `ORACLE_PUBLIC_URL` when it is set, else the origin of the request URL.
+ * An unparsable public URL yields '' (which never verifies).
+ */
+export function callbackAudience(
+  publicUrl: string | undefined,
+  requestUrl: string,
+): string {
+  try {
+    return new URL(publicUrl || requestUrl).origin;
+  } catch {
+    return '';
+  }
+}
+
 function limitBody(maxSize: number) {
   return bodyLimit({
     maxSize,
@@ -455,17 +456,32 @@ export function createShell(
   });
 
   app.use('/api/internal/actions/outcomes', limitBody(64 * 1024));
+  // Auth Hub's signed outcome callbacks: on whenever Hub actions are
+  // configured. The signature is checked against the Hub's own did:web key
+  // (from AUTH_HUB_URL) for this oracle's origin, then the owner object
+  // confirms the outcome through Auth Hub's authenticated status API.
   app.post('/api/internal/actions/outcomes', async (c) => {
     if (
       c.env.HUB_ACTIONS_ENABLED !== 'true' ||
-      !(await equalOutcomeKeys(
-        c.req.header('x-auth-hub-outcome-key') ?? null,
-        c.env.AUTH_HUB_ACTION_OUTCOME_KEY,
-      ))
+      !c.env.AUTH_HUB_URL ||
+      !c.env.AUTH_HUB_CHANNEL_SERVICE_KEY
     )
       return c.json({ code: 'unauthorized' }, 401);
     const body = await c.req.raw.text();
     if (body.length > 64_000) return c.json({ code: 'request_too_large' }, 413);
+    if (
+      !(await verifyHubOutcomeCallback({
+        hubUrl: c.env.AUTH_HUB_URL,
+        rawBody: body,
+        headers: c.req.raw.headers,
+        // The origin the Hub signs for: the configured public URL when
+        // set (a Worker reachable under several hostnames), else the
+        // origin this request came in on.
+        audience: callbackAudience(c.env.ORACLE_PUBLIC_URL, c.req.url),
+        ...(c.env.AUTH_HUB ? { fetcher: c.env.AUTH_HUB } : {}),
+      }))
+    )
+      return c.json({ code: 'unauthorized' }, 401);
     try {
       const outcome = parseOutcome(JSON.parse(body));
       await userStub(c.env, outcome.ownerDid).recordHubActionOutcome(outcome);