@ixo/oracle-runtime-workers 0.22.0 → 0.23.0

package/src/hub-actions/client.ts

@@ -0,0 +1,163 @@
+import {
+  assertHubReferenceUrl,
+  parseCapabilities,
+  parseActionOptions,
+  parseOperation,
+  parseOutcome,
+  type ActionOperationV1,
+  type ActionCapabilitiesV1,
+  type ActionOutcomeV1,
+  type ActionReferenceV1,
+  type HubActionOptionsV2,
+} from '@ixo/action-protocol';
+
+export interface HubActionStatus {
+  reference: ActionReferenceV1;
+  ownerDid: string;
+  revision: number;
+  digest: string;
+  reviewStatus: string;
+  operationStatus: string;
+  outcome: ActionOutcomeV1 | null;
+}
+
+export interface HubActionTransport {
+  origin: string;
+  key: string;
+  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';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export class HubActionClient {
+  private readonly origin: string;
+
+  constructor(private readonly transport: HubActionTransport) {
+    const url = new URL(transport.origin);
+    if (
+      !(
+        url.protocol === 'https:' ||
+        (url.protocol === 'http:' && url.hostname === 'localhost')
+      ) ||
+      url.pathname !== '/' ||
+      url.search ||
+      url.hash ||
+      url.username ||
+      url.password ||
+      !transport.key
+    )
+      throw new Error('Hub action transport requires a secure origin and key');
+    this.origin = url.origin;
+  }
+
+  private async send(
+    path: string,
+    body?: unknown,
+    timeoutMs = 10_000,
+  ): Promise<unknown> {
+    const request = new Request(new URL(path, this.origin), {
+      method: body === undefined ? 'GET' : 'POST',
+      headers: {
+        'x-channels-service-key': this.transport.key,
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: AbortSignal.timeout(timeoutMs),
+      redirect: 'manual',
+    });
+    const response = await (this.transport.fetcher
+      ? this.transport.fetcher.fetch(request)
+      : fetch(request));
+    if (!response.ok)
+      throw new Error(`Hub action request returned ${response.status}`);
+    return response.json();
+  }
+
+  async request(input: {
+    bindingId: string;
+    bindingRevision: number;
+    requestKey: string;
+    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.
+    const response = await this.send(
+      `/api/internal/actions/operations?${HUB_PROTOCOL_QUERY}`,
+      {
+        ...input,
+        operation: parseOperation(input.operation),
+      },
+    );
+    if (!response || typeof response !== 'object' || !('reference' in response))
+      throw new Error('Hub action response has no reference');
+    return assertHubReferenceUrl(response.reference, this.origin);
+  }
+
+  async capabilities(): Promise<ActionCapabilitiesV1> {
+    return parseCapabilities(
+      await this.send(
+        `/api/internal/actions/operations/capabilities?${HUB_PROTOCOL_QUERY}`,
+      ),
+    );
+  }
+
+  async options(input: {
+    bindingId: string;
+    bindingRevision: number;
+  }): Promise<HubActionOptionsV2> {
+    const query = new URLSearchParams({
+      bindingId: input.bindingId,
+      bindingRevision: String(input.bindingRevision),
+      version: '2',
+    });
+    const options = parseActionOptions(
+      await this.send(
+        `/api/internal/actions/operations/options?${query.toString()}`,
+      ),
+    );
+    if (options.version !== 'ixo.auth-options/2')
+      throw new Error('Hub action options require version 2');
+    return options;
+  }
+
+  /** `timeoutMs`: the poll path passes a short one (a slow Hub must not hold a poll). */
+  async status(id: string, timeoutMs = 10_000): Promise<HubActionStatus> {
+    if (!/^[A-Za-z0-9_-]{32}$/.test(id))
+      throw new Error('Invalid Hub action id');
+    const raw = await this.send(
+      `/api/internal/actions/operations/${id}?${HUB_PROTOCOL_QUERY}`,
+      undefined,
+      timeoutMs,
+    );
+    if (!isRecord(raw)) throw new Error('Invalid Hub action status');
+    const value = raw;
+    const reference = assertHubReferenceUrl(value.reference, this.origin);
+    if (
+      reference.id !== id ||
+      typeof value.ownerDid !== 'string' ||
+      !value.ownerDid.startsWith('did:ixo:') ||
+      !Number.isSafeInteger(value.revision) ||
+      typeof value.digest !== 'string' ||
+      !/^[a-f0-9]{64}$/.test(value.digest) ||
+      typeof value.reviewStatus !== 'string' ||
+      typeof value.operationStatus !== 'string'
+    )
+      throw new Error('Invalid Hub action status');
+    return {
+      reference,
+      ownerDid: value.ownerDid,
+      revision: Number(value.revision),
+      digest: value.digest,
+      reviewStatus: value.reviewStatus,
+      operationStatus: value.operationStatus,
+      outcome: value.outcome == null ? null : parseOutcome(value.outcome),
+    };
+  }
+}

package/src/hub-actions/request.ts

@@ -0,0 +1,110 @@
+import {
+  canonicalJson,
+  type ActionCapabilitiesV1,
+  type ActionOperationV1,
+  type ActionReferenceV1,
+} from '@ixo/action-protocol';
+import type { HubActionClient } from './client';
+import { HubActionRefused, type HubActionOrigin } from './store';
+
+export interface PreparedHubActionRequest extends HubActionOrigin {
+  provider: string;
+  operation: ActionOperationV1;
+}
+
+export function assertOperationEnabled(
+  capabilities: ActionCapabilitiesV1,
+  operation: ActionOperationV1,
+  ownerDid: string,
+): void {
+  if (!capabilities.operations.includes(operation.kind))
+    throw new Error('Hub operation is not enabled for this oracle');
+  if (operation.kind === 'form.submit.v1') {
+    const form = capabilities.forms.find(
+      (item) => item.formId === operation.formId,
+    );
+    if (
+      !form ||
+      form.destination !== operation.destination ||
+      form.declaration !== operation.declaration ||
+      canonicalJson(form.fields) !==
+        canonicalJson(
+          operation.fields.map(
+            ({ value: _value, source: _source, ...field }) => field,
+          ),
+        )
+    )
+      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)
+    )
+      throw new Error("Hub transfer is outside this oracle's capability");
+  } else if (operation.kind === 'resource.read.v1') {
+    if (
+      operation.ownerDid !== ownerDid ||
+      !capabilities.resourceOrigin ||
+      new URL(operation.url).origin !== capabilities.resourceOrigin
+    )
+      throw new Error("Hub resource is outside this owner's capability");
+  }
+}
+
+/** The host verifies the channel binding before invoking this transport. */
+export async function prepareHubAction(
+  client: Pick<HubActionClient, 'capabilities' | 'request'>,
+  store: {
+    reserve(
+      origin: HubActionOrigin,
+      operation: ActionOperationV1,
+      proposedExpiry: number,
+    ): Promise<number>;
+    record(
+      origin: HubActionOrigin,
+      reference: ActionReferenceV1,
+    ): Promise<ActionReferenceV1>;
+    byRequestKey?(requestKey: string): Promise<ActionReferenceV1 | null>;
+  },
+  input: PreparedHubActionRequest,
+  nowMs = Date.now(),
+): Promise<ActionReferenceV1> {
+  const capabilities = await client.capabilities();
+  assertOperationEnabled(capabilities, input.operation, input.ownerDid);
+  const expiresAt = await store.reserve(
+    input,
+    input.operation,
+    Math.floor(nowMs / 1000) + 15 * 60,
+  );
+  // A retry of a key whose reservation lapsed: the Hub refuses a past
+  // expiry before its idempotency lookup, so a POST could never succeed.
+  // The recorded reference (the first POST's) is the answer if there is
+  // one; otherwise the request is over.
+  if (expiresAt <= Math.floor(nowMs / 1000)) {
+    const recorded = await store.byRequestKey?.(input.requestKey);
+    if (recorded) return recorded;
+    throw new HubActionRefused(
+      'expired',
+      'This review request expired before it reached Auth Hub; ask the user to confirm again.',
+    );
+  }
+  const reference = await client.request({
+    bindingId: input.bindingId,
+    bindingRevision: input.bindingRevision,
+    requestKey: input.requestKey,
+    expiresAt,
+    operation: input.operation,
+  });
+  if (
+    reference.accountId !== capabilities.accountId ||
+    reference.bindingId !== input.bindingId ||
+    reference.bindingRevision !== input.bindingRevision
+  )
+    throw new Error(
+      'Hub action reference does not match the authenticated account',
+    );
+  return store.record(input, reference);
+}