@ixo/oracle-runtime-workers 0.21.2 → 0.23.0

package/src/action-proposals/topic-history.ts

@@ -0,0 +1,267 @@
+import {
+  assertContract,
+  resolveEffectiveTopicShape,
+  parseTopicOperationPayload,
+} from '@ixo/topic-protocol';
+import { z } from 'zod';
+import { canonicalizeIxoJson } from '@ixo/ixo-transaction/action-proposals';
+import type { TopicMatrixReader } from './topic-matrix';
+import {
+  TopicMatrixEventSchema,
+  readTopicEvent,
+  type TopicMatrixEvent,
+} from './topic-matrix';
+import { digestTopicProposalEffect } from './topic-store';
+import { ActionProposalConflict } from './store';
+
+const State = z.object({
+  version: z.literal(4),
+  topicId: z.string(),
+  anchor: z.object({ roomId: z.string(), rootEventId: z.string() }),
+  contracts: z.object({
+    proposed: z.unknown().optional(),
+    effective: z.unknown().optional(),
+  }),
+  projection: z.object({ revision: z.string(), contractRevision: z.string() }),
+  shape: z.object({ digest: z.string() }),
+});
+const Ref = z.object({
+  revision: z.string(),
+  bodyHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+  bodyRef: z.object({
+    provider: z.literal('matrix'),
+    roomId: z.string(),
+    eventId: z.string(),
+    contentHash: z.string(),
+  }),
+});
+const Body = z
+  .object({
+    version: z.literal(4),
+    revision: z.string(),
+    authoredBy: z.string(),
+    kindRef: z.object({
+      source: z.literal('standard'),
+      kind: z.enum([
+        'project',
+        'task',
+        'agent_task',
+        'proposal',
+        'evaluation',
+        'claims',
+        'question',
+        'discussion',
+        'incident',
+      ]),
+    }),
+    baseRecipe: z.enum([
+      'project',
+      'flow',
+      'proposal',
+      'evaluation',
+      'claims',
+      'research',
+      'discussion',
+      'incident',
+    ]),
+    shapeSources: z.array(z.unknown()),
+    shapeDigest: z.string(),
+    claimBinding: z
+      .object({ entityDid: z.string(), collectionId: z.string() })
+      .passthrough()
+      .optional(),
+    roles: z
+      .array(z.object({ roleId: z.string(), assignees: z.array(z.string()) }))
+      .default([]),
+    ownerId: z.string().optional(),
+  })
+  .passthrough();
+const ContractOperation = z.object({
+  version: z.literal(2),
+  operationId: z.string(),
+  topicId: z.string(),
+  type: z.enum(['propose-contract', 'update-contract', 'supersede-contract']),
+  previousRevision: z.string(),
+  actor: z.string(),
+  createdAt: z.string(),
+  payload: z.record(z.string(), z.unknown()),
+  capability: z.string().optional(),
+});
+export async function readTopicAuthority(
+  reader: TopicMatrixReader,
+  room: string,
+  topicId: string,
+  owner: string,
+  /** The room state the caller already read and parsed, if any. */
+  roomState?: TopicMatrixEvent[],
+) {
+  const stateEvents =
+    roomState ??
+    z
+      .array(TopicMatrixEventSchema)
+      .max(2048)
+      .parse(await reader.state(room));
+  const stateEvent = stateEvents.find(
+    (e) => e.type === 'ixo.topic.contract' && e.state_key === topicId,
+  );
+  if (!stateEvent)
+    throw new ActionProposalConflict('Canonical topic state is unavailable');
+  const state = State.parse(stateEvent.content);
+  if (state.topicId !== topicId || state.anchor.roomId !== room)
+    throw new ActionProposalConflict('Topic locator mismatch');
+  const root = await readTopicEvent(reader, room, state.anchor.rootEventId);
+  if (
+    root.sender !== owner ||
+    root.type !== 'm.room.message' ||
+    root.room_id !== room
+  )
+    throw new ActionProposalConflict(
+      'Only owner-authored topic history is supported',
+    );
+  const history = z
+    .array(TopicMatrixEventSchema)
+    .max(256)
+    // Only the owner's relations are fetched and decrypted: authority here
+    // is owner-authored, and another member's relations must neither cost a
+    // decrypt nor fork or overflow the history read.
+    .parse(await reader.history(room, root.event_id, { sender: owner }));
+  const contracts = history
+    .filter((e) => e.sender === owner && e.type === 'ixo.topic.operation')
+    .flatMap((event) => {
+      const raw = z
+        .object({
+          operation: z
+            .object({ topicId: z.string(), type: z.string() })
+            .passthrough(),
+        })
+        .parse(event.content).operation;
+      if (
+        raw.topicId !== topicId ||
+        !['propose-contract', 'update-contract', 'supersede-contract'].includes(
+          raw.type,
+        )
+      )
+        return [];
+      const operation = ContractOperation.parse(raw);
+      if (
+        event.room_id !== room ||
+        z
+          .object({
+            'm.relates_to': z.object({
+              rel_type: z.literal('m.reference'),
+              event_id: z.literal(root.event_id),
+            }),
+          })
+          .safeParse(event.content).success !== true
+      )
+        throw new ActionProposalConflict(
+          'Topic operation root binding mismatch',
+        );
+      parseTopicOperationPayload(operation);
+      return [{ event, operation }];
+    });
+  let prior = root.event_id;
+  let selected: (typeof contracts)[number] | undefined;
+  const remaining = [...contracts];
+  while (remaining.length) {
+    const next = remaining.filter(
+      (e) => e.operation?.previousRevision === prior,
+    );
+    if (next.length !== 1)
+      throw new ActionProposalConflict('Topic history is incomplete or forked');
+    const entry = next[0]!;
+    const op = entry.operation;
+    if (entry.event.sender !== owner || op.actor !== owner)
+      throw new ActionProposalConflict(
+        'Delegated contract mutation requires an unsupported authority proof',
+      );
+    if (
+      op.payload.previousRevision !== prior &&
+      op.payload.topicPreviousRevision !== prior
+    )
+      throw new ActionProposalConflict('Topic operation revision mismatch');
+    prior = op.operationId;
+    selected = entry;
+    remaining.splice(remaining.indexOf(entry), 1);
+  }
+  if (!selected?.operation || prior !== state.projection.contractRevision)
+    throw new ActionProposalConflict(
+      'Topic projection is not backed by complete contract history',
+    );
+  const ref = Ref.parse(
+    selected.operation.payload.contractRef ??
+      selected.operation.payload.contract,
+  );
+  if (
+    ref.revision !== prior ||
+    ref.bodyRef.roomId !== room ||
+    ref.bodyRef.contentHash !== ref.bodyHash
+  )
+    throw new ActionProposalConflict('Pinned body reference mismatch');
+  const selectedHead = Ref.parse(
+    state.contracts.proposed ?? state.contracts.effective,
+  );
+  if (canonicalizeIxoJson(selectedHead) !== canonicalizeIxoJson(ref))
+    throw new ActionProposalConflict(
+      'Projection body head differs from authenticated history',
+    );
+  const bodyEvent = await readTopicEvent(reader, room, ref.bodyRef.eventId);
+  if (
+    bodyEvent.sender !== owner ||
+    bodyEvent.room_id !== room ||
+    bodyEvent.type !== 'ixo.topic.contract.body' ||
+    z
+      .object({ 'm.relates_to': z.object({ event_id: z.string() }) })
+      .parse(bodyEvent.content)['m.relates_to'].event_id !== root.event_id
+  )
+    throw new ActionProposalConflict('Pinned body sender mismatch');
+  const body = Body.parse(bodyEvent.content.contract);
+  assertContract('topic-contract-body', body);
+  const bodyHash = `sha256:${await digestTopicProposalEffect(bodyEvent.content.contract)}`;
+  if (
+    bodyHash !== ref.bodyHash ||
+    body.revision !== prior ||
+    body.authoredBy !== owner
+  )
+    throw new ActionProposalConflict('Pinned body integrity mismatch');
+  const shape = resolveEffectiveTopicShape({
+    baseRecipe: body.baseRecipe,
+    kind: body.kindRef.kind,
+    // The shape release (`TOPIC_SHAPE_RELEASE`), not the package version.
+    sourceVersion: '1.0.0-rc.7',
+  });
+  if (
+    shape.digest !== body.shapeDigest ||
+    shape.digest !== state.shape.digest ||
+    canonicalizeIxoJson(shape.sources) !==
+      canonicalizeIxoJson(body.shapeSources)
+  )
+    throw new ActionProposalConflict('Pinned shape is unsupported or changed');
+  const authority = {
+    rootEventId: root.event_id,
+    contractBodyEventId: bodyEvent.event_id,
+    operationEventId: selected.event.event_id,
+    stateEventId: stateEvent.event_id,
+    contractBodyHash: bodyHash,
+    revision: prior,
+    shapeDigest: shape.digest,
+  };
+  // The state event is re-emitted by ordinary projection activity; the
+  // contract head it points at is what carries authority.
+  const { stateEventId: _state, ...pinned } = authority;
+  return {
+    authority,
+    body,
+    // The fingerprint is the authority chain's head and the pinned body: a
+    // new contract operation changes `authority.revision`, while ordinary
+    // activity in the topic thread (a reply, a reaction) does not block the
+    // owner's claim.
+    dependencies: [
+      {
+        kind: 'topic' as const,
+        key: topicId,
+        digest: await digestTopicProposalEffect({ authority: pinned, body }),
+      },
+    ],
+  };
+}

