openvibers/openvibe.contracts Commits

Contracts 0.133.0: Actor task webhooks (signed per task, actor.task-webhook@1) (#86)

OP OpenVibers committed 10 Oct 2026 · tag v0.133 · 0 files, +0 −0

Plan T17: Actor task webhooks, the Contracts half. Additive; OpenVibe.Actor implements them with its pin to this release (next PR).

- **`actor.task-create-request@1`** gains `webhooks`: 1 to 8 items, each an https `url` and the `events` to deliver (platform.task@1 state names).
- **Signing:**
  - `platform.task@1` already listed `webhooks`, with a `secret_ref` naming a *project* secret. Project secrets do not exist, and a person's task has no project.
  - So Actor mints a secret per task: `platform.task@1` gains `webhook_secret` (`whsec_` and 43 characters).
  - It appears only in the answer that created the task (and an idempotent repeat), never in a read or a list, and it is erased once the task has ended and its deliveries are done.
  - The request schema leaves `secret_ref` out, so naming one is a 422 until project secrets exist.
- **New `actor.task-webhook@1`** (the delivery body): `{ type: "actor.task.state", delivery_id: "whd_…", state, task }`.
  - `delivery_id` is stable across retries; `task` is the task as it was then, without the secret.
  - Signed exactly like an Events delivery (`X-OpenVibe-Timestamp` + `X-OpenVibe-Signature-V2`), so receivers check it with openvibe-sdk/events `verifyDeliveryV2`.
  - 2xx is delivered; 410 or a URL the egress guard refuses ends it; anything else is retried for about a day.
- `lib/ids.js`: `webhook_delivery: 'whd'`. The `actor.task.create` capability describes webhooks.
- **Fixtures:**
  - valid: a request with webhooks, a delivery;
  - invalid requests: plain http, `secret_ref`;
  - invalid deliveries: one carrying the secret, one with a bad delivery id.

`node test/run.js`: 18,408 checks passed; `compat.js v0.132.0`: no breaking changes; `generated/` is up to date.