package/src/action-proposals/topic-matrix.ts

@@ -0,0 +1,292 @@
+import { z } from 'zod';
+import { boundedBytes } from '../core/domain-context/transport';
+import { digestTopicProposalEffect } from './topic-store';
+import { ActionProposalConflict } from './store';
+import { TopicReadUnavailable } from './topic-errors';
+import type { TopicActionProposal } from '@ixo/ixo-transaction/topic-proposals';
+
+export const TopicMatrixEventSchema = z.object({
+  event_id: z.string().startsWith('$').max(512),
+  type: z.string().min(1),
+  state_key: z.string().optional(),
+  content: z.record(z.string(), z.unknown()),
+  sender: z.string().regex(/^@[^:]+:.+$/),
+  room_id: z.string().optional(),
+  origin_server_ts: z.number().optional(),
+});
+export type TopicMatrixEvent = z.infer<typeof TopicMatrixEventSchema>;
+/**
+ * What a topic read may tell the gateway about itself: the moment its
+ * budget ends (the gateway stops before it, decrypt waits included) and,
+ * for history, the only sender whose relations matter (others are never
+ * decrypted or counted).
+ */
+export type TopicReadOptions = { deadlineAt?: number; sender?: string };
+export interface TopicMatrixReader {
+  state(roomId: string): Promise<unknown>;
+  event(
+    roomId: string,
+    eventId: string,
+    opts?: TopicReadOptions,
+  ): Promise<unknown>;
+  history(
+    roomId: string,
+    root: string,
+    opts?: TopicReadOptions,
+  ): Promise<unknown>;
+}
+const DidResponse = z.object({
+  data: z.object({
+    iids: z.object({
+      nodes: z
+        .array(
+          z.object({
+            id: z.string(),
+            service: z.array(
+              z.object({ type: z.string(), serviceEndpoint: z.string() }),
+            ),
+          }),
+        )
+        .max(2),
+    }),
+  }),
+  errors: z.array(z.unknown()).optional(),
+});
+export async function resolveTopicIdentity(
+  did: string,
+  blocksync: string | undefined,
+  fetcher: typeof fetch = fetch,
+) {
+  if (!blocksync)
+    throw new TopicReadUnavailable('Trusted DID resolver is unavailable');
+  const endpoint = new URL(blocksync);
+  if (endpoint.protocol !== 'https:' || endpoint.username || endpoint.password)
+    throw new TopicReadUnavailable('Invalid trusted DID endpoint');
+  const response = await fetcher(endpoint, {
+    method: 'POST',
+    redirect: 'error',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      query:
+        'query TopicIdentity($id:String!){iids(filter:{id:{equalTo:$id}}){nodes{id service}}}',
+      variables: { id: did },
+    }),
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!response.ok) throw new TopicReadUnavailable('DID lookup unavailable');
+  const envelope = DidResponse.safeParse(
+    JSON.parse(new TextDecoder().decode(await boundedBytes(response, 65536))),
+  );
+  // A GraphQL error envelope (`data: null`, `errors`) is the resolver
+  // failing, not a fact about the DID.
+  if (!envelope.success || envelope.data.errors?.length)
+    throw new TopicReadUnavailable('DID lookup unavailable');
+  const raw = envelope.data;
+  if (raw.data.iids.nodes.length !== 1)
+    throw new ActionProposalConflict('Identity is not indexed');
+  const record = raw.data.iids.nodes[0]!;
+  if (record.id !== did)
+    throw new ActionProposalConflict('DID lookup mismatch');
+  const services = record.service.filter((s) => s.type === 'MatrixHomeServer');
+  if (services.length !== 1)
+    throw new ActionProposalConflict(
+      'Exactly one Matrix homeserver is required',
+    );
+  const url = new URL(services[0]!.serviceEndpoint);
+  if (
+    url.protocol !== 'https:' ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname !== '/' ||
+    url.port
+  )
+    throw new ActionProposalConflict('Invalid DID Matrix service');
+  const homeserver = url.origin;
+  const matrixUserId = `@${did.replaceAll(':', '-')}:${url.hostname}`;
+  return {
+    did,
+    matrixUserId,
+    homeserver,
+    bindingDigest: await digestTopicProposalEffect({
+      did,
+      service: services[0],
+    }),
+  };
+}
+/**
+ * One event, parsed. An event the gateway cannot hand over (not decrypted
+ * yet, not found) comes back empty: a read that failed, not a fact about the
+ * card.
+ */
+export async function readTopicEvent(
+  reader: TopicMatrixReader,
+  room: string,
+  eventId: string,
+) {
+  const raw = await reader.event(room, eventId);
+  if (raw === null || raw === undefined)
+    throw new TopicReadUnavailable('Topic event is not readable');
+  return TopicMatrixEventSchema.parse(raw);
+}
+export async function readTopicRoom(
+  reader: TopicMatrixReader,
+  room: string,
+  owner: string,
+) {
+  const state = z
+    .array(TopicMatrixEventSchema)
+    .max(2048)
+    .parse(await reader.state(room));
+  if (
+    new Set(state.map((e) => `${e.type}\0${e.state_key ?? ''}`)).size !==
+    state.length
+  )
+    throw new TopicReadUnavailable('Room state has duplicate keys');
+  const membership = state.find(
+    (e) => e.type === 'm.room.member' && e.state_key === owner,
+  );
+  const power = state.find(
+    (e) => e.type === 'm.room.power_levels' && e.state_key === '',
+  );
+  const encryption = state.find(
+    (e) => e.type === 'm.room.encryption' && e.state_key === '',
+  );
+  const creation = state.find(
+    (e) => e.type === 'm.room.create' && e.state_key === '',
+  );
+  if (membership?.content.membership !== 'join' || !power || !creation)
+    throw new ActionProposalConflict(
+      'The owner is not a member of the room, or its policy is unreadable',
+    );
+  const levels = z
+    .object({
+      users: z.record(z.string(), z.number()).default({}),
+      users_default: z.number().default(0),
+      events: z.record(z.string(), z.number()).default({}),
+      events_default: z.number().default(0),
+      state_default: z.number().default(50),
+    })
+    .parse(power.content);
+  const level = levels.users[owner] ?? levels.users_default;
+  for (const type of [
+    'm.room.message',
+    'ixo.topic.contract.body',
+    'ixo.topic.operation',
+    'ixo.topic.contract',
+  ]) {
+    const required =
+      levels.events[type] ??
+      (type === 'ixo.topic.contract'
+        ? levels.state_default
+        : levels.events_default);
+    if (level < required)
+      throw new ActionProposalConflict(
+        'Owner cannot write the topic event types',
+      );
+  }
+  const selected = [
+    creation,
+    membership,
+    power,
+    ...(encryption ? [encryption] : []),
+  ];
+  // Only the facts that carry authority are fingerprinted: the owner's
+  // membership value (not their avatar or display name) and each policy
+  // event's content (not the event id a re-send would change).
+  const topicTypes = [
+    'm.room.message',
+    'ixo.topic.contract.body',
+    'ixo.topic.operation',
+    'ixo.topic.contract',
+  ];
+  const authority = (e: TopicMatrixEvent) => ({
+    type: e.type,
+    state_key: e.state_key ?? '',
+    content:
+      e.type === 'm.room.member'
+        ? { membership: e.content.membership }
+        : e.type === 'm.room.power_levels'
+          ? // Only the owner's level and the thresholds for the topic event
+            // types: another member's level changing is not this card's
+            // business.
+            {
+              owner: levels.users[owner] ?? levels.users_default,
+              events: Object.fromEntries(
+                topicTypes.map((type) => [
+                  type,
+                  levels.events[type] ??
+                    (type === 'ixo.topic.contract'
+                      ? levels.state_default
+                      : levels.events_default),
+                ]),
+              ),
+            }
+          : e.content,
+  });
+  const dependencies = await Promise.all(
+    selected.map(async (e) => ({
+      kind: 'matrix' as const,
+      key: `${e.type}\0${e.state_key ?? ''}`,
+      digest: await digestTopicProposalEffect(authority(e)),
+    })),
+  );
+  if (!encryption)
+    dependencies.push({
+      kind: 'matrix',
+      key: 'm.room.encryption\0',
+      digest: await digestTopicProposalEffect(null),
+    });
+  return { state, dependencies, encrypted: !!encryption };
+}
+export async function assertTopicRoomUnchanged(
+  proposal: TopicActionProposal,
+  reader: TopicMatrixReader,
+  blocksync: string | undefined,
+  fetcher: typeof fetch = fetch,
+) {
+  const owner = await resolveTopicIdentity(
+    proposal.ownerDid,
+    blocksync,
+    fetcher,
+  );
+  if (
+    owner.bindingDigest !== proposal.action.owner.bindingDigest ||
+    owner.matrixUserId !== proposal.action.owner.matrixUserId ||
+    owner.homeserver !== proposal.action.owner.homeserver
+  )
+    throw new ActionProposalConflict('Owner Matrix identity changed');
+  const current = await readTopicRoom(
+    reader,
+    proposal.action.roomId,
+    owner.matrixUserId,
+  );
+  for (const dep of proposal.action.dependencies.filter(
+    (d) => d.kind === 'matrix',
+  ))
+    if (
+      !current.dependencies.some(
+        (d) => d.key === dep.key && d.digest === dep.digest,
+      )
+    )
+      throw new ActionProposalConflict('Room authority changed');
+  const people =
+    proposal.action.name === 'create_topic'
+      ? proposal.action.participants
+      : proposal.action.grants.map((g) => g.grantee);
+  const bindings = await Promise.all(
+    people.map((person) =>
+      resolveTopicIdentity(person.did, blocksync, fetcher),
+    ),
+  );
+  people.forEach((person, i) => {
+    const binding = bindings[i]!;
+    if (
+      binding.bindingDigest !== person.bindingDigest ||
+      binding.matrixUserId !== person.matrixUserId
+    )
+      throw new ActionProposalConflict('Participant identity changed');
+  });
+  return current;
+}