diff --git a/PRODUCT.md b/PRODUCT.md index 982b43b..1cfc838 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -74,7 +74,7 @@ in REST:ACT the API's clients deploy it, it runs as each caller, and it is charg ## Evidence on Hand -- The draft and its companion documents (presentation verbs, registries), rendered under `/spec/`. +- The draft and its companion documents (the extension drafts, registries), rendered under `/spec/`. - Interactive explanations: `AnatomyDemo.astro` (four requests against `notes/42`), `ResolutionWalk.astro`. - Real behaviour from restactd: status codes 408/429/507, default limits, the `/.well-known/restact` document, verbatim shell sessions. diff --git a/README.md b/README.md index 959a491..aebafcb 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,8 @@ the hub, the page descriptions) is still checked. Meta descriptions are always c ## The specification pages -`/spec/`, `/spec/draft/`, `/spec/presentation-verbs/` and `/spec/registries/` are rendered at build +`/spec/`, `/spec/draft/`, the extension drafts (`/spec/objects/`, `/spec/events/`, `/spec/delegation/`, +`/spec/connectors/`, `/spec/mcp/`, `/spec/http-verbs/` and `/spec/presentation-verbs/`) and `/spec/registries/` are rendered at build time from copies of the sources in `stackumi/restact` (the specification repository), committed under `src/content/spec/` (the Cloudflare build needs no sibling checkout). `SOURCE.json` there records the source commit. When the specification changes, a person runs @@ -43,7 +44,7 @@ corepack pnpm sync:spec [path-to-spec-checkout] # default ../restact corepack pnpm verify ``` -and commits the result. The sync vendors both drafts (the protocol draft and the presentation draft) and keeps only the `ins:` line of each draft's `author:` list (any +and commits the result. The sync vendors all eight drafts (the protocol draft and the seven extension drafts) and keeps only the `ins:` line of each draft's `author:` list (any other key there is dropped), stops with an error if a draft has no front matter, and scans every copied file for an email address, deleting its output and failing if it finds one. No address enters this repository. `src/lib/specmd.ts` turns the kramdown-rfc drafts and the plain @@ -83,7 +84,7 @@ the site keeps its own. | `src/layouts/Docs.astro` | docs page: side nav, article, on-this-page list, prev/next | | `src/layouts/MdPage.astro` | maps MDX frontmatter onto `Docs.astro` | | `src/components/` | Shell: Header, Tagline, ThemeToggle, Footer. Building blocks: CodeBlock, Tabs, Callout, MethodTag, InRestactd, ReaderGroups, SpecBody, SpecSideNav. Figures and demos: AnatomyDemo, Venn, BudgetFigure, UiMock, UiDocumentDemo, NodeFamilies, ResolutionWalk | -| `src/pages/spec/` | the specification hub, the draft, presentation verbs and registries pages | +| `src/pages/spec/` | the specification hub, the draft, the extension drafts and registries pages | | `scripts/` | `sync-spec.mjs` (vendor the specification sources), `sync-docs.mjs` (vendor the restactd docs), `check-site.mjs` (content checks), `vendored.mjs` (their shared scans) | | `src/lib/term.ts` | markup helper for hand-coloured terminal and JSON blocks | | `src/lib/shiki-theme.mjs` | the highlighting theme, built from the CSS tokens | diff --git a/scripts/check-site.mjs b/scripts/check-site.mjs index 5724e1a..5c9f448 100644 --- a/scripts/check-site.mjs +++ b/scripts/check-site.mjs @@ -23,7 +23,7 @@ // their own 404 page and agree with INDEXABLE on noindex; the page rules above skip them import { readFileSync, statSync, existsSync } from 'node:fs'; import { join, relative } from 'node:path'; -import { EMAIL, FORBIDDEN, scanText, treeHash, walk } from './vendored.mjs'; +import { FORBIDDEN, findEmail, scanText, treeHash, walk } from './vendored.mjs'; const DIST = new URL('../dist/', import.meta.url).pathname; const CONFIG = new URL('../src/site.config.ts', import.meta.url).pathname; @@ -61,8 +61,8 @@ const SPEC_SRC = new URL('../src/content/spec/', import.meta.url).pathname; if (existsSync(SPEC_SRC)) { for (const f of walk(SPEC_SRC)) { if (!f.endsWith('.md')) continue; - const m = readFileSync(f, 'utf8').match(EMAIL); - if (m) err(relative(SPEC_SRC, f), `email address "${m[0]}" in a vendored specification file`); + const m = findEmail(readFileSync(f, 'utf8')); + if (m) err(relative(SPEC_SRC, f), `email address "${m}" in a vendored specification file`); } } @@ -106,8 +106,8 @@ for (const file of pages) { if (m) err(page, `banned wording "${m[0]}"`); } // (b) emails, anywhere in the markup (scripts and styles excluded) - const em = noScripts.match(EMAIL); - if (em) err(page, `email address "${em[0]}"`); + const em = findEmail(noScripts); + if (em) err(page, `email address "${em}"`); // (c) forbidden names and hosts, anywhere including code for (const [re, label] of FORBIDDEN) if (re.test(noScripts)) err(page, `contains ${label}`); // (d) noindex while not indexable diff --git a/scripts/sync-spec.mjs b/scripts/sync-spec.mjs index 1008407..ec9bbce 100644 --- a/scripts/sync-spec.mjs +++ b/scripts/sync-spec.mjs @@ -4,21 +4,25 @@ // // corepack pnpm sync:spec [path-to-spec-checkout] (default: ../restact) // -// The vendored copies are not edited, with one exception: each draft's front matter (the protocol -// draft and the presentation draft) keeps only the `ins:` line of its author list, so no address enters this repository (a scan of every copied .md +// The vendored copies are not edited, with one exception: each draft's front matter keeps only the `ins:` line of its author list, so no address enters this repository (a scan of every copied .md // file for an address then fails the sync as a second guard). The author stays // `ins: N. Byrd`. SOURCE.json records the commit the copies came from. import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'; import { execFileSync } from 'node:child_process'; import { join, resolve } from 'node:path'; +import { findEmail } from './vendored.mjs'; const root = new URL('..', import.meta.url).pathname; const src = resolve(process.argv[2] ?? join(root, '..', 'restact')); const out = join(root, 'src', 'content', 'spec'); const DRAFT = 'draft-byrd-restact-protocol-00.md'; -const PRESENTATION = 'draft-byrd-restact-presentation-00.md'; -for (const f of [DRAFT, PRESENTATION]) { +// The extension drafts, vendored with the same treatment as the protocol draft. +const EXTENSIONS = ['objects', 'events', 'delegation', 'connectors', 'mcp', 'http-verbs', 'presentation'].map( + (n) => `draft-byrd-restact-${n}-00.md`, +); +const ALL = [DRAFT, ...EXTENSIONS]; +for (const f of ALL) { if (!existsSync(join(src, f))) { console.error(`sync-spec: ${join(src, f)} not found. Pass the path to a checkout of stackumi/restact.`); process.exit(2); @@ -28,7 +32,7 @@ for (const f of [DRAFT, PRESENTATION]) { const git = (...args) => execFileSync('git', ['-C', src, ...args], { encoding: 'utf8' }).trim(); const commit = git('rev-parse', 'HEAD'); const date = git('log', '-1', '--format=%cI'); -if (git('status', '--porcelain', '--', DRAFT, PRESENTATION, 'registries')) { +if (git('status', '--porcelain', '--', ...ALL, 'registries')) { console.error('sync-spec: the source checkout has uncommitted changes in the spec files; commit or stash them first.'); process.exit(2); } @@ -63,7 +67,7 @@ function stripAuthor(file) { .join('\n'); return front + draft.slice(end); } -const drafts = [DRAFT, PRESENTATION].map((f) => [f, stripAuthor(f)]); +const drafts = ALL.map((f) => [f, stripAuthor(f)]); rmSync(out, { recursive: true, force: true }); mkdirSync(join(out, 'registries'), { recursive: true }); @@ -72,16 +76,15 @@ for (const f of readdirSync(join(src, 'registries')).filter((f) => f.endsWith('. cpSync(join(src, 'registries', f), join(out, 'registries', f)); } -// Guard: no vendored file may contain an email address (the same pattern check-site uses). -const EMAIL = /[\w.+-]+@[\w-]+(?:\.[\w-]+)*\.[A-Za-z]{2,}\b/; +// Guard: no vendored file may contain an email address (the same check check-site uses; a URL's userinfo is not an address). const scan = (dir) => { for (const e of readdirSync(dir, { withFileTypes: true })) { const p = join(dir, e.name); if (e.isDirectory()) scan(p); else if (e.name.endsWith('.md')) { - const hit = readFileSync(p, 'utf8').match(EMAIL); + const hit = findEmail(readFileSync(p, 'utf8')); if (hit) { - console.error(`sync-spec: ${p} contains an email address ("${hit[0]}"); removed the output. Strip it at the source or extend the filter.`); + console.error(`sync-spec: ${p} contains an email address ("${hit}"); removed the output. Strip it at the source or extend the filter.`); rmSync(out, { recursive: true, force: true }); process.exit(1); } diff --git a/scripts/vendored.mjs b/scripts/vendored.mjs index 0d692b0..bd59559 100644 --- a/scripts/vendored.mjs +++ b/scripts/vendored.mjs @@ -30,9 +30,9 @@ export function* walk(dir) { // as Pagefind's, is not ours to remove). const TEXT = /\.(?:html|txt|xml|json|js|mjs|css|svg|md|webmanifest)$/; const CODE = /\.(?:js|mjs|css)$/; -// `scheme://user:password@host` is a URL's userinfo, such as a placeholder connection string, not -// an address. -const USERINFO = /[a-z][a-z0-9+.-]*:\/\/[^\s/@]*:$/i; +// `scheme://user@host` and `scheme://user:password@host` are a URL's userinfo, such as a +// placeholder connection string, not an address. +const USERINFO = /[a-z][a-z0-9+.-]*:\/\/(?:[^\s/@]*:)?$/i; /** The first email address in `s`, ignoring URL userinfo, or null. */ export const findEmail = (s) => { diff --git a/src/content/spec/draft-byrd-restact-connectors-00.md b/src/content/spec/draft-byrd-restact-connectors-00.md new file mode 100644 index 0000000..0397142 --- /dev/null +++ b/src/content/spec/draft-byrd-restact-connectors-00.md @@ -0,0 +1,726 @@ +--- +title: "REST:ACT Connectors" +abbrev: "REST:ACT Connectors" +docname: draft-byrd-restact-connectors-00 +category: exp +submissiontype: independent +ipr: trust200902 +area: "Applications" +keyword: + - REST + - WebAssembly + - capability security + - credentials + - language models +stand_alone: yes +pi: [toc, sortrefs, symrefs, comments] +author: + - + ins: N. Byrd +normative: + RESTACT: + title: "The REST:ACT Protocol: Invoking Sandboxed Functionality over REST" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-protocol-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-protocol-00.md + RESTACT-HTTP-VERBS: + title: "REST:ACT HTTP Verbs" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-http-verbs-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-http-verbs-00.md + RFC3986: + RFC8259: +informative: + RESTACT-DELEGATION: + title: "REST:ACT Identity and Delegation" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-delegation-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-delegation-00.md + RESTACT-OBJECTS: + title: "REST:ACT Objects and Data" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-objects-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-objects-00.md + RFC8126: + +--- abstract + +This document specifies an optional extension to REST:ACT, the protocol for invoking sandboxed +verbs over HTTP. It defines how a server uses a credential that belongs to one of its users on that +user's behalf without releasing it. A secrets mount passes a credential written to it to an +external secrets backend and never returns it. A mediated outbound call is one bounded HTTP request +that the server makes through an owner-governed connector object, placing a mounted credential +into the request as it sends it. Model completion lets a verb ask a language model for one bounded, +text-only completion through such a connector, metered against a budget that the connector's owner +sets. Webhook delivery lets a verb send one signed JSON `POST` to the destination such a connector +names. A server advertises each feature with its own token: `secrets-management`, `mediated-egress`, +`llm-connector` and `webhook-connector`. This document also creates the REST:ACT LLM Providers +registry. + +--- middle + +# Introduction {#connectors-introduction} + +An application often calls services outside the server for its users, with credentials that belong +to them: an API key for a model provider, or a token for a ticketing system. REST:ACT {{RESTACT}} +gives a verb no network access. A verb reaches an outside service only through a host interface +that names the operation (the "Capability Model" section of {{RESTACT}}). This document defines +four features for that, each optional and each advertised by its own feature token: + +* The mediated secrets mount ({{secrets-mount}}, `secrets-management`): object paths at which a + credential written by a client goes to an external secrets backend. The server stores only + metadata there, and no path on the server returns the value. +* The mediated outbound call ({{mediated-egress}}, `mediated-egress`): one bounded outbound HTTP + request that the server makes as the request's principal through a governed **connector** + object, placing a mounted credential into the request at the moment of sending. It belongs to + the server's embedding surface and defines no HTTP route. +* Model completion ({{llm}}, `llm-connector`): the `llm` capability interface, through which a verb + asks a language model for one bounded, text-only completion over a connector, billed to the + caller against a budget that the connector's owner controls. +* Webhook delivery ({{webhook}}, `webhook-connector`): the `webhook` capability interface, through + which a verb sends one signed JSON `POST` to the destination and path that a connector's owner + fixed, and learns only the status it was answered with. + +Each builds on the one before it. An outbound call places only credentials held in the mount, and +a model completion or a webhook delivery is made under the rules of the outbound call, through a +connector of kind `llm` or `webhook`. The tokens are still advertised separately; +{{llm-discovery}} and {{webhook-discovery}} say when a server advertises `llm-connector` and +`webhook-connector`. + +`llm` and `webhook` are typed interfaces: each names the one operation it performs, and the server, +not the verb, builds the request on the wire. No feature of this document gives a verb a request +whose method, target, header fields and content are all its own. An outside service that needs a +shape these interfaces do not offer is reached through a further typed interface under its own +feature token, or not from a verb. + +The decision records for this document are +[ADR-0087](https://github.com/stackumi/restactd/blob/main/spec/decisions/0087-secrets-backend-and-mediated-mount.md), +[ADR-0094](https://github.com/stackumi/restactd/blob/main/spec/decisions/0094-mediated-outbound-call.md) +and [ADR-0095](https://github.com/stackumi/restactd/blob/main/spec/decisions/0095-typed-connectors-llm.md) +in the reference implementation. + +## Relationship to REST:ACT {#connectors-relationship} + +This document is a REST:ACT extension, as described in the "Extension specifications" section of +{{RESTACT}}. The server requirements of each section bind only a server that advertises the token +that section names: `secrets-management` for {{secrets-mount}}, `mediated-egress` for +{{mediated-egress}}, `llm-connector` for {{llm}}, and `webhook-connector` for {{webhook}}. A requirement that also names a feature or +mechanism of another document, such as the refusal of a path-scoped sub-token, binds a server that +this document binds when that server also offers that feature or mechanism. A client does not assume any behavior of this document from a server +that does not advertise its token. + +A secrets mount serves a `PUT` on a mount path by passing its `value` member to a system outside +the server without storing it. That is extension point E7 of the "Extension specifications" +section of {{RESTACT}}, and the object's own policy still governs the `PUT`. + +{::boilerplate bcp14-tagged} + +# The mediated secrets mount (OPTIONAL, feature `secrets-management`) {#secrets-mount} + +An application often holds a credential belonging to a workspace owner — an API key, a token — that +must be governable, rotatable and auditable as a resource without ever being readable as data. A +server MAY designate an operator-configured **mount** (a route pattern over the object grammar, e.g. +`ws/{ws}/secrets/{name}`) at which object writes are natively **mediated**: a `PUT` carrying a +`value` member forwards that value to an external secrets backend and persists metadata only, and no +path on the server ever returns it. + +**The reference object.** An object under the mount is an ordinary governed object in every respect a +client can observe — it has a `$policy`, an `$owner`, lifecycle events, Problem Details — except that +two of its members are **reserved to the mediation**: `value` is write-only and never persisted or +returned, and `version` is mediation-owned and MUST be refused on any client write. A server MUST +refuse a non-JSON (binary) `PUT` on a mount path, since a content-addressed blob IS a persisted +value. A `GET` serves metadata only. A reference created this way MUST be born with an explicit +owner-only `$policy` established in its creating write, so it is never world-readable for an instant. + +**Failure.** When the backend cannot be reached, the server MUST refuse with `503` (`restact_code` +`unavailable`, which the "Errors" section of {{RESTACT}} registers) and MUST NOT fall back to +storing the value. + +**`null` members.** On a mount path the reserved members keep their rules: a server MUST refuse +`"value": null` with `400` (`invalid-input`), `version` stays refused on every client write, `null` +included, and a server MUST refuse a `PUT` that carries `value` together with a `null` member. On a +server that also advertises `put-null-removes`, a `"$policy": null` member on a mount path would +leave a reference without the policy it must carry, so the server refuses it with `422` +(`invalid-input`) instead of removing the policy. + +**Discovery.** A server supporting this profile MUST advertise `secrets-management`; absent it, a +client MUST NOT assume a mount exists, and MUST treat a `value` member as ordinary data. + +# The mediated outbound call (OPTIONAL, feature `mediated-egress`) {#mediated-egress} + +A credential held under the mount above is only useful if something can SPEND it. A server MAY +support performing one bounded outbound HTTP request **on the caller's behalf**, splicing the +owner's credential in server-side at the moment of sending — so the credential is used without ever +being released. This profile defines no HTTP route: it is a capability of the server's own embedding +surface, which an embedder exposes through a route of its own. Absent the feature token, a client +MUST NOT assume any such route behind it performs a credentialed call. + +**The connector.** The destination is named by an ordinary governed object — a **connector** — whose +server-read members are: `destination` (JSON `{"host", "port", "tls": "required"}`, where `host` is a +DNS name and MUST NOT be an address literal), optional `secretRefs` (JSON array of reference-object +paths), `splice` (required exactly when `secretRefs` is non-empty: JSON `{"headers": {…}, "body": +{…}}` whose values are owner-written templates), optional `pathPrefixes`, and optional `limits`. A +connector is a **capability**: holding `read` on one means the server will splice its owner's +credential on the reader's behalf. A server MUST therefore refuse a call through a connector that +does not carry its own `$policy` — an inherited one is never a use-grant — or whose `write` and +`delete` matcher lists are not each exactly `["owner"]`, since those members ARE the capability. A +server MAY additionally declare a prefix under which connectors are created and refuse a creating +write there that is not born so governed. + +On a server that also advertises `put-null-removes`, a `"$policy": null` member under a prefix where +the server requires a connector to be born governed would leave a connector without the policy it +must carry. The server refuses it in the same way as it refuses a creating write there that +carries no `$policy`. + +**Authorization.** The call executes as the principal the server's own identity chain resolved for +the inbound request; the embedder's handler MUST NOT be able to name a principal. An anonymous +principal and a path-scoped sub-token (the "Path-scoped sub-tokens (OPTIONAL, feature `path-scoped-tokens`)" section of {{RESTACT-DELEGATION}}) MUST both be refused. The use-grant +is `read` on the connector's own policy — evaluated by the server's one policy engine, with a +refusal indistinguishable from "no such connector" — and, for each spliced reference, `read` on that +reference as well. + +**Destination affinity.** A `${secret:}` placeholder is honored ONLY inside the connector's own +`splice` templates. It MUST name a reference the connector declares in `secretRefs`, that reference +MUST list the connector's own path in its `connectors` member (both sides, byte-for-byte), and the +reference MUST live under the secrets mount ({{secrets-mount}}). The caller's own headers, body and +request target are data: no placeholder in them is ever honored, and the literal `${secret:` +appearing in any of them MUST be refused rather than passed through. A caller header colliding with a +splice slot, an occupied body slot, and a non-JSON body when body slots are declared MUST each be +refused. Every declared reference resolves or the call is refused: there is never a partial send with +an empty credential. + +**Reach.** Destinations are bounded by operator configuration, never by the connector alone. A server +MUST resolve the declared name, verify EVERY resolved address against the ranges no such call may +reach (loopback, private, link-local, unique-local, multicast, unspecified, and cloud-metadata +addresses), refuse the call if ANY of them is blocked rather than choosing among them, and connect to +exactly one verified address without a second lookup. These checks bind the address the server +connects to. A server whose platform does not let it learn or choose that address, such as a +runtime whose `fetch` resolves the name itself and exposes no resolved address, MUST send every +such call through a forward proxy that applies the range check to the address it connects to and +refuses as this paragraph requires, or MUST NOT advertise `mediated-egress`, `llm-connector` or +`webhook-connector`. TLS MUST be used and verified against the +declared name — except a destination an operator has explicitly acknowledged as a deterministic test +harness, which a server MAY admit despite failing the range check above and MAY reach over plain +`http` instead of TLS; absent that explicit acknowledgement, such a destination MUST be refused. A +`3xx` response MUST be returned to the caller as a refusal and MUST NOT be followed: a redirect names +a destination the owner never declared. + +**Bounds.** Request and response bytes, header count and header bytes, and wall-clock time MUST be +bounded; a response cut at its bound MUST be reported as truncated rather than served as if complete; +returned response headers MUST be a fixed allowlist that excludes cookies and authorization echoes. + +**The invariant.** A server MUST NOT format a resolved value into any string it could return, log, +audit, or persist — the value MUST be carried as opaque bytes through substitution and never +concatenated into a request line, header name, path, or diagnostic message of its own. This +structural rule, not after-the-fact recognition, is what a response, log line, audit record, or +stored object being free of the value depends on. Servers SHOULD ALSO scrub responses for a resolved +value as a backstop against an upstream that echoes it back (an error page quoting a header it +received, a `Location` built from the request); this is advisory, not a MUST, because no fixed scrub +granularity or encoding list can catch every re-encoding an upstream might apply, and a value short +enough that scrubbing it would also redact ordinary text of the same length cannot be protected by a +scrub at all. A server SHOULD refuse to splice a value shorter than whatever floor its own scrub can +protect, rather than send one it could not recover if echoed. Every call, including every refusal, +SHOULD be audited by reference PATH — never by value, and never by value length. + +On a server that also advertises `llm-connector` or `webhook-connector`, a mediated call through a +typed connector, one whose `kind` is `llm` ({{llm}}) or `webhook` ({{webhook}}), is refused +(`connector-kind-mismatch`): a typed connector is reached only through its own interface. + +**Discovery.** A server supporting this profile MUST advertise `mediated-egress`. + +## Codes of the mediated call {#egress-codes} + +The codes that the refusals of {{mediated-egress}} carry, with the HTTP status class of each and the +feature tokens that cover it (the "Extension specifications" section of {{RESTACT}}), are below. +Each refuses a mediated call, except `connector-birth-ungoverned`, which refuses a creating write. A +code that `llm-connector` or `webhook-connector` also covers is one a refusal of `complete` ({{llm}}) or of `post` ({{webhook}}) can carry. A mediated +call through a typed connector carries `connector-kind-mismatch` ({{llm-discovery}}). Another +extension MAY carry `secret-not-bound`, `secret-not-mount`, `secret-denied` or `secret-too-short` +in a refusal of its own feature's use of a secret reference: that extension defines the refusal, +which names the same kind of fault as the code's row, and a feature token of that extension then +also covers the code and is listed in the row's Covered by cell. REST:ACT HTTP Verbs +{{RESTACT-HTTP-VERBS}} carries all four in its refusals of a deployment with webhook verification. + +| Code | Status | Covered by | Meaning | +|---|---|---|---| +| `egress-denied` | 403 | `mediated-egress`, `llm-connector`, `webhook-connector` | the principal may not use the connector: it is anonymous or holds a path-scoped sub-token, or it lacks `read` in the connector's own `$policy`. A connector that does not exist is refused the same way | +| `egress-connector-ungoverned` | 403 | `mediated-egress`, `llm-connector`, `webhook-connector` | the connector carries no `$policy` of its own, or its `write` or `delete` list is not exactly `["owner"]` | +| `egress-not-allowed` | 403 | `mediated-egress`, `llm-connector`, `webhook-connector` | the destination is outside what the operator's configuration admits, or the request path is outside the connector's `pathPrefixes` | +| `egress-blocked-address` | 403 | `mediated-egress`, `llm-connector`, `webhook-connector` | an address the destination's name resolves to is in a range no mediated call may reach | +| `egress-connector-invalid` | 422 | `mediated-egress`, `llm-connector`, `webhook-connector` | the call names a connector path that is not an object path, or a connector member is absent or malformed, such as an address-literal `host` or a `tls` other than `"required"` | +| `egress-bounds-exceeded` | 413 | `mediated-egress`, `llm-connector`, `webhook-connector` | the request is over a byte or header bound | +| `egress-redirect-refused` | 502 | `mediated-egress`, `llm-connector`, `webhook-connector` | the destination answered with a redirect (`3xx`), which the server does not follow | +| `egress-upstream-error` | 502 | `mediated-egress`, `llm-connector`, `webhook-connector` | the destination could not be reached: name resolution, connection or TLS failed, or the wall-clock bound ran out | +| `connector-birth-ungoverned` | 422 | `mediated-egress` | a write that creates an object under the prefix the server declares for connectors carries no `$policy` of its own, or one whose `write` or `delete` list is not exactly `["owner"]` | +| `splice-slot-conflict` | 422 | `mediated-egress` | a caller header collides with a splice slot, or the caller's body occupies a body slot | +| `splice-body-not-json` | 422 | `mediated-egress` | the connector declares body slots and the caller's body is not JSON | +| `placeholder-in-caller-data` | 403 | `mediated-egress` | the literal `${secret:` appears in the caller's headers, body or request target | +| `secret-not-declared` | 403 | `mediated-egress` | a placeholder names a reference that the connector does not declare in `secretRefs` | +| `secret-not-bound` | 403 | `mediated-egress`, `llm-connector`, `webhook-connector`, `webhook-verification` | the reference's `connectors` member does not list the connector, or, for webhook verification, its `verifiers` member does not list the route and its owner | +| `secret-not-mount` | 403 | `mediated-egress`, `llm-connector`, `webhook-connector`, `webhook-verification` | the reference is not under the secrets mount | +| `secret-denied` | 403 | `mediated-egress`, `llm-connector`, `webhook-connector`, `webhook-verification` | the principal may not read the reference; for webhook verification, the principal deploying the verb | +| `secret-too-short` | 403 | `mediated-egress`, `llm-connector`, `webhook-connector`, `webhook-verification` | a resolved value is shorter than the floor the server's scrub can protect, or, for webhook verification or webhook delivery, a key shorter than 16 bytes or, for delivery, one that does not decode | +| `secret-unresolvable` | 503 | `mediated-egress`, `llm-connector`, `webhook-connector` | a declared reference did not resolve | +| `secret-not-utf8` | 422 | `mediated-egress`, `llm-connector` | a resolved value is not UTF-8 text, so it cannot be placed into a header or a JSON string unchanged. It stays unusable until its owner rewrites it | + +# Model Completion (OPTIONAL, feature `llm-connector`) {#llm} + +A server MAY let a verb ask a language model for a completion through an `llm` capability interface +the verb imports. The verb never reaches the network. It names a governed **connector** object, and +the server makes the call itself under the rules of the mediated outbound call +({{mediated-egress}}), placing the connector owner's credential from the secrets mount +({{secrets-mount}}) into the request and returning a typed result. The verb sees no socket, no +request or response on the wire, and never the credential. The interface has one operation: + +* `complete(request) -> result` performs one bounded, non-streaming, + text-only completion. The request carries `connector` (the connector's object path), an optional + `system` prompt, `messages` (each a `role`, `user` or `assistant`, and a string `content`), and + an optional `model`, `max-output-tokens` and `temperature`. The completion carries the model's + `text`; a `stop-reason` normalized to `end`, `max-tokens`, `stop-sequence` or `other`; the `model` + the provider reports having used; and `usage`: input, output and cache-read token counts, an + optional `estimated-usd-micros`, and the `meter-tier` that produced them ({{llm-budget}}). + +Every refusal is an `invocation-error` carrying a stable code ({{llm-discovery}}), never a trap, so +a verb can degrade. + +The capability is gated the same way as composition and object-data access: a server links it only +for a component that imports it, a deployment MAY withhold it from a verb that declares it +(the "Verb declaration (deployment profile)" section of {{RESTACT}}), and it is attenuated down a composition tree, so a called verb never holds it when +its caller's frame does not (the "Composition" section of {{RESTACT}}). A call from a verb that does not hold it is refused +with `forbidden`. + +**Purity.** `complete` is effectful by construction: it spends money, its result is not +deterministic, and the prompt leaves the server for a third party. A `function` (the "Verb invocation (the bare verb)" section of {{RESTACT}}) MUST +NOT call it; a server refuses the call with `403` `forbidden-side-effect`. A server MUST also reject +at deployment, with `400` `forbidden-side-effect`, a `function` whose component imports `llm`, +wherever the verb's own imports are known to it. A source-language verb whose runner serves every +verb of its language (the "Verb code: source and executable" section of {{RESTACT}}) has no imports of its own, so for it the runtime refusal is the +only one. A completion that has been sent is an external effect outside the invocation's atomic +write set (the "Consistency" section of {{RESTACT}}): a later trap rolls back the verb's object writes but not the spend, +which the budget ledger records regardless. A connector's `purity` member (below) cannot make +`complete` safe. + +**The connector.** A connector used through `llm` is a connector of {{mediated-egress}}, under every +rule there for its own `$policy`, its owner-only `write` and `delete`, reach, TLS, redirects and +bounds, with these members in addition (string values, JSON-encoded where structured): + +* `kind` (required): `"llm"`. A call naming a connector of another kind is refused + (`connector-kind-mismatch`). +* `provider` (required): a registered, versioned identifier from the REST:ACT LLM Providers + registry ({{connectors-iana}}), such as `anthropic-messages/v1`. The registry row fixes the wire format, the + request path under the connector's `destination`, the request header that carries the + credential, and how the provider's usage and stop reason map onto `usage` and `stop-reason`. An + unregistered or unversioned value makes the connector invalid. A server MAY decline to implement + a registered provider, and then refuses a connector that names it (`llm-provider-unsupported`). +* `secretRefs` (required): exactly one reference, whose value the server places in the header the + provider's row names. A typed connector MUST NOT carry `splice`: the registry row fixes where the + credential goes, so there is no owner-written template and nothing a caller could collide with. +* `budget` (required): the path of a budget root ({{llm-budget}}) whose `state` object has the same + stored `$owner` as the connector, so that nobody bills a ceiling someone else owns. +* `models` (optional): `{"default": "", "allowed": ["", …]}`. A request naming a model + outside `allowed`, when `allowed` is present, is refused, and so is a request that names no model + to a connector with no `default` (`llm-model-not-allowed`). A request naming none otherwise uses + `default`. +* `pricing` (optional): `{"inputPerMTok", "outputPerMTok", "cacheReadPerMTok"}`, the owner's + statement of the provider's prices in US-dollar micros per million tokens, used to reconcile at + tier 2. +* `meterTier` (optional): `"0"`, `"1"` or `"2"` ({{llm-budget}}); absent is `"0"`. +* `estimateUsdMicrosPerCall` (required at tier 1 or 2): the conservative amount reserved per call. +* `purity` (optional): `"safe"` or `"effectful"`, absent meaning `"effectful"`. A server only ever + narrows with it: an operation the server knows to be effectful stays effectful whatever the member + says. It exists for later typed interfaces whose operations can be safe. + +**Authorization.** The server evaluates the use-grant for the principal the calling frame runs as +(the "Execution identity" section of {{RESTACT}}): `read` in the connector's own `$policy`, and `read` on the secret reference, +which MUST be mount-resident and MUST name the connector in its own `connectors` member +({{mediated-egress}}). An anonymous principal and a path-scoped sub-token +(the "Path-scoped sub-tokens (OPTIONAL, feature `path-scoped-tokens`)" section of {{RESTACT-DELEGATION}}) are refused. Under an authority switch the use-grant is evaluated for the +owner's frame while the spend is billed to the real caller ({{llm-budget}}), so a verb that runs as +its owner and imports `llm` spends its owner's connector for every principal its `execute` policy +admits. That policy, not the connector's `read` list, is then the effective spend policy, and an +owner SHOULD narrow it to the principals meant to use the credential. + +**Bounds.** A server MUST hold every call within these ceilings. A server MAY apply lower bounds +that a connector's `limits` ({{mediated-egress}}) names; nothing raises them. + +* At most 64 `messages`, and at most 64 KiB of serialized request (`llm-request-too-large`). +* `max-output-tokens` clamped to at most 4096, never raised; absent, the connector's or the + server's default applies. +* At most 4 calls per invocation tree, counted across the whole composition tree under its one + shared bound (the "Composition" section of {{RESTACT}}), every attempt included (`llm-calls-exceeded`). The cap is fixed, + not configurable, so no configuration turns a bounded tree into an agent loop. +* The wall-clock bound of a mediated call ({{mediated-egress}}). The call also counts against + the server's limit on mediated calls in flight. + +Text is the only content. Images, documents, tool definitions and tool results, structured-output +schemas, streaming, and multi-turn continuation handles are not part of `complete`; each would be a +new method or a new interface (the "The guest contract (WIT)" section of {{RESTACT}}), never an overload of this one. + +**Output.** The completion `text` is opaque, untrusted data to the verb and to everything +downstream. The server never interprets, parses or executes it, and a verb that renders it does so +under the same rules as any other string. Text a verb stores carries no mark of where it came from, +so an application that needs to tell model output apart keeps that record itself. An error answered +by the provider is returned as `llm-upstream-error`, carrying the provider's status +and a bounded excerpt scrubbed as {{mediated-egress}} recommends. + +**Execution locus.** A credentialed call runs only in the server process. A server that runs a +verb's frame in a separate worker process (the "Security Considerations" section of {{RESTACT}}) MUST NOT resolve a secret value in that +worker. It refuses `complete` there with `typed-call-unavailable-under-isolation` before any policy +read, budget reservation or network I/O, rather than handing the credential to a weaker locus. + +## The budget {#llm-budget} + +Every `llm` connector names a budget, and the server meters every call against it. A budget is two +kinds of ordinary governed object under a root path ``: `/state`, the aggregate, and +`/ledger/`, one row per charge. An application that also spends on the owner's behalf +(its own model calls, for example) keeps its spend in the same budget, so one ceiling covers both. + +The owner creates `/state`; the server never does, and refuses a call whose budget state is +absent (`budget-unconfigured`). `/state` MUST carry its own `$policy` whose `write` and `delete` +lists are exactly `["owner"]`; otherwise the server refuses to use it (`budget-ungoverned`), since a +principal able to write it could raise the ceiling. The calling principal needs no authority over +the budget: its authority is `read` on the connector. + +**Metering tiers.** The connector's `meterTier` decides how a call is costed. + +| Tier | Source of the figure | What it bounds | +|---|---|---| +| `0` | what the server observes: calls, bytes, wall time | Safety: the call ceiling and the principal's quota. Needs nothing from the provider and records no dollar figure. | +| `1` | the connector's `estimateUsdMicrosPerCall` | A spending cap applied before dispatch: each call reserves the estimate and settles at it. | +| `2` | the provider's reported token usage times the connector's `pricing` | Accuracy: the reconciled figure, rounded up to the micro, replaces the estimate. | + +Bounds never depend on the provider's cooperation; only accuracy does. Every dollar figure a server +records is an estimate built from the provider's reported usage and the owner's stated prices, and +is marked as one; the server never knows what is really billed. At tiers 1 and 2 a server MUST +reserve before it sends and reconcile afterwards: the estimate is debited before the request leaves +and the real figure replaces it after, so the next call is gated on what was spent, and a crash in +between leaves a conservative reservation rather than an unrecorded spend. + +**`/state`.** Members the owner decides on are top-level, written only by the owner through the +data plane, and never written by the server: + +| Member | Meaning | +|---|---| +| `ceilingUsdMicros` | The period's ceiling for the whole root. | +| `ceilingCalls` | The period's call ceiling, which also bounds a tier-0 connector. | +| `periodSeconds` | The period length. | +| `subCeilings` | JSON `{"": {"ceilingUsdMicros": ""}, …}`. A principal absent from it is bounded by the root ceiling only. | +| `totals` | The accrual envelope below, and the only member the server writes. | + +Members that change when money is spent live inside `totals`, one JSON-encoded property, because a +compare-and-swap of a single property (`set-at-if`, the "Object Data Access" section of {{RESTACT-OBJECTS}}, or a conditional `PUT`) is the +only atomic write available to an application sharing the budget. Values are decimal-integer +strings unless noted. + +| Sub-member | Meaning | +|---|---| +| `periodStart` | The start of the current period, in epoch milliseconds. | +| `spentUsdMicros`, `calls` | The period's running totals. | +| `reservedUsdMicros` | Open reservations. Written by the server only. | +| `lastPeriodSpentUsdMicros` | The previous period's spend. | +| `bySubject` | An object `{"": {"spentUsdMicros", "reservedUsdMicros", "calls"}}`, an entry created at zero when first touched. Only the server writes `reservedUsdMicros`. | +| `nextLedgerSeq` | The key of the next ledger row, taken and incremented in the same write. | +| `openReservations`, `foldedReservations` | The server's record of reservations in flight and of expired ones (below). Written by the server only. | + +A server refuses a `state` whose `totals` is absent, is not a JSON object, or lacks a usable +`periodStart` or `nextLedgerSeq`, and one that carries `periodStart`, `spentUsdMicros`, `calls` or +`bySubject` at the top level instead of inside `totals` (`budget-unconfigured`). It never defaults +`periodStart` or `nextLedgerSeq`: a default would invent a period or renumber a ledger. + +**Every writer carries through what it does not own.** A writer that rewrites `totals` MUST read +it, change only the sub-members it is entitled to, and write back every other sub-member, and +every other key inside a `bySubject` entry, unchanged. A writer that rebuilt the envelope from a +fixed list of keys would erase the other writer's members: an application that erased a server +reservation would over-admit, and a server that erased an application's member would lose its data. +A writer admitting its own spend MUST compare the ceiling against `spentUsdMicros + +reservedUsdMicros` plus the new charge, never against `spentUsdMicros` alone. Inside `totals` the +server writes only the sub-members above; outside it, only ledger rows. + +**Write authority.** The server's budget writes pass through the same policy gate as any data-plane +write, evaluated as the stored `$owner` of `/state`, and each is one conditional write of +`totals` (`If-Match` on the representation just read, the "Consistency" section of {{RESTACT}}) retried from a fresh +read on `412`. An application writes as the owner in the same way, so the two writers are +serialized by the ordinary conditional-write mechanism. + +**Reserve.** Before any I/O the server reads `state`, settles expired reservations and rolls the +period over if it has ended (below). It then refuses `budget-exhausted`, naming the ceiling that +bound, when `calls + 1` exceeds `ceilingCalls`; or, at tier 1 or 2, when `spentUsdMicros + +reservedUsdMicros` plus the estimate exceeds `ceilingUsdMicros`; or, where `subCeilings` names the +billed principal, when that principal's own spent and reserved figures plus the estimate exceed +its ceiling. Otherwise, in one conditional write, it adds the estimate to `reservedUsdMicros`, +increments `calls` (and both for the principal in `bySubject`), takes `nextLedgerSeq` as the row key +and increments it, and records the reservation; then it creates the ledger row. A row the policy +gate refuses is `budget-ungoverned`, and the server releases the reservation before refusing. + +**Reconcile, release and expiry.** After the call the server replaces the reservation with the +actual figure: at tier 2 the reported usage times `pricing`; at tier 1, or at tier 2 when the +response has no usage, the estimate; at tier 0, zero. A call that failed after the request was sent +and reported no usage settles at the estimate, never at zero. A failure after the reservation but +before any byte is sent is released instead: the row is written terminal with no spend, and the +reservation and its count in `calls` are removed. A reservation still open three times the +mediated-call wall-clock bound after it was made is presumed lost to a crash and is folded into +`spentUsdMicros` at its estimate; a reconcile that arrives later corrects that figure once. A ledger +row becomes terminal at most once and is never rewritten afterwards. + +**Rows.** Every row carries `kind`, `principal` (the billed subject), `usdMicros`, `calls`, +`estimate` (whether the figure is an estimate), `reservedAt` (epoch milliseconds) and optionally +`connector`. A row the server writes has `kind` `"verb-llm"` and also carries `verb`, `meterTier` +and, at tier 2, the token counts. A row is created with the `$owner` of `/state` and an explicit +`$policy` whose `read` list is that of `state` at the time and whose `write` and `delete` lists are +`["owner"]`: whoever may read the aggregate may read its rows, and only the owner edits history. A +server places no meaning on a `kind` it did not write. No row carries the prompt or the completion. + +**Rollover.** The server, on every reserve, and an application, on each of its own writes to +`totals`, that finds `now ≥ periodStart + periodSeconds × 1000` MUST, in the same write and before +its own changes, set `lastPeriodSpentUsdMicros` to `spentUsdMicros`; set `spentUsdMicros`, `calls`, +and each `bySubject` entry's `spentUsdMicros` and `calls` to zero; and set `periodStart` to the +start of the period that contains `now` on the owner's grid, +`periodStart + ⌊(now − periodStart) / (periodSeconds × 1000)⌋ × periodSeconds × 1000`, not to `now` +itself, which would lengthen every quiet period by the gap. Reservations, `nextLedgerSeq` and the +server's reservation records carry over. Rollover happens lazily, on the first of those writes that +finds the period over, needs no timer, and is idempotent. + +**Billing.** The billed principal is always the real caller, also under an authority switch +(the "Execution identity" section of {{RESTACT}}): a row's `principal` and the sub-ceiling consulted are the caller's, as for +quota. + +**Out of scope.** A server does not create `state`, prune the ledger (deleting rows is the owner's +business), reconcile rows it did not write, convert currencies, know real prices, or enforce one +ceiling across several budget roots. + +## Codes and discovery {#llm-discovery} + +The codes a refusal of `complete` carries, with the HTTP status class of each, are: + +| Code | Status | Meaning | +|---|---|---| +| `forbidden` | 403 | the verb does not hold the capability of the interface it called, `llm` or `webhook` ({{webhook}}) | +| `forbidden-side-effect` | 403 | a `function` called `complete` or `post` | +| `connector-kind-mismatch` | 422 | the connector's `kind` does not fit the call: a `complete` through a connector whose `kind` is not `llm`, a `post` through one whose `kind` is not `webhook` ({{webhook}}), or a mediated call through a typed connector ({{mediated-egress}}) | +| `llm-provider-unsupported` | 422 | the connector names a registered provider the server does not implement | +| `llm-model-not-allowed` | 403 | the model is outside `models.allowed`, or none was named and the connector has no default | +| `llm-request-too-large` | 413 | too many messages, or too many request bytes | +| `llm-calls-exceeded` | 429 | the invocation tree has used its calls | +| `budget-unconfigured` | 422 | the connector has no budget, or its `state` is absent, malformed or owned by someone else | +| `budget-ungoverned` | 403 | the budget's `state` is writable by someone other than its owner, or its ledger refuses the owner's row | +| `budget-exhausted` | 429 | a root or per-principal ceiling would be exceeded; the detail names which. Transient: the caller backs off, and the server does not retry | +| `typed-call-unavailable-under-isolation` | 501 | the server runs the frame where no secret may be resolved, a fixed property of its configuration | +| `llm-upstream-error` | 502 | the provider answered with an error | + +A refusal under a rule this section takes from {{mediated-egress}} (authorization, destination +affinity, reach, or bounds) carries that rule's code from the table of {{egress-codes}}. + +A server SHOULD audit every call as {{mediated-egress}} describes, adding the connector's kind and +provider, the model, the metering tier, the token counts, and the reconciled figure with its +estimate flag. Neither an audit record nor a ledger row ever carries the prompt or the completion: +they record that a call happened and what it cost. + +**The interface.** The `llm` interface of the WIT package `rest-act:plugin` has one function, +`complete(completion-request) -> result` (feature `llm-connector`, +gated): one bounded, text-only model completion through a connector object. The "Guest Contract +(WIT package `rest-act:plugin`)" section of {{RESTACT}} lists it with the package's other +interfaces. + +**Discovery.** A server that implements the `llm` interface and can place a mediated credential (a +secrets mount in service and a destination allowlist configured, {{mediated-egress}}) MUST advertise +`llm-connector`. The token is independent of `mediated-egress`: a server can offer the mediated call +without linking `llm`, and a server that links `llm` advertises its token whether or not it offers +the mediated call to embedders. A server that refuses `complete` in worker processes still +advertises it, since the interface links; the refusal is per call. A component that imports `llm` on +a server without the token is refused at upload (the "The guest contract (WIT)" section of {{RESTACT}}). A verb that holds the capability +reports `networkAccess` `"outbound"` in its descriptor (the "Discovery" section of {{RESTACT}}), which here means outbound +calls the server itself makes through connector objects, never a socket the verb holds, and lists +`rest-act:plugin/llm` among its `interfaces`. Its reported `world` MAY be the one it would target +without `llm`. + +# Webhook Delivery (OPTIONAL, feature `webhook-connector`) {#webhook} + +A server MAY let a verb send a signed webhook through a `webhook` capability interface the verb +imports. As with {{llm}}, the verb never reaches the network. It names a governed connector object, +and the server builds the request, signs it with the connector owner's key from the secrets mount +({{secrets-mount}}), and sends it under the rules of the mediated outbound call +({{mediated-egress}}). The interface has one operation: + +* `post(request) -> result` sends one `POST` with JSON content to the + connector's destination. The request carries `connector` (the connector's object path), `body` + (a string holding the JSON text {{RFC8259}} to send) and an optional `id`. The delivery carries + `status`, the HTTP status code the destination answered with, and the `id` the server sent. + +The verb chooses only the content and, optionally, the message identifier. The method, the +destination, the request target, the content type and every header field are fixed by this section +and by the connector's owner. Every refusal is an `invocation-error` carrying a stable code +({{webhook-discovery}}), never a trap. + +The capability is gated as `llm` is ({{llm}}): a server links it only for a component that imports +it, a deployment MAY withhold it from a verb that declares it with the grant flag `webhook=deny` +(the "Verb declaration (deployment profile)" section of {{RESTACT}}), and it is attenuated down a +composition tree. A call from a verb that does not hold it is refused with `forbidden`. + +**Purity.** `post` is effectful. A `function` MUST NOT call it; a server refuses the call with `403` +`forbidden-side-effect`, and MUST reject at deployment, with `400` `forbidden-side-effect`, a +`function` whose component imports `webhook`, wherever the verb's own imports are known to it. A +delivery that has been sent is an external effect outside the invocation's atomic write set (the +"Consistency" section of {{RESTACT}}): a later trap rolls back the verb's object writes but not the +delivery. A server sends each `post` at most once and never retries it. A refusal does not carry an +identifier the server made, so a verb that may retry a `post` passes its own `id`, the same one on +every attempt, and a receiver can then drop the duplicate. + +**The connector.** A connector used through `webhook` is a connector of {{mediated-egress}}, under +every rule there for its own `$policy`, its owner-only `write` and `delete`, reach, TLS, redirects +and bounds, with these members in addition (string values): + +* `kind` (required): `"webhook"`. A call naming a connector of another kind is refused + (`connector-kind-mismatch`). +* `path` (required): the request target, which matches `path-absolute` of {{RFC3986}}, optionally + followed by `?` and a query, holds no space or control character, and is at most 2048 bytes. +* `signing` (required): `"standard-webhooks"`, the only value of this version. The server signs as + the `standard-webhooks` scheme of {{RESTACT-HTTP-VERBS}} verifies. +* `secretRefs` (required): exactly one reference, whose value is the signing key in the form that + scheme reads. A key that does not decode, or decodes to fewer than 16 bytes, is refused + (`secret-too-short`), and a server MUST NOT refuse a longer key for its length, so a key that + verifies under {{RESTACT-HTTP-VERBS}} signs on every server. The key is never placed in the + request, so the scrub floor of {{mediated-egress}} does not apply to it. + +A webhook connector MUST NOT carry `splice` or `pathPrefixes`: the connector's `path` and this +section fix the whole request, so there is no owner-written template and nothing a caller could +collide with. A connector that breaks a rule of this list is refused (`egress-connector-invalid`). + +**The request.** The server sends `POST` to the connector's `destination` at its `path`, with these +header fields and no others, apart from `Host`, a `User-Agent` of the server's choosing, and the +fields that framing the content needs: + +* `Content-Type: application/json`; +* `webhook-id`: the request's `id` or, when it has none, an identifier of that form the server + makes with at least 128 bits from a cryptographically secure random source. An `id` is 1 to 64 characters, + each an ASCII letter, a digit, `_` or `-`; any other `id` is refused (`invalid-input`); +* `webhook-timestamp`: the server's clock when it signs, as that scheme writes a timestamp; +* `webhook-signature`: `v1,` and the signature over the `webhook-id`, `.`, the timestamp, `.`, and + the content, as that scheme computes it. + +The content is the UTF-8 encoding of the request's `body`, unchanged. The server MUST refuse a `body` that is +not JSON text (`webhook-body-invalid`) or is larger than 64 KiB (`egress-bounds-exceeded`), before +it resolves the key. + +**The answer.** The verb learns only the status. Every status, a `3xx`, `4xx` or `5xx` included, is +a delivery and returns `status`, since the destination has received the request by then. A server +never follows a `3xx`; unlike the mediated call, it does not report one as a refusal. The +server reads the destination's response content only within the bounds of {{mediated-egress}} and +returns none of it, or any response header field, to the verb, so the interface carries data out and +brings back nothing an outside service chose beyond a status code. + +**Authorization.** The server evaluates the use-grant for the principal the calling frame runs as, +as {{llm}} does: `read` in the connector's own `$policy`, and `read` on the secret reference, which +MUST be mount-resident and MUST name the connector in its own `connectors` member +({{mediated-egress}}). An anonymous principal and a path-scoped sub-token are refused. A verb that +runs as its owner and imports `webhook` sends through its owner's connector for every principal its +`execute` policy admits; that policy is then the effective policy for who may cause a delivery, and +an owner SHOULD narrow it. + +**Bounds.** At most 8 calls of `post` per invocation tree, counted across the whole composition tree +under its one shared bound (the "Composition" section of {{RESTACT}}), every attempt included +(`webhook-calls-exceeded`). Each call is a mediated call for the wall-clock bound and the limit on +mediated calls in flight ({{mediated-egress}}). A server MAY apply lower bounds that a connector's +`limits` names; nothing raises them. + +**Execution locus.** As for `complete` ({{llm}}), a server MUST NOT resolve the signing key in a +worker process that runs a verb's frame. It refuses `post` there with +`typed-call-unavailable-under-isolation` before any policy read or network I/O. + +## Codes and discovery {#webhook-discovery} + +The codes a refusal of `post` carries, beyond those {{llm-discovery}} defines and uses alike +(`forbidden`, `forbidden-side-effect`, `connector-kind-mismatch` and +`typed-call-unavailable-under-isolation`), are: + +| Code | Status | Meaning | +|---|---|---| +| `webhook-body-invalid` | 422 | the `body` is not JSON text | +| `webhook-calls-exceeded` | 429 | the invocation tree has used its calls | + +A refusal under a rule this section takes from {{mediated-egress}} (authorization, destination +affinity, reach, or bounds) carries that rule's code from the table of {{egress-codes}}. A +destination that could not be reached is `egress-upstream-error`. + +A server SHOULD audit every call as {{mediated-egress}} describes, adding the connector's kind, the +`webhook-id` and the status. No audit record carries the content. + +**The interface.** The `webhook` interface of the WIT package `rest-act:plugin` has one function, +`post(webhook-request) -> result` (feature `webhook-connector`, +gated). The "Guest Contract (WIT package `rest-act:plugin`)" section of {{RESTACT}} lists it with +the package's other interfaces. + +**Discovery.** A server that implements the `webhook` interface and can place a mediated credential +MUST advertise `webhook-connector`, independently of `mediated-egress` and `llm-connector`. A +server that refuses `post` in worker processes still advertises it, since the interface links. A +component that imports `webhook` on a server without the token is refused at upload (the "The guest +contract (WIT)" section of {{RESTACT}}). A verb that holds the capability reports `networkAccess` +`"outbound"` in its descriptor, as {{llm-discovery}} describes, and lists `rest-act:plugin/webhook` +among its `interfaces`. + +# Security Considerations {#connectors-security} + +The requirements that keep a credential from leaking are in the sections that define each feature. +This section adds no requirement. It lists them by the party they constrain: the verb, the caller, +and the owner of a connector or a mount. + +* A verb never holds a socket or a credential value. It can ask for a completion only through a + connector whose use-grant its frame's principal holds, within the call cap of its invocation tree + and the ceilings of the connector's budget, and the text it gets back is untrusted data ({{llm}}, + {{llm-budget}}). A verb that runs as its owner spends the owner's connector for every principal + its `execute` policy admits, so that policy is then the effective spend policy ({{llm}}). It + can send a webhook only as JSON content to a destination and path that a connector's owner fixed, + signed with a key it never sees, and learns only the status ({{webhook}}). The content is + whatever the verb chose, so a verb that may read data can send it to that destination: holding + `read` on a webhook connector is a grant to send data there. +* A caller's headers, body and request target are data. A `${secret:` placeholder is honored only + in the connector owner's `splice` templates, a reference is used only when it lists the connector + back, and the server connects only to a destination that the operator's configuration + admits, at an address that passes the range check unless the operator has explicitly acknowledged + that destination as a deterministic test harness, without following a redirect ({{mediated-egress}}). Holding `read` on a connector lets a caller have the server splice the + owner's credential into a call; it never lets the caller see the credential. +* A value written to a mount path goes to the secrets backend and is never persisted or returned + ({{secrets-mount}}). The server refuses a call through a connector whose own `$policy` does not + limit `write` and `delete` to its owner, and refuses to use a budget `state` whose own `$policy` + does not, since those objects decide where a credential goes and how much may be spent + ({{mediated-egress}}, {{llm-budget}}). + +The security considerations of {{RESTACT}} apply. + +# IANA Considerations {#connectors-iana} + +This document requests the following registrations in registries that {{RESTACT}} creates, and one +new registry. + +* In the "REST:ACT Feature Tokens" registry: `secrets-management` ({{secrets-mount}}), + `mediated-egress` ({{mediated-egress}}), `llm-connector` ({{llm}}) and `webhook-connector` + ({{webhook}}). +* In the "REST:ACT Error Codes" registry: the codes in the tables of {{egress-codes}}, + {{llm-discovery}} and {{webhook-discovery}}, except `forbidden` and `forbidden-side-effect`, + which {{RESTACT}} registers. +* In the "REST:ACT Capability Interfaces" registry: `rest-act:plugin/llm` ({{llm}}) and + `rest-act:plugin/webhook` ({{webhook}}). +* A **"REST:ACT LLM Providers"** registry of the versioned wire-protocol identifiers an `llm` + connector names in `provider` ({{llm}}), registration policy Specification Required {{RFC8126}}; + initial entry `anthropic-messages/v1`, in `registries/llm-providers.md`. A row pins the provider's + wire format at a fixed API version, so a changed format is a new identifier, never an edit to a + registered one. diff --git a/src/content/spec/draft-byrd-restact-delegation-00.md b/src/content/spec/draft-byrd-restact-delegation-00.md new file mode 100644 index 0000000..c6640b3 --- /dev/null +++ b/src/content/spec/draft-byrd-restact-delegation-00.md @@ -0,0 +1,693 @@ +--- +title: "REST:ACT Identity and Delegation" +abbrev: "REST:ACT Delegation" +docname: draft-byrd-restact-delegation-00 +category: exp +submissiontype: independent +ipr: trust200902 +area: "Applications" +keyword: + - REST + - WebAssembly + - custom methods + - capability security +stand_alone: yes +pi: [toc, sortrefs, symrefs, comments] +author: + - + ins: N. Byrd +normative: + RFC7636: + RFC8693: + RESTACT: + title: "The REST:ACT Protocol: Invoking Sandboxed Functionality over REST" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-protocol-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-protocol-00.md +informative: + RFC8252: + RFC9700: + HTMLIFRAME: + title: "HTML: the iframe element (WHATWG Living Standard)" + target: https://html.spec.whatwg.org/multipage/iframe-embed-object.html#the-iframe-element + RESTACT-CONNECTORS: + title: "REST:ACT Connectors" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-connectors-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-connectors-00.md + RESTACT-EVENTS: + title: "REST:ACT Events" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-events-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-events-00.md + RESTACT-MCP: + title: "REST:ACT Model Context Protocol Facet" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-mcp-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-mcp-00.md + RESTACT-OBJECTS: + title: "REST:ACT Objects and Data" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-objects-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-objects-00.md + +--- abstract + +This document specifies an optional extension to REST:ACT, the protocol for invoking sandboxed +verbs over HTTP. It defines credentials and acts that change whose authority a request carries: an +operator act that reassigns ownership, read-only sub-tokens confined to one object-path prefix, and +grants under which one principal acts for another within bounds, with both identities visible. It +also defines how a verb reads the delegation actor and how a client reads who created and last +changed an object. A server advertises each feature with its own token. + +--- middle + +# Introduction {#delegation-introduction} + +In REST:ACT {{RESTACT}} a request carries its principal's whole authority, and a resource's owner +never changes. This document defines optional features, each under its own feature token, that +change one of those facts or record who acted: + +* an operator act that reassigns the owner of resources a former owner can no longer manage + ({{admin-reown}}); +* path-scoped sub-tokens, read-only credentials confined to one object-path prefix + ({{path-scoped-tokens}}); +* delegated tokens, with which an actor acts for a subject within the bounds of a grant the subject + made, together with the delegation actor in the `identity` interface ({{delegated-tokens}}); +* client actors, programs with no principal of their own that a grant names as its actor + ({{client-actors}}); +* the provenance facet, which says who created and last changed an object ({{provenance-facet}}). + +The decision records for this document are +[ADR-0092](https://github.com/stackumi/restactd/blob/main/spec/decisions/0092-path-scoped-sub-tokens.md), +[ADR-0109](https://github.com/stackumi/restactd/blob/main/spec/decisions/0109-delegated-tokens.md), +[ADR-0111](https://github.com/stackumi/restactd/blob/main/spec/decisions/0111-ownership-is-fixed-admin-reown.md) +and [ADR-0131](https://github.com/stackumi/restactd/blob/main/spec/decisions/0131-offline-reown.md) +in the reference implementation. + +## Relationship to REST:ACT {#delegation-relationship} + +This document is a REST:ACT extension, as described in the "Extension specifications" section of +{{RESTACT}}. That section says whom this document binds: a server that offers a mechanism one of +these feature tokens covers advertises the token and is bound by what this document requires of +that mechanism. The tokens are `admin-reown`, `path-scoped-tokens`, `delegated-tokens`, +`delegated-client-actors`, `identity-actor` and `object-provenance`. The token +`delegated-prefixes` is registered and reserved for a later amendment ({{delegation-iana}}); no +server advertises it yet. + +| Feature token | Section | +|---|---| +| `admin-reown` | {{admin-reown}} | +| `path-scoped-tokens` | {{path-scoped-tokens}} | +| `delegated-tokens` | {{delegated-tokens}} | +| `identity-actor` | {{delegated-tokens}} (the delegation actor in the `identity` interface) | +| `delegated-client-actors` | {{client-actors}} | +| `object-provenance` | {{provenance-facet}} | +| `delegated-prefixes` | none: reserved for a later amendment | + +That section makes one exception for this document: the rules of {{delegated-tokens}} for a server +that implements delegated tokens but does not advertise `delegated-tokens`, because it cannot sign or +because its operator has switched delegation off, bind that server too. A server +that implements none of this document is still bound by the core's reservation of the paths +`tokens/sub`, and of `tokens/grants` and `tokens/exchange` and everything beneath each, under +`/v1/`, and of the `aud` value `restact-delegated`. + +Path-scoped sub-tokens, delegated tokens and client actors are bearer credentials or are carried +on them. A server that accepts no bearer credential, for instance one that establishes principals +only through the authentication of an application it is mounted in or a trusted proxy's header +field (the "Authentication" section of {{RESTACT}}), does not offer them and does not advertise +`path-scoped-tokens`, `delegated-tokens`, `identity-actor` or `delegated-client-actors`. + +This document uses three of the extension points that section names. E1 is the operator act of +{{admin-reown}}, and E4 is that act's withdrawal of a runs-as-owner opt-in. E9 covers the delegation +actor that the `identity` interface exposes ({{delegated-tokens}}). The bounds of a sub-token and of +a delegated token need no extension point: they only narrow what a credential may do, as that +section lets any extension do. Their refusals take precedence over the answer the core gives a +caller who may not read (the "Refusing a caller who may not read" section of {{RESTACT}}). + +A requirement that also names a feature or mechanism of another document, such as a lifecycle +hook, a schedule, a secrets mount or deployment history, binds a server that this document binds +when that server also offers that feature or mechanism. A server that offers a feature with a token advertises the token, and a +requirement on a mechanism no token covers, such as a lifecycle hook outside the data-plane CRUD +subset, binds every server that offers the mechanism (the "Extension specifications" section of +{{RESTACT}}). A client does not assume any behavior of this document from a server that does not +advertise its token. + +{::boilerplate bcp14-tagged} + +# Operator ownership recovery (OPTIONAL, feature `admin-reown`) {#admin-reown} + +A server MAY let a configured operator reassign ownership. It advertises the `admin-reown` feature +token when the act is available. The act belongs to the operator, not to the product's users. A +server that offers it: + +* MUST admit it only for operator subjects named in server configuration: never through a role, + group, scope, claim, `public`, or `owner` matcher, and never for the anonymous identity or a + path-scoped sub-token ({{path-scoped-tokens}}). A delegated request is refused as on every + administrative route ({{delegated-tokens}}); +* MUST answer as if the act did not exist when it is not configured; +* MUST name, in each act, a current owner `from`, a new owner `to`, and an object path. It MUST move + only resources that path names, and only those `from` currently owns: the object at the path and + the verbs defined on it, plus everything beneath the path when the act asks for its subtree; +* MUST refuse with `400` (`invalid-input`) a `to` that equals `from`, that is the anonymous + identity, or, on a server advertising `delegated-client-actors`, that begins `client:` + ({{client-actors}}); +* MUST, in the same write that changes a verb's owner, turn off its runs-as-owner opt-in + (the "Execution identity" section of {{RESTACT}}) and any other owner-made grant of authority or visibility the verb carries, + and MUST pause the verb if it is a lifecycle hook. Nothing then runs with the new owner's + authority until the new owner opts in with their own credential; +* MUST NOT move registrations (schedules and subscriptions, the "Events, Triggers, and Scheduling" section of {{RESTACT-EVENTS}}), which run under their + registrant's authority; MUST NOT fire lifecycle hooks or publish events for the change of owner + itself; and SHOULD NOT move a slot of a secrets mount (the "The mediated secrets mount (OPTIONAL, feature `secrets-management`)" section of {{RESTACT-CONNECTORS}}), whose credential the + old owner supplied. + +**A paused hook** is not invoked when its event occurs; the server records the skip in its operator +log, and it does not resolve past the paused hook to an ancestor's. Every other invocation of the +verb (a direct call, a schedule or subscription that targets it, a composition) is unaffected, +because none of them runs under the owner's authority. While the hook is paused, its `meta` +(the "Verb properties (the program itself)" section of {{RESTACT}}) carries `paused: true`; the +member is absent otherwise. Only its owner replacing its code resumes it: `PUT …:verb/code`, a rollback +(the "Deployment history and rollback (OPTIONAL, feature `verb-history`)" section of {{RESTACT-OBJECTS}}), or a re-registration (the "Verb declaration (deployment profile)" section of {{RESTACT}}). A `policy` or other property write +leaves it paused. A runs-as-owner opt-in is restored only the way it was first made, by the owner +at deploy. + +The reference host's wire form follows. A server MAY offer the act through another operator +interface with the same semantics. + +~~~ +POST /admin/reown Content-Type: application/json +{"from": "", "to": "", "path": "", + "subtree": false, "dryRun": false} +→ 200 {"from", "to", "path", "subtree", "dryRun", + "verbs": [{"route", "runsAsCleared", "invokerCleared", + "paused"}], + "objects": , "skipped": {"secretSlots": }} +~~~ + +`dryRun` reports what the act would move and changes nothing. `skipped.secretSlots` counts the +slots of a secrets mount that the act left with their old owner. Each resource moves atomically; the +act as a whole need not. Because it selects only what `from` still owns, repeating an act completes +a partial one. + +**Pairwise subjects.** A verb's frames read pairwise subjects computed for its owner (the "Caller +Identity" section of {{RESTACT}}). Reassigning the verb changes them, and data the verb keyed by the +earlier ones no longer matches any caller. + +# Path-scoped sub-tokens (OPTIONAL, feature `path-scoped-tokens`) {#path-scoped-tokens} + +Every bearer credential defined so far carries its principal's COMPLETE authority. A server MAY +additionally support minting a deliberately attenuated sub-credential: confined to one object-path +prefix, read-only, and short-lived. This is a NARROWING primitive — a sub-token MUST NOT confer any +right its minting principal does not already hold (the "Authorization and Identity" section of {{RESTACT}}) — suited to delegating a minimal, +temporary, read-only view of a subtree to an untrusted or semi-trusted context: a sandboxed +{{HTMLIFRAME}}-style opaque-origin frame, a short-lived share link's fetcher, or an embedded widget. + +**Minting.** A server supporting this profile MUST expose `POST /v1/tokens/sub`, taking a JSON body +`{"prefix": "", "ttl_seconds": }` and returning, on success, +`200` with `{"token": "", "expires_at": , "prefix": "", "read_only": +true}`. The endpoint MUST refuse an unauthenticated (anonymous) caller with `401`, unconditionally — +even though the anonymous principal's own read rights would still be an upper bound on what could be +minted, minting is refused outright, since an anonymous mint surface would collapse any per-principal +rate limit into one shared bucket and an anonymous sub-token grants nothing an anonymous read could +not already do directly. The server MUST verify, against its LIVE authorization state (never trusted +from the request), that the calling principal can itself **read** `prefix` — the identical gate a +data-plane read of that path would apply (the "Object data (the noun)" section of {{RESTACT}}) — and MUST refuse `403` when it cannot; +this is the load-bearing attenuation check, since everything downstream depends on the minted token +never exceeding it. The minted token MUST be read-only (this profile defines no write-capable +sub-token). `ttl_seconds`, when supplied, MUST be honored up to a server-defined ceiling and MUST be +CLAMPED (never refused) when the request exceeds it; a server SHOULD default to a short TTL (on the +order of minutes) when the field is absent and MUST advertise both the default and the ceiling, as +the `subTokenTtl` member `{defaultSeconds, maxSeconds}` of the `service` object of its discovery +document (the "Discovery" section of {{RESTACT}}), since they are otherwise unobservable to a +client. The endpoint MUST be rate-limited per authenticated principal, refusing excess mint attempts +with `429` — minting is cheap to request but each attempt costs a signature, so an unbounded mint +surface is a denial-of-wallet vector in its own right, independent of what is ultimately minted. + +**Recognizing a sub-token.** The mint response's `token` MUST be structurally distinguishable from an +ordinary bearer issued by the same server (for example, via a reserved `aud` claim on a JWT-shaped +token) — every downstream authorization gate consulting it needs to know, without ambiguity, that it +is confined. A path-scoped sub-token runs under an **attenuated principal** (the "Authorization and +Identity" section of {{RESTACT}}): the server keeps only the minting principal's `sub`, for the +`owner`, `sub:` and `prop:` matchers and for provenance and logging, and drops its roles, +groups, scopes and claims. A resource readable only through a `role:`, `group:`, `scope:` or +`claim:` matcher is therefore unreadable through a sub-token even though the minting principal +could read it directly. The rule on `deny` rules in that section applies to the sub-token. + +**Enforcement.** For any request authenticated as a sub-token, a server MUST apply the following as +ADDITIONAL denials layered on top of its ordinary authorization evaluation — this profile can only +ever turn an `allow` into a `deny`, never the reverse: + +1. A read of an object path that is not within the token's `prefix` MUST be refused `403` + `forbidden`. +2. Any write, delete, manage, or verb-deployment action MUST be refused `403` `forbidden`, + unconditionally — independent of what the underlying `$policy` or verb policy would otherwise + permit. Minting a FURTHER sub-token from a sub-token MUST likewise be refused `403` `forbidden` + (a non-read action against `POST /v1/tokens/sub` itself), foreclosing scope-laundering and + unbounded delegation depth. On a server that advertises `delegated-tokens`, a sub-token MUST + also be refused `403` `delegation-bound` on the grants API and as the exchange's `actor_token` + ({{delegated-tokens}}); on a server that does not, those routes answer `404` to every caller. A + principal that is the actor of a live grant it has exchanged MUST NOT mint a sub-token. +3. A read within `prefix` is authorized exactly as the minting principal's own read would be + (subject to the narrowing in "Recognizing a sub-token" above) — no NEW grant is created. + +Expiry is enforced exactly as for any other bearer of the same underlying credential mechanism; a +sub-token past its `exp` MUST be refused like any other expired bearer. + +**Reach of the denials.** These denials apply to every authorization decision the server makes for +a request authenticated by a sub-token and for the work it causes, whichever document defines that +decision. They only narrow what the request may do, as the "Extension specifications" section of +{{RESTACT}} lets any extension do. + +**Reachability from an opaque origin.** The primary motivating consumer is a sandboxed, opaque-origin +browsing context ({{HTMLIFRAME}}, `sandbox="allow-scripts"` without `allow-same-origin`) whose fetches to +the server are cross-origin with `Origin: null`. A server that also implements CORS (the "Security Considerations" section of {{RESTACT}}) MAY +extend its allowed-origin policy so that a request presenting a sub-token succeeds from `Origin: null` +for reads within scope, WITHOUT reflecting credentials — this does not create a new server-side +authorization (the "Security Considerations" section of {{RESTACT}}: CORS governs only whether a browser lets a page read a response, never +whether the server accepts the request), and remains fully subject to the enforcement rules above. + +**Discovery.** A server supporting this profile MUST advertise `path-scoped-tokens` in its feature list +(the "Discovery" section of {{RESTACT}}); a client MUST NOT assume the mint endpoint exists absent that token. + +The discovery document (the "Discovery" section of {{RESTACT}}) lists no verbs to a request +authenticated by a sub-token. + +# Delegated tokens (OPTIONAL, feature `delegated-tokens`) {#delegated-tokens} + +Every credential defined so far is either a principal's COMPLETE authority or, for a sub-token +({{path-scoped-tokens}}), a read-only view of one subtree. A server MAY additionally let one +principal (the **subject**) authorize another (the **actor**) to act for them, within bounds, +while BOTH identities stay visible. The subject creates a durable **grant**; the actor presents +proof of itself and receives a short-lived **delegated token** that authenticates as the subject, +bounded by the grant. + +**Four independent tokens.** + +* `delegated-tokens`: the grant, the grants API, the exchange, the delegated token, the bounds + and their reach, the refused surfaces, traces, and secret values (this section). +* `delegated-client-actors`: an actor that is a program with no principal of its own + ({{client-actors}}). A server advertising it MUST advertise `delegated-tokens`. +* `identity-actor`: the delegation actor in the `identity` interface, described at the end of this + section, and in every frame the bounds reach. A server advertises it only alongside `delegated-tokens`. +* `object-provenance`: the `?meta=provenance` facet ({{provenance-facet}}). It is usable without + delegation. + +A fifth token, `delegated-prefixes`, is named for a later amendment that lets a grant carry a +workspace list. It is NOT defined here; its absence tells a client that `prefixes` is refused. + +**The grant.** A grant is a server-held record with these fields: + +| Field | Meaning | +|---|---| +| `id` | opaque, at least 128 random bits. An identifier, not a credential: exchanging needs the actor's proof. | +| `subject` | the creating principal's subject. Immutable. | +| `actor` | `{"kind": "principal", "sub": ""}`, or `{"kind": "client", "id": "client:", "label": ""}` ({{client-actors}}). Immutable. | +| `read_only` | boolean. `true` when a request omits it. | +| `snapshot` | the creating credential's roles, groups, scopes and scalar claims, captured at creation and re-captured at every `PATCH`. NEVER returned on the wire. | +| `created_at`, `expires_at` | `expires_at` MUST NOT exceed `created_at` plus the advertised `grantTtl.maxSeconds` | +| `label` | optional display text, at most 200 characters | +| `last_used_at` | the time of the last successful exchange (SHOULD) | +| `exchanged_at` | the time of the grant's first successful exchange. Server-held: set once, never changed or cleared (a `PATCH` keeps it), NEVER returned on the wire. A principal is bound as an actor only once this is set. | +| `secret_hash` | client actors only: the hash of the current grant secret. NEVER returned on the wire. | + +* Only the subject's own ordinary credential manages a grant. It MUST be non-anonymous, and neither + a sub-token nor a delegated token. +* An actor equal to the subject MUST be refused (`400`). A server MAY restrict which principals may + create grants. +* **The snapshot is how the ceiling is "the user's own permissions".** A delegated principal's + roles, groups, scopes and claims come from the grant's snapshot, so a permission the subject + holds through a `role:`, `group:`, `scope:` or `claim:` matcher is not lost. The snapshot MUST + NOT be wider than the credential that created or last renewed the grant. +* **`prefixes` is reserved.** Until a server advertises `delegated-prefixes`, it MUST refuse any + grants request that carries a `prefixes` member, whatever its value (`null` and `[]` included), + with `400` `invalid-input` ("workspace prefixes are not supported by this server"), and it MUST + treat a stored grant that carries `prefixes` (after a downgrade or a restore) as **not live** + everywhere liveness is checked. A list is never accepted and left unenforced. + +**The grants API.** Its routes, and the exchange's, live under the object paths that the core +reserves for this section: `tokens/grants` and `tokens/exchange`, and every path beneath each, under +`/v1/` (the "Extension specifications" section of {{RESTACT}}). The wire uses snake_case, as +`POST /v1/tokens/sub` does. + +| Request | Result | +|---|---| +| `POST /v1/tokens/grants` | `201` with the grant. Body: exactly one of `actor`, a JSON string naming the actor's subject (a server MAY bound its length), and `client`, an object ({{client-actors}}); then `read_only?`, `ttl_seconds?` (CLAMPED to `grantTtl.maxSeconds`, never refused) and `label?`. A body that names both `actor` and `client`, or neither, is refused `400`. | +| `GET /v1/tokens/grants` | `200`, the caller's own live grants, newest first, paginated as the "Collections: Listing, Pagination, Filtering, Field Masks" section of {{RESTACT}} defines (`pageSize`, `pageToken`, `nextPageToken`) in a body `{"grants":[…],"nextPageToken"?:"…"}` | +| `GET /v1/tokens/grants/{id}` | `200`, or `404` when the grant is absent, expired, revoked, not live, or not the caller's: ONE answer for all, so there is no existence oracle | +| `PATCH /v1/tokens/grants/{id}` | `200`. Any of `read_only`, `ttl_seconds` (resets `expires_at` from now, clamped) and `label`. MUST re-capture the snapshot from the presenting credential (replacing it, not merging), whether or not any other field changes. Narrowing and widening are both allowed, since only the subject can call it. | +| `DELETE /v1/tokens/grants/{id}` | `204`; the grant is revoked. Again, or for another's grant: `404`. | + +* An anonymous caller MUST get `401`. +* A sub-token or delegated caller MUST get `403` `delegation-bound`. +* `POST` and `PATCH` by a principal that is the actor of ANY live grant it has exchanged MUST get `403` + `delegation-bound`, even with its own ordinary bearer. Its `GET` and `DELETE` are unaffected: + revoking is always allowed. This refusal precedes any ownership answer. +* Excess requests, or a per-subject cap on live grants, give `429` `quota`. +* A `prefixes` member gives `400` `invalid-input`. A refused `PATCH` MUST change nothing. +* Timestamps are unix seconds. A grant's wire actor is `{"kind":"principal","sub":""}` or + the client form above. +* No response ever carries `snapshot`, `secret_hash` or a pending client's `code_challenge`. Every + response, errors included, MUST carry `Cache-Control: no-store`. +* A server accepting cookie-borne sessions on the grants API MUST apply its cross-site request + forgery defense there: a forged grant creation hands the forger a credential. + +**The exchange (RFC 8693).** `POST /v1/tokens/exchange`, `application/x-www-form-urlencoded`, as +{{RFC8693}} §2.1 defines it. + +| Parameter | Value | +|---|---| +| `grant_type` | `urn:ietf:params:oauth:grant-type:token-exchange` | +| `subject_token` | the grant id | +| `subject_token_type` | `urn:restact:params:oauth:token-type:grant` | +| `actor_token` | **the actor's proof.** For a principal actor, its own ordinary bearer (`actor_token_type` `urn:ietf:params:oauth:token-type:access_token`). For a client actor, the grant secret (`urn:restact:params:oauth:token-type:grant-secret`, {{client-actors}}). | + +The two `urn:restact:` token-type URIs are provisional, and no registry holds them yet +({{delegation-iana}}). + +A server MUST apply these refusals in this order: + +1. A request with an `Authorization` header gets `400` `invalid_request`. The actor is proven only + by `actor_token`. +2. `resource`, `audience` or `scope`, or a `requested_token_type` other than an access token, gets + `400` `invalid_request`. Narrowing lives on the grant, not on the exchange. +3. When `actor_token_type` is the access-token type, the server MUST VERIFY `actor_token` through + its ordinary bearer verification first; a token that fails gets `401`. Only a token that + verifies is then classified: a delegated token or a sub-token gets `403` `delegation-bound`. + Unverified claims MUST NOT be read, so a forged token learns nothing beyond `401`. +4. The grant named by `subject_token` is loaded. An unknown, expired or revoked grant, or one that + is not live, gets `401` `invalid_grant`. +5. The proof is checked against what **the grant's `actor.kind`** requires, never against the type + the caller declared: a principal actor requires step 3's verified bearer, with `sub` equal to + `grant.actor.sub`; a client actor requires the grant-secret type, matching `secret_hash`. + Anything else gets `401` `invalid_grant`. + +Steps 4 and 5 MUST answer identically, in status and body. The endpoint MUST be rate-limited per +actor and per source (`429` `quota`); a failed exchange counts against the presenting source and +actor, never against the grant. A limit MUST NOT refuse a proof that verifies; `429` replaces +only a failure. The source is the transport peer, so a server behind a proxy has one source for +all of its callers; a server's counters MAY be per process (N nodes then give N times the budget) +and MAY be bounded, in which case a failure from an untracked key is limited rather than +unlimited. Success is `200` with `Cache-Control: no-store`: + +~~~json +{ "access_token": "…", + "issued_token_type": + "urn:ietf:params:oauth:token-type:access_token", + "token_type": "Bearer", "expires_in": 900, "subject": "alice", + "grant_secret": "…" } +~~~ + +`subject` is the grant's subject; **the actor MUST check it** against the user it is serving before +using the token. `grant_secret` is present for a client actor only. Errors are Problem Details +(the "Errors" section of {{RESTACT}}) with one added member, `error`, carrying the RFC 6749 §5.2 code (`invalid_request`, +`invalid_grant`); status codes follow the error table of the "Errors" section of {{RESTACT}}, so an `invalid_grant` is `401`. + +A successful exchange MUST record `exchanged_at`, if it is unset, before it returns the token. The write MUST be conditional on the grant still being stored and live, so it never revives a revoked grant, and on a multi-node backend it MUST be committed to the shared store. If the grant is no longer stored and live when the write is made, the exchange MUST issue no token and answer as step 4 does. If the write cannot be committed for another reason, such as a store failure, the exchange MUST fail with `503` (`restact_code` `unavailable`, which the "Errors" section of {{RESTACT}} registers) and issue no token. + +**The delegated token and the delegated principal.** The token is signed with the server's ordinary +bearer key and MUST carry NO `kid` header (a `kid` would route it to an external identity +provider's verifier). Its claims: `aud` containing the reserved value `restact-delegated`; `sub` +the grant's subject; `act` `{"sub": }`; `grant` the grant id; `iat`; and `exp` no later +than the lesser of now plus `tokenTtl.maxSeconds` and the grant's `expires_at`. A refresh is a +fresh exchange. + +* A server treats a credential as delegated only if it issued it through the exchange. An `act` + claim on any other credential MUST be ignored. +* A request that carries a bearer whose `aud` contains `restact-delegated` together with an + identity any other mechanism establishes (a trusted identity header, or the session of an + application the server is mounted in) MUST be refused `401`, so that other identity cannot + silently drop the grant's bounds. Reading `aud` for this refusal needs no verification, because + it can only refuse. +* **Per request**, the server verifies the signature and `exp`; loads the grant and checks that it + is live and has a recorded exchange, that `grant.subject == sub` and that `grant.actor == act.sub` + (otherwise `401` `unauthorized`; so no delegated request is served under a grant whose exchange + the store does not show, for example after a restore); and builds the **delegated principal**, whose subject is `grant.subject` and + whose roles, groups, scopes and claims come from `grant.snapshot`. Beside it, never on it, the + server carries the **delegation record** `{actor, grant, read_only}`. +* The precedence of authentication mechanisms is unchanged: a delegated token is recognized only + where a bearer is the credential that authenticated the request. +* The token's own claims (`act`, `grant`, `aud`) MUST NOT be visible to any matcher or to + `identity.claim()`. All bounds come from the stored grant on every request, so a `PATCH` or a + `DELETE` takes effect on the next request without a new token. +* **The actor adds no authority.** Policy is evaluated as the subject; a matcher naming the actor's + own principal does not admit a delegated request. +* Liveness is checked once, when the request is authenticated; a request already in flight + completes. A server MAY cache grant state for at most the advertised + `revocationLatencySeconds`. A cached copy that shows no exchange is never trusted: the server + re-reads the grant before it refuses for that reason, and before it applies the actor rule. + +**Delegated requests (OPTIONAL, feature `delegated-tokens`).** A request authenticated by a +delegated token runs as its **subject**, bounded by the grant: the bounds are +additional denials only, and they follow every frame the request causes. The compute cost of such a +request is attributed to its real caller, the subject. + +**The bounds: additional denials only.** Like a sub-token's, the bounds can turn an allow into a +deny, never the reverse. A request the delegated principal could not make is refused exactly as the +subject's own would be (the **ceiling**). A `read_only` grant additionally admits ONLY `GET` and +`HEAD` of stored representations and facets, and `GET` invocations of functions; it refuses every +other method with `403` `delegation-bound`, decided from the request and the grant alone, before +policy or existence is consulted, so the refusal is no existence oracle. Inside a frame, the guest +sees the same error a policy denial gives it, with no new error case. Read-only blocks changes +only: it does not block what a read or a function reaches without changing anything. + +**Reach of the bounds.** The bounds apply to every authorization decision the server makes for a +delegated request and for the work it causes, whichever document defines that decision. They only +narrow what the request may do, as the "Extension specifications" section of {{RESTACT}} lets any +extension do. + +**The bounds follow the work.** Code installed under a delegation stays bound by it, whoever +triggers it. + +* *(a) Frames the request causes* (composition hops, authority-switched frames, lifecycle hooks + fired by a delegated write, and asynchronous operations) carry the delegation record's actor + unchanged across every switch; an operation started under delegation completes under the bounds + captured when it started. +* *(b) Registrations made under delegation.* A schedule or subscription created by a delegated + request MUST store the grant id. Each firing runs as the registrant's attenuated authority and + carries the actor. A firing MUST be skipped, finally and with an operator-log record, when its + grant is not live, or when the grant is read-only and the target is an action. The registration + itself remains. +* *(c) Code installed under delegation: the stamp.* A server MUST stamp a verb + `elevatedUnderGrant: ` when a write made under delegation leaves it running as its + owner or touches a lifecycle hook (a deployment, a rollback, a `policy` write, or any other + verb-property write). The stamp is server state, replaces any earlier stamp, and is checked at + every authority switch into a stamped verb and at every firing of a stamped hook. When the + stamp's grant is not live, every stamped verb pauses (the switch is refused `403` + `delegation-bound`, a hook firing is skipped and logged). When the grant is read-only, the same + applies to stamped actions and every stamped hook, but a stamped function proceeds. When the grant + is live, the switch proceeds and carries the stamp's actor. The stamp is cleared when a + non-delegated credential of the grant's subject, or of the verb's owner, makes any stamping write + on the verb; a rollback that leaves the verb running as its owner, or a verb that is a lifecycle + hook, re-applies the grant recorded with the history entry it restores, unless made by a + non-delegated credential of that grant's subject. While a verb is stamped, its `meta` + carries `boundVia: ` and NEVER the grant id. +* *The actor's own registrations.* A schedule or subscription whose registrant is a stamp grant's + actor, created with that actor's own credential while its target is stamped, MUST record that + grant; its firings are skipped once the grant is not live, even after the target is re-saved, so a + standing registration the agent set up for itself does not come back to life because the user + later re-saved the verb. +* *Hook code is the owner's to replace.* Replacing the code of a lifecycle hook, which runs under + its owner's authority, MUST be performed by the owner. This applies to every caller, and it is the rule on replacing a + hook's code that the "Events, Triggers, and Scheduling" section of {{RESTACT-EVENTS}} states. + +**The `boundVia` member (feature `delegated-tokens`).** While a verb is stamped as elevated under a +delegation, its `meta` (the "Verb properties (the program itself)" section of {{RESTACT}}) MUST +carry `boundVia`, the actor's identifier, and MUST NOT carry the grant id. A verb that is not +stamped carries no `boundVia`. + +**Never-delegable acts, and refused surfaces.** A delegated principal MUST be refused `403` +`delegation-bound` for every method of the grants API, use as the exchange's `actor_token`, +client-actor redemption, and sub-token minting. (A credential in the exchange request's +`Authorization` header is refused earlier, `400` `invalid_request`, by the exchange's first +refusal.) A **principal that is the actor +of any live grant it has exchanged** MUST likewise be refused when it creates or renews a grant or mints a sub-token, +EVEN WITH ITS OWN ORDINARY BEARER; its reading, listing and revoking of its own grants stay +allowed. A server MUST also refuse a delegated principal, `403` `delegation-bound`, on the surfaces +whose bounds cannot be shown to hold: SSE subscriptions, the MCP facet ({{RESTACT-MCP}}), embedder custom +routes, and the administrative routes. Native (embedder) verbs are not refused; they are invoked +through the ordinary verb path and a server MUST NOT hand them the raw delegated bearer. + +**Traces.** + +* An object created under delegation is owned by the subject. +* A deployment or rollback made under delegation SHOULD record `deployedVia` (the actor id) beside + `deployedBy` (the "Deployment history and rollback (OPTIONAL, feature `verb-history`)" section of {{RESTACT-OBJECTS}}). + A server records the stamp's grant with each history entry of a stamped verb, so that a rollback + can re-apply it, and MUST NOT expose it: the grant id MUST NOT appear in a history + representation. +* The auto-published event payload carries the `actor` member that the "Publishing events" section + of {{RESTACT-EVENTS}} requires for a mutation made under delegation; event names are unchanged. + +**Secret values stay the user's to type.** On a server that also advertises `secrets-management` +({{RESTACT-CONNECTORS}}), a delegated `PUT` carrying a `value` member on a mount path MUST be refused `403` `delegation-bound`. +Creating the reference (metadata, no value) is allowed. + +**Discovery and configuration.** A server MUST advertise `delegated-tokens` only when it can sign +and the operator has not switched delegation off. It MUST publish, as the `delegation` member of +the `service` object of its discovery document (the "Discovery" section of {{RESTACT}}), +`tokenTtl {defaultSeconds, maxSeconds}`, `grantTtl {defaultSeconds, maxSeconds}` and +`revocationLatencySeconds`; the reference values are 900/900, 3600/2,592,000 and 0. + +**Until it advertises the token, every route in this section answers `404` and authentication +refuses every delegated token with `401`**, so no grant or client secret can be minted before its +enforcement exists. The paths `tokens/grants` and `tokens/exchange`, and everything beneath each, +under `/v1/` are reserved on every server, whether or not it advertises delegation, as +`/v1/tokens/sub` is (the "Extension specifications" section of {{RESTACT}}). A server that switches delegation off MUST fail closed: every grant is not +live, and a server that boots with delegation off MUST revoke every stored grant before serving a +request, so that switching it back on revives nothing. If that revocation cannot be committed the +server MUST refuse to boot. On a multi-node backend the revocation is made in the shared store, and +a node running with delegation off treats every grant as not live, even one another node created +after it booted. A pending asynchronous operation started under delegation is not resumed. The +rules of this paragraph bind a server that implements delegated tokens whether or not it advertises +`delegated-tokens`. + +**The delegation actor.** A server MAY expose, through the `identity` interface (the "Caller +Identity" section of {{RESTACT}}), the **delegation actor** of the invocation, as an OPTIONAL +feature (token `identity-actor`). This value is ambient. It is read with +`actor() -> option`, whose value is the actor's identifier: the actor's subject for a +principal actor, or the server-assigned `client:` identifier for a client actor +({{client-actors}}). It is returned in every frame whose work runs under a delegation's bounds, +authority-switched frames and hooks included, and in every frame of code installed under a delegation, whoever triggered it, +and none otherwise. It discloses the actor's identifier only — never the delegating subject, nor any +role, scope, group, or claim — and it reaches another owner's authority-switched frames and hooks +when delegated work reaches them. On a server that does not disclose the real identity (the +"Caller Identity" section of {{RESTACT}}), the value identifies no actor. It is the string +`delegated`, for every actor and in every frame, so a verb learns that a delegation bounds the +frame and nothing more. Whether `actor()` returns a value is the same on every server, so a verb +that decides by that alone behaves alike on each. A verb that compares the value with an +identifier it holds, or keys data by it, reads `subject-kind()` first: where that answers +`pairwise` the value is this string and names no one, so a list of actors to refuse matches +nothing and every actor shares one key. Through `actor()` such a server gives no pairwise form of +an actor's identifier, for a client actor or a principal actor ({{delegation-security}}). + +**Error code.** This document defines one `restact_code` value, in the form of the error table of +the "Errors" section of {{RESTACT}}, and registers it ({{delegation-iana}}). A server uses it only +at the places that {{delegated-tokens}} and {{path-scoped-tokens}} name. + +| `restact_code` | Status | Meaning | +|---|---|---| +| `delegation-bound` | 403 | the credential or the code is bound by delegation ({{delegated-tokens}}): a delegated token or a sub-token on the grants API, as the exchange's `actor_token` or at redemption; a delegated request on a refused surface, outside its grant's bounds, minting a sub-token or writing a secret value; the actor of a live grant it has exchanged creating or renewing a grant or minting a sub-token; or an authority switch into a verb whose stamp's grant no longer allows it. A sub-token's own confinement ({{path-scoped-tokens}}) is `forbidden`. | + +# Client actors (OPTIONAL, feature `delegated-client-actors`) {#client-actors} + +A **client actor** is a program on the user's machine with no principal of its own. The sign-in +page and the program are clients of the grants API, and the requirements below on each bind it as a +client (the "Conformance and Feature Discovery" section of {{RESTACT}}). The flow follows +{{RFC8252}} loopback sign-in with {{RFC7636}} PKCE: + +1. The program starts a loopback listener and opens the sign-in page with a `code_challenge`. +2. That page, in the user's own session, calls `POST /v1/tokens/grants` with + `{"client": {"label", "code_challenge", "code_challenge_method": "S256"}, …}`. +3. The server assigns the actor id `client:` and returns the grant plus a one-time `code` + that lives at most 120 seconds. +4. The page relays the code to the listener. The server never redirects. The relay target MUST be a + loopback IP literal (`127.0.0.1` or `[::1]`) with a port, and the page MUST refuse any other + target. +5. The program calls `POST /v1/tokens/grants/redeem` with `{code, code_verifier}`. This route is + unauthenticated, and is refused if it carries a sub-token or a delegated token. +6. The server checks the S256 verifier and returns `{grant_id, grant_secret, actor}`, exactly once. + +The code is consumed by its first redeem attempt, successful or not. The label is untrusted text: +a sign-in page and every grants list MUST render it as plain text beside the server-assigned id. + +**The grant secret** has at least 256 random bits and is stored only as a hash. It is the client's +`actor_token` and is not a bearer for any other route. **It rotates on every exchange**: a +successful exchange returns a new `grant_secret` and supersedes the one presented, and presenting a +superseded secret MUST revoke the grant (the refresh-token rotation of {{RFC9700}}). Where the platform offers an operating-system credential +store bound to the client program, the client MUST keep the secret there; otherwise it MUST tell +the user at sign-in that the agent's own tools may be able to read the secret, and MUST NOT put the +secret in an environment variable that tools the agent runs inherit. + +An actor id SHOULD NOT encode the delegating subject. On a server advertising this token, no +ordinary credential whose subject begins with `client:` authenticates (`401`). + +# The provenance facet (OPTIONAL, feature `object-provenance`) {#provenance-facet} + +`GET /v1/?meta=provenance` returns `{"created":{"subject","actor"?,"at"},"updated":{…}}` for +the object. It covers every committed mutation of the object (data-plane and capability writes, +blob writes, `$policy` and `$owner` writes), committed atomically with the write it describes. An +ownership reassignment ({{admin-reown}}) is an `$owner` write: it sets `updated` to the operator's +subject with no `actor` (or, for a reassignment the server makes outside any request, to a subject +the server reserves for that purpose), and leaves `created` as it was. +`subject` is the principal the write ran as; `actor` appears only for a write made under delegation; +no grant id ever appears. An object last written before the feature existed returns no `created` or +`updated` member. The facet is read-gated by the object's own `read` and answers `404` or `403` +exactly as a `GET` of the object would; it is never part of the object's representation. + +# Security Considerations {#delegation-security} + +* **Delegation.** A grant ({{delegated-tokens}}) lends a user's authority to an actor. Revocation + stops delegated tokens, the schedules, subscriptions and elevated code installed under the grant, + but NOT the data the actor wrote, the shares it made (a share never transfers ownership: see the + "Ownership is fixed" section of {{RESTACT}}), the ordinary verbs it deployed, + or the connector wiring ({{RESTACT-CONNECTORS}}) it created. A role snapshot goes stale until the grant is renewed. A server accepting cookie-borne + sessions on the grants API MUST apply its cross-site request forgery defense there, because a + forged grant creation hands the forger a credential. +* **Operator recovery.** An operator recovery act MUST withdraw the runs-as-owner opt-in and pause + the hooks on what it moves ({{admin-reown}}), so a reassignment by the operator does not push + authority as an owner's reassignment would (the "Pushed authority (ownership reassignment)" bullet + of the "Security Considerations" section of {{RESTACT}}). +* **The actor's identifier.** Delegation keeps the actor visible. Its identifier appears in the + event for what it writes, where {{RESTACT-EVENTS}} requires or the server includes the member, + in the provenance facet ({{provenance-facet}}), in the `boundVia` of a verb its write stamps + ({{delegated-tokens}}), and in the grant its subject reads. A pairwise form of it, like the + pairwise subject of the "Caller Identity" section of {{RESTACT}}, would therefore not stay + apart from the real one. An owner whose lifecycle hook ran for a delegated write and who read + the same write's event, or who read the `boundVia` of a stamped verb of its own, would hold both + forms. A client actor's identifier belongs to one user's grant. Where the event or the facet + names that user beside it, the owner would then know the user behind every later delegated call + that carried the same pairwise actor, and with it the user's own pairwise subject, which is what + that subject exists to prevent. A server that does not disclose the real identity therefore + gives a verb only the fact that a delegation bounds the frame ({{delegated-tokens}}). Three + limits remain. That fact narrows who a caller is: an owner who sees few delegated calls, and + reads events that name the user and actor of delegated writes, can match them by number or by + time, and an operator who minds does not offer `identity-actor`. An actor is told the subject it + acts for when it exchanges the grant, so an actor that owns a verb and invokes it with the + delegated token reads that subject's pairwise form for itself and holds both; a user is not + pseudonymous to an actor it delegates to. And the identifiers on the data plane stay: whoever + may read what an actor wrote learns the actor wherever the event or the facet names it, and two + owners who both read a `client:` identifier can tell that one user's agent wrote to both. + +The security considerations of {{RESTACT}} apply. + +# IANA Considerations {#delegation-iana} + +This document requests the following registrations in registries that {{RESTACT}} creates. It +creates no registry. + +* In the "REST:ACT Feature Tokens" registry: the tokens in the table of + {{delegation-relationship}}, with `delegated-prefixes` registered as reserved. +* In the "REST:ACT Error Codes" registry: `delegation-bound` ({{delegated-tokens}}). + +The object paths `tokens/sub`, and `tokens/grants` and `tokens/exchange` with everything beneath +each, under `/v1/`, and the `aud` value `restact-delegated`, are reserved by {{RESTACT}} (its "Extension +specifications" section) for the meanings this document gives them. + +This document also defines two provisional token-type URIs, +`urn:restact:params:oauth:token-type:grant` and `urn:restact:params:oauth:token-type:grant-secret` +({{delegated-tokens}}). No registry that {{RESTACT}} creates holds them. diff --git a/src/content/spec/draft-byrd-restact-events-00.md b/src/content/spec/draft-byrd-restact-events-00.md new file mode 100644 index 0000000..b77c059 --- /dev/null +++ b/src/content/spec/draft-byrd-restact-events-00.md @@ -0,0 +1,814 @@ +--- +title: "REST:ACT Events" +abbrev: "REST:ACT Events" +docname: draft-byrd-restact-events-00 +category: exp +submissiontype: independent +ipr: trust200902 +area: "Applications" +keyword: + - REST + - WebAssembly + - custom methods + - capability security +stand_alone: yes +pi: [toc, sortrefs, symrefs, comments] +author: + - + ins: N. Byrd +normative: + RFC8259: + RESTACT: + title: "The REST:ACT Protocol: Invoking Sandboxed Functionality over REST" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-protocol-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-protocol-00.md +informative: + RESTACT-DELEGATION: + title: "REST:ACT Identity and Delegation" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-delegation-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-delegation-00.md + RESTACT-PRESENTATION: + title: "REST:ACT Presentation Verbs" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-presentation-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-presentation-00.md + RESTACT-OBJECTS: + title: "REST:ACT Objects and Data" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-objects-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-objects-00.md + +--- abstract + +This document specifies an optional extension to REST:ACT, the protocol for invoking sandboxed +verbs over HTTP. It defines how a server runs a verb that no client request started: a lifecycle +hook when an object is created, changed or deleted, a subscription when an event is published on a +topic, and a schedule at a set time. It defines how a verb publishes an event, how a server delivers +a topic's events to clients over Server-Sent Events, and how a server reports which objects a +rendered view read, so that a client can refresh only the views an event affects. A server +advertises each feature with its own token. + +--- middle + +# Introduction {#events-introduction} + +REST:ACT {{RESTACT}} runs a verb when a client invokes it. This document defines the optional +features under which a server also runs verbs on its own, and publishes and delivers events: + +* lifecycle hooks, subscriptions and schedules, each run under the authority of the principal that + registered it ({{events}}); +* the event-publish capability, through which a verb publishes an event on a topic, and the events + the server publishes itself ({{event-publish}}); +* the read set, which tells a client which objects a rendered view depends on + ({{read-set-headers}}); +* delivery of a topic's events to clients over Server-Sent Events ({{event-sse}}); +* verb subscriptions, which deliver a topic's events to a verb ({{verb-subscriptions}}); +* schedules, which run a verb on a recurrence ({{schedules}}); +* the rules that subscriptions and schedules share as registered resources, and how a server + reports how their firings ended ({{registrations}}, {{registration-outcomes}}). + +Each is optional, and a server advertises each one it implements with its own feature token +({{events-relationship}}). + +## Relationship to REST:ACT {#events-relationship} + +This document is a REST:ACT extension, as described in the "Extension specifications" section of +{{RESTACT}}. That section says whom this document binds: a server that offers a mechanism one of +these feature tokens covers advertises the token and is bound by what this document requires of +that mechanism, and a requirement on a mechanism no token covers, such as a lifecycle hook outside +the data-plane CRUD subset, binds every server that offers the mechanism. The tokens are +`lifecycle-hooks`, `event-subscriptions`, `verb-subscriptions`, `verb-subscriptions-read-gate`, +`schedules`, `registration-outcomes`, `targeted-invalidation` and `admin-checkpoint`. The token +`events` is registered and reserved; no server advertises it. A requirement that also names a +feature or mechanism of another +document, such as a delegated credential or a presentation verb, binds a server that this document +binds when that server also offers that feature or mechanism. A client does not assume any behavior of this document from a server that does not +advertise its token. + +| Feature tokens | Section | +|---|---| +| `lifecycle-hooks` (data-plane CRUD subset) | {{events}} | +| `schedules` | {{events}}, {{schedules}}, {{registrations}} | +| `event-subscriptions` | {{event-publish}}, {{event-sse}} | +| `admin-checkpoint` | {{event-publish}} (reserved host topics) | +| `targeted-invalidation` | {{event-publish}}, {{read-set-headers}}, {{event-sse}} | +| `verb-subscriptions`, `verb-subscriptions-read-gate` | {{verb-subscriptions}}, {{registrations}} | +| `registration-outcomes` | {{registration-outcomes}} | +| `events` | none: registered and reserved | + +Every invocation this document starts without a request caller (a lifecycle hook, a subscription +delivery or a scheduled firing) runs under the authority of the principal that registered it, +attenuated as the "Execution identity" section of {{RESTACT}} sets for such invocations, the +extension point that the "Extension specifications" section of {{RESTACT}} names E2. + +{::boilerplate bcp14-tagged} + +# Events, Triggers, and Scheduling {#events} + +Beyond client-initiated invocation, a server MAY support **server-initiated** invocation, running a +verb in response to an event or a schedule. This entire section is OPTIONAL; a server that does not +support it remains conformant. A server **supports eventing** when it publishes events by any means +this document defines (the event-publish capability, auto-publishing, or a reserved host topic) or +delivers them to clients or verbs. + +An **event** is a message with a name and payload, associated with a **topic**, where a topic is an +object path: events concerning `/rooms/tavern` are published on that path. A verb MAY publish an +event through a host capability (the "Capability Model" section of {{RESTACT}}); publishing is the only new primitive — +everything that *handles* an event is an ordinary verb. There are three handling mechanisms, each +reusing existing constructs: + +* **Lifecycle hooks** are reserved verb names that begin with `on` followed by an uppercase + letter (for example `onCreate`, `onDelete`, `onChange`, `onEnter`). When a server performs the corresponding operation on an + object, it invokes that object's hook verb if one is defined, resolved up the inheritance chain + (the "Verb Resolution and Inheritance" section of {{RESTACT}}) — exactly as accessor verbs (the "Active Properties (Accessor Verbs)" section of {{RESTACT-OBJECTS}}) mediate data access. A server + MAY support the **data-plane CRUD subset** of lifecycle hooks independently of the rest of this + section, advertised by the `lifecycle-hooks` feature token. A server that advertises it MUST treat + `onCreate`, `onChange`, and `onDelete` as reserved verb names that MUST be actions (the "Verb invocation (the bare verb)" section of {{RESTACT}}), and + MUST, after a data-plane mutation on an object path commits, invoke that object's matching hook if + one resolves and its registrant may read the object (below): `PUT` fires `onCreate` when the + object did not previously exist and `onChange` when it did, and `DELETE` fires `onDelete` (after + the delete). The hook runs through the ordinary invocation + path under **registrant authority**: as the principal who registered the hook (its owner), charged to + that owner's quota and bound by the same limits and the hook's own `execute` policy — NOT as the + caller who triggered it. The triggering caller's identity is conveyed to the hook only as + informational input, granting no authority; this prevents a hook that auto-fires on a third party's + write from acting with that writer's identity (reading the writer's data or claims and exfiltrating + them). Where the input names that caller, it MUST give the real subject of the principal the + write ran as, and never a pairwise subject (the "Caller Identity" section of {{RESTACT}}), + whatever the hook reads from the `identity` interface ({{events-security}}). A server MAY leave + the identity out of the input, so a hook MUST NOT take its absence to mean an anonymous writer. + Firing is **best-effort**: a hook error or trap does not roll back or fail the mutation (the + mutation is the client's authoritative intent). A hook paused by an operator's ownership recovery + is not invoked (the "Operator ownership recovery (OPTIONAL, feature `admin-reown`)" section of {{RESTACT-DELEGATION}}). Nor is a hook whose registrant may not read the object: before + it invokes a hook, on every mutation that fires one, a server MUST evaluate whether the hook's + registrant, attenuated as for any server-initiated invocation, is authorized to read the object + (the "Authorization and Identity" section of {{RESTACT}}). For `onCreate` and `onChange` the gate is evaluated against the object as the + mutation left it. For `onDelete` it is evaluated against the authorization the object had + immediately before its removal, as for a deletion delivered to a subtree subscription over SSE + ({{event-sse}}). If the + registrant may not read the object, or the server cannot establish that it may, the server MUST + NOT invoke the hook, and MUST NOT invoke a hook resolved further up the inheritance chain in its + place. Such a skip is final, is not charged to the registrant, and MUST NOT be observable to the + registrant. A server SHOULD record it in an operator-facing log; that record MUST NOT carry the + hook's payload or the triggering principal, and SHOULD name the hook by its deployed route rather + than by the mutated object's path. Without this gate a hook + defined on an ancestor would learn the path, time, and author of every mutation beneath it, + including mutations of objects whose own policy shuts the hook's owner out. A server MUST bound a + hook→write→hook chain (e.g. a maximum hook-firing depth). To bound fan-out further, a server MAY + restrict this subset to fire only on the data plane and not on accessor-mediated or + capability-mediated writes. +* **Subscriptions** bind a topic to a target verb. A subscription is an ordinary resource, created + and removed with the standard methods; a server that supports eventing invokes the target verb + when a matching event is published. A subscription is **read-gated** like an SSE stream + ({{event-sse}}), against the registering principal, both when it is created and at every delivery + ({{verb-subscriptions}}). +* **Schedules** bind a time or recurrence to a target verb in the same way, providing timer and + heartbeat behavior ({{schedules}}). + +A server-initiated invocation has no request caller; it executes with the **authority of the +principal that registered** the trigger or schedule, captured at registration time and attenuated +as the "Execution identity" section of {{RESTACT}} sets for server-initiated invocations, with cost attributed to that principal. Each firing is a +distinct invocation, atomic where the server's consistency level provides it (the "Consistency" section of {{RESTACT}}), +bounded by the usual limits (the "Resource Limits" section of {{RESTACT}}) and, for fan-out, by the composition rules +(the "Composition" section of {{RESTACT}}). + +**Replacing a hook's code.** Replacing the code of a lifecycle hook, which runs under its owner's +authority, MUST be performed by the owner, through every interface (`PUT …:verb/code`, rollback, and +re-registration): an authenticated non-owner receives `403`, whatever `$policy` grants (an +unauthenticated caller receives `401`, and where the "Verb declaration (deployment profile)" section +of {{RESTACT}} refuses a non-owner re-registration carrying `exec` with `400`, that refusal comes +first). This rule applies to every server advertising `lifecycle-hooks` and is not +gated on any delegation token. + +## Publishing events {#event-publish} + +The **event-publish capability** is a gated host capability (the "Capability Model" section of {{RESTACT}}), granted to a verb the +same way as composition and object-data access (deny-by-default; a deployment MAY withhold it from a +verb that declares it). It exposes one operation, +`publish(topic, name, data) -> result<_, invocation-error>`, which appends an +event (a name and a payload) to the named topic's event log. The topic MUST be a +client-addressable object path. Because publishing is an observable side effect, a **function MUST +NOT publish** (the "Verb invocation (the bare verb)" section of {{RESTACT}}); a server MUST refuse a publish attempt by a function with `403` +`forbidden-side-effect`. A server MAY additionally **auto-publish** a system event to an object's +topic when that object is mutated through the data plane, so subscribers observe mutations without a +guest hook. A server that auto-publishes these system events MUST name them after the corresponding +lifecycle hooks: `onCreate`, `onChange`, and `onDelete`. A server that supports the publish +capability advertises it in discovery (the "Discovery" section of {{RESTACT}}); a deployment MAY disable eventing entirely, +in which case the capability and the SSE surface ({{event-sse}}) are both withdrawn and the +discovery token is omitted. + +**Names and payloads.** An event name MUST be non-empty and MUST NOT contain a control character +(U+0000 through U+001F, or U+007F), because it travels as a line of the SSE framing +({{event-sse}}); a server MAY also bound its length, and documents the bound if it does. The `data` +argument MUST be empty or the text of a single JSON object {{RFC8259}}; empty `data` stands for the +empty object. That object MUST NOT have a top-level member whose name begins with `$`, since those +names belong to the server (below). A server MUST fail a publish that breaks any of these rules +with `invalid-input` and MUST NOT retain or deliver the event; a verb that returns that error +surfaces as `422` (the "Errors" section of {{RESTACT}}). + +**The publisher.** A server that supports eventing MUST add a `$publisher` member to the payload of +every event it publishes. The server sets it; it is never taken from the publisher: + +* `{"kind": "host"}` for an event the server publishes itself: an auto-published lifecycle event, + an event on a reserved host topic (below), and the gap signal of {{event-sse}}; +* `{"kind": "verb", "verb": ""}` for an event a verb publishes, where `` is the route + of the verb definition whose invocation called `publish`, as deployed (its definition pattern, + the "Verb Resolution and Inheritance" section of {{RESTACT}}). It is never the concrete path the verb was invoked on, which could name an + object the topic's readers may not read. `` travels as a JSON string: a server MUST + encode it with JSON's string escapes, never paste it into the payload text, because an object + path may contain `"` and `\`, and a pasted route could add members to `$publisher`, a second + `kind` among them. + +Apart from adding `$publisher`, the server MUST leave the payload as the publisher wrote it. A +client MUST ignore members of `$publisher` it does not recognize, and MUST treat an event that has +no `$publisher` member as unattested. The member identifies code, not a principal: it does not name +the principal that invoked the verb, which a verb can put in its own payload if it chooses. A verb +that publishes to a topic others can read therefore discloses its deployed route to them. +`$publisher` tells a client that receives an event from the server who published it; it is not a +credential. Input a verb receives, such as a hook's payload or a subscription delivery +({{verb-subscriptions}}), can be supplied by any caller permitted to invoke that verb directly. + +**Reserved host topics.** A server MAY publish its own operational lifecycle events — a checkpoint +starting and finishing, for instance — on topics in a **reserved namespace** of its own. Such a +topic is deliberately NOT a client-addressable object path: it is distinguished by a syntactic form +that the path grammar cannot produce, or one that the "Addressing" section of {{RESTACT}} reserves +and refuses in every client request, so that the rule above ("the topic MUST be a +client-addressable object path") makes the namespace unspeakable by a verb's `publish` and by the +data plane alike. That is what keeps it a one-way channel — by construction, rather than by an ACL +that could be misconfigured. For example, a server can use paths whose first segment begins with +`@`, which that section reserves; the reference implementation publishes checkpoint events on +`@host/checkpoint`. + +Because a reserved host topic has no backing object, the read gate of {{event-sse}} — the same +authorization as reading the object — has nothing to evaluate. A server MUST NOT treat that as +open: it MUST require an authenticated principal to subscribe to a reserved host topic, on any +deployment where authentication is configured at all. Verb subscriptions ({{verb-subscriptions}}) +MAY bind a target verb to a reserved host topic and fire under registrant authority exactly as for +any other topic; the same rule is their read gate, applied to the registering principal at +registration and again at every delivery. Both are read-side carve-ins only; neither creates a way +to publish into the namespace. A server that reserves such a namespace MUST document the reserved +form and the topics it publishes. + +A server that advertises the **`targeted-invalidation`** feature (the "Discovery" section of {{RESTACT}}) MUST auto-publish +the lifecycle event on every committed object mutation — a data-plane `PUT`/`DELETE` AND a verb's +object capability (`set`/`set-at`, `set-subject`/`set-subject-at`, `remove`/`remove-at`, and delete where a deployment profile +exposes one) alike, closing the base rule's data-plane-only scope for such a server. Its auto-published payload MUST be a JSON +object carrying at least an `object` member (the mutated object's path — the target this feature +turns on); a `subject` member (the triggering principal) MAY also be present. Where it is, its +value MUST be the real subject of the principal the write ran as, the same for every recipient, a +verb that the event is delivered to included ({{verb-subscriptions}}); it is never a pairwise +subject (the "Caller Identity" section of {{RESTACT}}; {{events-security}}). The event name is +carried on the transport as usual ({{event-sse}}), never inside this payload as a separate +requirement. The payload MAY carry an `actor` member, and MUST carry one for a mutation made under +delegation (the "Delegated tokens (OPTIONAL, feature `delegated-tokens`)" section of {{RESTACT-DELEGATION}}) on a server advertising `delegated-tokens` and +`targeted-invalidation`. + +**Removals.** A removal of a property that was set, whether by a `null` member of a data-plane `PUT` +(the "Extension specifications" section of {{RESTACT}}, E5; informative: the "Declared Data Properties" section of +{{RESTACT-OBJECTS}}) or by `remove` or `remove-at` (the "Object Data Access" section of {{RESTACT-OBJECTS}}), is a change of the object. Where +a server fires a lifecycle hook or auto-publishes a lifecycle event for the write, the removal is +`onChange`, never `onCreate` or `onDelete`, and the hook gates of {{events}} apply unchanged. A +removal never deletes the object, even when it removes the last data member, so it never fires +`onDelete`. Its event carries the members of any other change event, and like those it does not +name the property; a subscriber that needs to know what changed reads the object again. A `remove` +or `remove-at` that finds the property not set changes nothing and is not by itself a mutation of +the object, while a data-plane `PUT` stays a write whatever its `null` members find +(the "Object data (the noun)" section of {{RESTACT}}). + +### The read set of an invocation {#read-set-headers} + +The `targeted-invalidation` feature has a second, response-side half: scoped delivery is only useful +to a client that knows **which objects a rendered view actually depends on**. A server that +advertises the feature MUST report that dependency set on the response to an invocation whose +representation is `application/vnd.restact.ui+json` (presentation verbs, {{RESTACT-PRESENTATION}}), +using the response header + +~~~ +Restact-Read-Set: [, ]* +~~~ + +whose value is a comma-separated list of object paths (the "Addressing" section of {{RESTACT}}). The set is +**server-observed, not verb-declared**: it names the object paths the invocation read through the +object-data capability (the "Object Data Access" section of {{RESTACT-OBJECTS}}), including reads served by a page-granular query. A verb +declares nothing and needs no change to be covered; a server MUST NOT populate this header from any +value the verb or the request supplied, because a client uses it to decide what to re-fetch. + +The header is host-asserted metadata and MUST be carried as a response header, never injected into +the verb-authored representation: the document is untrusted verb output, and a client MUST NOT read +invalidation scoping out of it. + +**Disclosure filter, applied first.** The emitted set MUST contain only paths the **requesting +principal** could itself read directly — the same existence-and-read gate a data-plane `GET` on that +path would apply, evaluated against the requester, not against a switched execution principal +(the "Execution identity" section of {{RESTACT}}). A view running under `runs_as=owner` or registrant authority may legitimately +read objects its caller cannot; reporting those paths would disclose their existence and full path +to that caller. Such a caller's view is therefore under-invalidated on exactly those objects and +refreshes on the coarser ladder instead: the view may go stale, but no path is disclosed. + +**Bounds and overflow.** A server MUST bound the header. The bound for this version is **32 paths +and 2 KiB of header value, whichever binds first** (a bound chosen to stay well inside the header +budgets of ordinary reverse proxies). When the filtered set exceeds either bound, the server MUST +omit `Restact-Read-Set` and instead emit + +~~~ +Restact-Read-Set-Coarse: +~~~ + +whose value is the **deepest common ancestor of the already-filtered set** and means "any change +under this path invalidates this response". The coarse form MUST be a single, plain, grammar-valid +object path: never a wildcard or pattern form (the path grammar admits none, so a client validating +the value — as it MUST, both values being server-sent data — would reject it and silently fall back +to no invalidation at all), and never a truncated list (which would silently under-invalidate). The +exact/coarse distinction is carried by the **header name**, never by the value's grammar. The +filter-before-ancestor ordering is normative: computing the ancestor over an unfiltered set would +reintroduce, as a prefix, exactly the disclosure the filter removed. + +**Absent rather than empty, and absent rather than wrong.** Neither header has an empty form. A +server MUST omit both when it has nothing correct to report — an invocation that read no object at +all, a response replayed from an idempotency record rather than freshly computed, a filtered set +with no common ancestor to coarsen to, or any condition under which the server knows its observation +was incomplete. A client MUST treat the absence of both headers as "scope unknown" and fall back to +whatever unscoped refresh it would have performed without this feature; a server MUST NOT emit a +narrower value than it can justify, since an under-stated read set is silently stale rendering, +which is the failure this feature exists to prevent. + +Both header names are outside the CORS-safelist, so a server that supports browser clients +(the "Security Considerations" section of {{RESTACT}}) MUST expose them via `Access-Control-Expose-Headers` alongside the other REST:ACT +response headers it exposes. A server that does not advertise `targeted-invalidation` emits neither +header (the "Extension specifications" section of {{RESTACT}}), and a client that does not see the +token MUST NOT rely on them. + +## Delivering events to clients (SSE) {#event-sse} + +Delivery of events to *clients* (rather than to verbs) is a transport concern. A server that supports +eventing SHOULD support Server-Sent Events (the WHATWG/W3C `text/event-stream` mechanism): a `GET` on a topic's object path +with `Accept: text/event-stream` opens a live stream of that topic's events instead of returning the +object's representation (content negotiation on the data-plane `GET`). The stream is **read-gated by +the same authorization as reading the object** (the "Authorization and Identity" section of {{RESTACT}}): a client that could not `GET` the +object's representation MUST NOT receive its events. A server MUST evaluate that gate when the +stream opens and again for each event it delivers afterwards; the retained events it sends as the +stream opens, all published before that evaluation, MAY rely on it. Each of the topic's OWN events carries a +monotonic id; a client MAY request **replay** of the topic's own retained events it missed by sending +`Last-Event-ID` (or an equivalent query parameter), and the server resumes after that id. A +subscriber that sends no cursor is making no claim about what it has already seen: a server MAY +begin the stream with the topic's retained events, and MAY instead begin at the live tail. A client +that requires only new events MUST therefore be prepared to receive retained ones it has already +observed, and SHOULD coalesce or discard them rather than treating each as a distinct change. +Retention is bounded and server-defined; a server MAY drop the oldest events and SHOULD signal a gap to a +lagging subscriber. A server MAY bound the number and lifetime of concurrent subscriptions. + +**Delivery floor.** A server MUST NOT deliver an event published before the most recent of the +following on the topic's object, however the event reaches the delivery: by a replay with or +without a cursor, by a catch-up after a lost connection or a restart, as an arrival from another +node, as an event a verb published that the server held or deferred until the invocation returned, +as a retained event a subscription drains after a restart, or as a subtree frame. Any such +delivery made after the step that accepted the event is held to the floor exactly as a replay is, so +that the read gate a subscriber passes today never admits an event published under a different +object, or under an authorization the server has since changed. A reader admitted by a change the +floor records does not receive an event published before it. The floor is the most recent of: + +* the object's deletion: an event published while an earlier object existed at the path is never + sent to a subscriber of a later one; +* a write that sets, replaces or removes the object's own `$policy`, or that reassigns its + `$owner`; +* a write that changes a property that a `prop:` matcher reads in a rule of the object's own + `$policy` that covers `read` (the "Authorization policy" section of {{RESTACT}}), including, for + an inherited value, a write to the object that holds it; +* on a server that advertises `object-policy-inheritance` ({{RESTACT-OBJECTS}}), a write or + deletion that sets, replaces or removes the `$policy`, or reassigns the `$owner`, of an ancestor + that was the object's governing anchor before the change or is after it, and a write that changes + a member of the governing anchor that a `prop:` matcher reads in a rule of the anchor's `$policy` + that covers `read`. + +"Before" is the topic's own event order: the floor falls after every event the server accepted for +the topic before the change committed, and before every event it accepts after. The floor applies +whether the change widened or narrowed access: a server cannot tell which subscribers a change +admitted and which it shut out, so every such change ends the history a replay or a late delivery +may cross. A server MUST NOT count an event the floor hides in a gap's `missed`, and resumes a cursor older than the +floor from the floor. When the floor hides retained events from a subscriber that sent a cursor, +the server SHOULD signal a gap without a `missed` member, unless the replay starts at a later +object's `onCreate`, which needs no gap signal for what came before it. A server MUST establish the +floor before the deletion or authorization change takes effect, so that no replay or late delivery +after the change crosses it; a server that cannot record it refuses the change with `503` (`unavailable`) +rather than making it without one. + +An event a verb published is compared with the floor at the point its invocation began, not when +the server releases it: a floor established after the invocation began holds back every event the +invocation published, including a change the invocation itself commits. + +An event the floor hides from a late delivery is dropped and not counted. Where the delivery has a +gap signal, the server SHOULD send one gap per run of hidden events, without a `missed` member, and +only to a subscriber that passes the read gate for the topic; a reader that has lost read receives +nothing. No gap is sent for an event hidden by the deletion term, which belongs to an earlier +object. A subtree frame has no gap signal and is dropped silently, and a verb subscription skips the +delivery as one the read gate refuses. The per-event read gate above still applies to every delivery +the floor admits. An event delivered in the same step that accepts it needs no floor check. + +**Deletion ends a topic's history.** Each event on an object's topic belongs to the object that +existed at that path when the event was produced, and the floor's deletion term binds live delivery +too: once the object is deleted, a server MUST NOT deliver any of its events to a subscriber of a +later object at the same path, live or otherwise. A server MAY meet this by purging the topic's +retained events at the deletion, by recording a deletion boundary among them, or by an incarnation +identifier. An event produced at the path while no object existed there belongs to no object; a +server SHOULD NOT deliver it to a subscriber of a later object, and a replay that starts at that +object's `onCreate` does not. + +Each frame's data is the event's payload: a JSON object carrying the `$publisher` member of +{{event-publish}}. A server signals a gap with an event named `gap`, whose payload carries +`$publisher` with `kind` `host` and MAY carry a `missed` member giving the number of events the +subscriber did not receive. + +A server that advertises **`targeted-invalidation`** MAY additionally accept a `?scope=subtree` +parameter (or an equivalent mechanism) on the subscribe request: an opted-in connection additionally +receives the lifecycle event for any committed mutation under the subscribed topic (not only the +topic itself), disambiguated from the topic's own events by the payload's `object` member — no new +event name. A subtree-delivered frame MUST NOT carry an `id`: the transport's event ids are commonly +allocated from a single space shared across all topics, so stamping a descendant's (typically higher) +id onto a frame delivered to a different topic's subscription would corrupt that subscription's own +replay cursor. Consequently, subtree-delivered frames are **not** retained on the subscribed topic and +are **not** subject to the replay guarantee above — that guarantee covers only a topic's own events, +delivered on its own subscription. Delivery of a subtree event is gated exactly as an ordinary +subscription would gate a direct subscription to the mutated object — the same read-authorization +rule stated above, evaluated per delivered object, not merely once at subscribe time against the +topic. For a deletion, a server MUST evaluate that gate against the authorization the deleted object +would have had **immediately before** its removal (the object's own policy if it had one, else its +governing context, precisely as a `GET` issued an instant earlier would have been gated) rather than +refusing outright merely because the object no longer exists — the event describes a past state, and +the gate must describe the authority over that past state, not the object's absence. A late +subtree frame is also held to the delivery floor of the object it reports; the deletion term does +not hide a deletion's own frame from a subtree subscriber that passes the gate for it. + +A topic's own `onDelete` event on a stream opened on the topic itself is gated the same way: a server +MUST evaluate the gate against the authorization the object had immediately before its removal. A +subscriber that could have read the object just before the deletion receives the event, and one that +could not does not, as for every other delivery of `onDelete`. If the server cannot establish that +authorization, it MUST NOT deliver the event. + +## Verb subscriptions (OPTIONAL, feature `verb-subscriptions`) {#verb-subscriptions} + +A **verb subscription** binds a topic to a target verb ({{events}}): when an event is published on +the topic, the server invokes the target as a server-initiated invocation under the authority of the +principal that registered the subscription (its registrant), attenuated as {{events}} requires +and billed to that principal. A server that supports verb subscriptions advertises the +`verb-subscriptions` feature token (the "Discovery" section of {{RESTACT}}). Delivering an event to a verb discloses it exactly +as delivering it to a client does, so a verb subscription is read-gated by the same authorization as +an SSE stream ({{event-sse}}), evaluated at two points. + +**The registrant is the principal checked.** The read gate is evaluated against the registrant's +authority as it is attenuated for server-initiated execution (that attenuation keeps only the +subject, so a grant the registrant holds only through a role, group, scope, or claim does not admit +it). It is NOT evaluated against the execution identity the target verb runs under: a target that +runs as its owner (the "Execution identity" section of {{RESTACT}}) does not widen what the registrant may subscribe to, and the +server MUST NOT admit a registration or a delivery because the target's owner could read the topic. +The registrant chooses where the topic's events go, so the registrant's authority is what bounds +them; a target's execution identity can also change after registration (a redeploy, or a more +specific definition that later shadows a wildcard one, the "Verb Resolution and Inheritance" section of {{RESTACT}}). + +**Attenuation never escapes a `deny` rule.** The attenuated registrant is subject to the rule of +the "Authorization and Identity" section of {{RESTACT}}: on a server that accepts `deny` rules, a `deny` keyed on a role, group, scope, or claim +matches it, at registration and at every delivery. + +**At registration.** A server MUST refuse to create a subscription whose topic object the requesting +principal is not authorized to read (the "Authorization and Identity" section of {{RESTACT}}), and MUST give an absent topic and an unreadable +topic the same refusal: `404` `not-found`, the refusal a `GET` of the topic gives the same principal +(the "Refusing a caller who may not read" section of {{RESTACT}}). A subscription to a topic that does not exist yet is therefore refused; the topic object +is created first. When the requester is authorized to read the topic but the attenuated registrant +authority is not, the server MUST refuse the registration, and SHOULD do so with `403` `forbidden`, +since that refusal discloses nothing the requester could not already learn by reading the topic. A reserved host topic +({{event-publish}}) has no backing object; it is subscribable only by an authenticated principal on +a deployment where authentication is configured, as for SSE. + +**At every delivery.** Before it invokes the target for an event, a server MUST evaluate the read +gate again, against the registrant and the authorization in force when the delivery is made — not +the authorization in force when the subscription was registered. A policy change, the revocation or +granting of a read, a change to the topic's governing context (the "Prefix-inherited object policy" section of {{RESTACT-OBJECTS}}), and +the topic's deletion therefore take effect at the next delivery, in both directions. For a deletion +event on the topic, the gate is evaluated against the authorization the topic had immediately before +its removal, exactly as for a subtree deletion over SSE ({{event-sse}}); if the server cannot +establish that authorization, it MUST NOT deliver. A subscription binds a path, not an object +identity: events for an object later re-created at the same path are gated by that object's own +authorization. The rule of {{event-sse}} that deletion ends a topic's history binds these +deliveries too, including a catch-up after a lost connection and a restart's drain of retained +events, and so does the delivery floor. + +**A refused delivery is skipped.** It is not delivered, not retried, and not deferred. The target is +not invoked, no quota or cost is charged to the registrant, and the skip MUST NOT consume any +per-subscription rate allowance the server applies (such as a minimum interval between deliveries), +so that it never suppresses a permitted delivery of a later event. A skip is final: a server MUST +NOT deliver a skipped (subscription, event) pair later — including through a replay, a catch-up, or +a restart's drain of retained events — even if the registrant has since become authorized to read +the topic. A server that deduplicates deliveries across nodes can meet this by recording a skipped +pair exactly as it records a delivered one. A skip MUST NOT be observable to the registrant +through the subscription resource or any other surface (a skip count or timestamp would itself +disclose that the unreadable topic changed). A server SHOULD record each skip in an operator-facing +log identifying the subscription and the registrant; any such record MUST NOT carry the event's +payload, its name, or the principal that caused it. + +A subscription registered before a server enforced this gate remains registered and is subject to +the delivery gate from then on; a server is not required to delete or re-validate it. + +A server that advertises `verb-subscriptions` MUST implement both gates and MUST also advertise the +**`verb-subscriptions-read-gate`** feature token. A client that sees `verb-subscriptions` without +`verb-subscriptions-read-gate` is talking to a server that predates this rule and MUST NOT assume +that subscriptions are read-gated. + +### The subscription resource {#subscription-resource} + +A subscription is a registration ({{registrations}}) in the collection `/v1/subscriptions`. The +body of a request creating one is a JSON object with these members and no others: + +* `target` (string, REQUIRED): the route of the action to invoke ({{registrations}}). +* `topic` (string, REQUIRED): an object path (the "Addressing" section of {{RESTACT}}) or a + reserved host topic ({{event-publish}}). A server MUST refuse any other value with `400` + `invalid-input`; for a topic it accepts, the read gate at registration (above) applies. +* `event` (string, OPTIONAL): an event name. When it is present, only events of that name are + delivered; when it is absent, every event on the topic is. + +An event matches a subscription when it is published on the subscription's topic itself, not on a +descendant of it, and has the subscription's `event` name if one was given. The representation of a +subscription carries the members {{registrations}} gives every registration, with `topic`, and +`event` when one was given. + +**The input of a delivery.** A server MUST pass the target, as its input, a JSON object with +these members: + +| Member | Value | +|---|---| +| `event` | the event's name | +| `topic` | the topic the event was published on | +| `data` | a JSON string holding the text of the event's payload, `$publisher` member included ({{event-publish}}) | +| `seq` | the event's id: the value an SSE stream gives the event in its `id` field ({{event-sse}}) | +| `subscription` | the subscription's `id` | + +The payload travels as text and unchanged, so the target receives exactly what an SSE client of the +topic does. The input is informational: any principal that may invoke the target directly can +supply the same input, so a target can rely on `$publisher` only when its execute policy admits no +such caller. + +## Schedules (OPTIONAL, feature `schedules`) {#schedules} + +A **schedule** binds a recurrence to a target action ({{events}}): each time the schedule falls +due, the server invokes the target as a server-initiated invocation under the authority of the +principal that registered it (the **registrant**), attenuated as {{events}} requires and billed to +that principal. A schedule is a registration ({{registrations}}) in the collection +`/v1/schedules`. A server that supports schedules advertises the `schedules` feature token (the +"Discovery" section of {{RESTACT}}). + +**The create request.** Its body is a JSON object with these members and no others: + +* `target` (string, REQUIRED): the route of the action to invoke ({{registrations}}). +* `intervalSeconds` (integer, REQUIRED): the period in seconds. A server MUST refuse with `400` + `invalid-input` a period shorter than its floor, the shortest period it accepts. The floor is + server-defined and SHOULD be documented; it bounds how fast one registration can spend its + registrant's resources. + +**The representation** carries the members {{registrations}} gives every registration, with +`intervalSeconds` as registered, and: + +* `lastFiredAt` (integer): the time of the schedule's latest firing, which is that firing's + `firedAt` (below). It is absent until the schedule first fires. +* `nextFireAt` (integer): the time the schedule next falls due. It is a due time, not a promise: + the schedule fires at or after it, and it is in the past while a due firing waits. + +**When a schedule fires.** A schedule falls due one interval after it is created, and then one +interval after each firing's `firedAt`. A server MUST NOT fire a schedule before it is due, SHOULD +fire it promptly once it is, and MAY fire it later, for example under load or while an earlier +firing of the same schedule is still running. Firing is **at most once**: + +* A due time yields at most one firing, even on a server of several nodes, and a firing is never + retried, whether its target fails or the server stops while it runs. The next firing is the one + for the next due time. +* When one or more due times pass while the server cannot fire the schedule (it is stopped, or the + firing waits), the server fires the schedule once, not once per due time missed, and the + schedule next falls due one interval after that firing. + +**The input of a firing.** A server MUST pass the target, as its input, a JSON object with these +members: + +| Member | Value | +|---|---| +| `event` | the string `schedule` | +| `schedule` | the schedule's `id` | +| `target` | the schedule's `target` | +| `firedAt` | the time the server took this firing, which becomes the schedule's `lastFiredAt` | +| `dueAt` | the due time this firing serves, never later than `firedAt`; for a firing that covers several due times, the earliest | + +A target that must tell a late firing from a punctual one compares `firedAt` with `dueAt`. The +input is informational ({{registrations}}). + +## Registration resources {#registrations} + +Subscriptions ({{verb-subscriptions}}) and schedules ({{schedules}}) are **registrations**: each +binds a trigger to a target action, is created and removed with the standard methods, and fires as +a server-initiated invocation ({{events}}). A server that advertises `schedules` serves these +requests: + +| Request | Result | +|---|---| +| `POST /v1/schedules` | `201` with the new schedule's representation, and a `Location` header naming its item `/v1/schedules/{id}` (a URI reference that resolves under the server's base URL: the "Base URL" section of {{RESTACT}}) | +| `GET /v1/schedules` | `200`, the caller's own schedules, in a body `{"schedules":[…]}` | +| `GET /v1/schedules/{id}` | `200` with the representation, or `404` `not-found` when the schedule is absent or is not the caller's: one answer for both | +| `DELETE /v1/schedules/{id}` | `204`; the schedule is removed. Absent, or another's: `404` as for `GET`. | + +A server that advertises `verb-subscriptions` serves the same four requests on `/v1/subscriptions`, +with a list body `{"subscriptions":[…]}`. Both collections follow these rules: + +* **Owned by the registrant.** The principal that creates a registration is its registrant. Only + the registrant can list, read or delete it; any other principal, and an id that does not exist, + gets the same `404`, so an id is no existence oracle. An id is opaque and SHOULD be unguessable. +* **No anonymous registrations.** On a deployment where authentication is configured, a server + MUST refuse an anonymous caller's create or delete with `401` (the "Authorization and Identity" + section of {{RESTACT}}), and the anonymous principal owns no registration: its list is empty and + every item answers `404`. +* **No sub-tokens.** A server MUST refuse a path-scoped sub-token (the "Path-scoped sub-tokens + (OPTIONAL, feature `path-scoped-tokens`)" section of {{RESTACT-DELEGATION}}) with `403` + `forbidden` on every request in this section: each firing would run with the authority of the + principal that minted the token, not with the token's own, and would outlive it. A request made + under delegation is bound by the "Delegated tokens (OPTIONAL, feature `delegated-tokens`)" + section of {{RESTACT-DELEGATION}}, which also governs the firings of a registration it creates. +* **Immutable.** A registration has no update. A server MUST answer `PUT` and `PATCH` on a + registration with `405` (`method-not-allowed`) and an `Allow` field that names `GET` and `DELETE` + and names neither `PUT` nor `PATCH` (it MAY name others the resource supports, such as `HEAD` and + `OPTIONS`); a client changes a registration by deleting it and creating another. +* **Strict create bodies.** A server MUST refuse with `400` `invalid-input`, creating nothing, a + create body that is not a JSON object {{RFC8259}}, that lacks a REQUIRED member, that has a member + whose value is not of the type its definition gives (`null` included), or that has a member this + document does not define for that resource. A member of the representation that the server + writes, such as `id` or `createdAt`, is not a member of the request, and neither is a member + defined by an optional feature the server does not advertise. A client can therefore send a + member that a later feature adds: a server that does not know it refuses the request rather than + creating a registration that ignores it. An integer member is a JSON number written without a + fraction or an exponent. +* **The target.** `target` is a verb route (the "Addressing" section of {{RESTACT}}). A firing is a + side effect, so the target is an action (the "Verb invocation (the bare verb)" section of + {{RESTACT}}): a server MUST refuse with `400` `invalid-input` a target whose object part is not an + addressable object path, one that resolves to no verb (the "Verb Resolution and Inheritance" + section of {{RESTACT}}), and one that resolves to a function. A server SHOULD refuse with `403` + `forbidden` a target whose execute policy does not admit the registrant as attenuated for a + server-initiated invocation ({{events}}), since no firing of it could run. A registration binds a + route, not a verb definition: each firing resolves the route again and is authorized against the + target's execute policy in force at that firing. +* **A bound per principal.** A server SHOULD bound the number of registrations of each kind that + one principal holds, and refuses a create beyond the bound with `429` `quota`. That response + carries no `Retry-After`: the bound does not lapse with time, only when the principal deletes a + registration. +* **Times.** Every time in a representation or a firing's input is an integer number of seconds + since 1970-01-01T00:00:00Z, leap seconds not counted (Unix time). +* **The representation.** Every registration's representation carries `id` (string), the last + segment of its item path; `target` as registered; `createdAt` (integer), the time it was created; + and the members its own section adds. It MAY carry other members, and a client MUST ignore a + member it does not recognize. +* **Firing.** Each firing is a distinct invocation of the target as an action, through the server's + ordinary invocation path, under the registrant's attenuated authority, billed to the registrant + and bound by the usual limits ({{events}}; the "Resource Limits" section of {{RESTACT}}). The + input its section defines is informational: any principal that may invoke the target directly + can supply the same input. A firing that fails is not retried; how it ended is recorded only + where the server advertises firing outcomes ({{registration-outcomes}}). +* **Removal.** Once a `DELETE` of a registration answers `204`, the server MUST NOT start another + firing of it, on any node and after any restart. A firing already started MAY finish. +* **Switched off.** A server that implements one of these resources but does not advertise its + feature token, for example because an operator has switched the feature off, MUST refuse a create + with `501` `unsupported-feature` and MUST NOT fire a registration of that kind. + +### Firing outcomes (OPTIONAL, feature `registration-outcomes`) {#registration-outcomes} + +A server that advertises the `registration-outcomes` feature token (the "Discovery" section of +{{RESTACT}}), which it does only alongside `schedules` or `verb-subscriptions`, records how the +latest firing of each schedule and subscription it serves ended, in three members of the +registration's representation: + +* `lastOutcome` (string): `ok` when the target ran and succeeded; `error` when the server took the + firing and it failed, because the target returned an error, trapped or exceeded a limit, or + because the server could not run it; `skipped` when the server took the firing but did not invoke + the target, because the registrant was over its quota or because the delegation grant the + registration follows did not allow it (the "Delegated tokens (OPTIONAL, feature + `delegated-tokens`)" section of {{RESTACT-DELEGATION}}). Absent until the first outcome. +* `lastError` (object): `{"code": , "at": }` for the latest firing that ended + `error` or `skipped`, where `at` is the time the server took that firing (for a schedule, its + `firedAt`); for consecutive `skipped` firings with the same code, `at` MAY stay at the first of + them. Absent until a firing ends `error` or `skipped`. A later `ok` does not clear it: a + server MUST keep `lastError` until a later `error` or `skipped` firing replaces it, so the + registrant can see when and how the target last failed. +* `consecutiveFailures` (integer): the number of firings that ended `error` since the latest `ok`. + An `ok` resets it to 0 and a `skipped` leaves it unchanged. A client MUST read an absent member + as 0. + +**The code.** `code` names the failure from a closed vocabulary, the values of the "REST:ACT Error +Codes" registry (the "Errors" section of {{RESTACT}}). When the code the server would give the same +failure on a direct invocation is a registered value, `code` is that value; a skip records `quota` +or `delegation-bound`. Otherwise `code` is `application-error` for a failure that arose in the verb, +such as an error code of the verb's own choosing, and `internal` for any other failure, such as a +fault in the server itself. Both are core codes; `application-error` appears only in a firing +outcome, never in a response. A server MUST NOT store or return any other text about a failure: not +the error's message or detail, not an unregistered code the target chose, and not the target's +output. The registrant is not always the target's author (the target can be another principal's +verb, or run as its owner, the "Execution identity" section of {{RESTACT}}), and an error's text can +carry data the registrant may not read, or the server's own internals; a code from a closed list +carries neither. + +**Firings only.** A delivery the read gate refuses ({{verb-subscriptions}}) is not a firing and MUST +NOT change any of these members, since a change would tell the registrant that a topic it may not +read had an event. Nor does an event the server drops before taking a firing for it, such as one +inside a minimum interval between deliveries, change them. When firings of one registration +overlap, a server SHOULD NOT let the outcome of one replace the outcome of a firing it took later. +A server that shares registrations across nodes and writes nothing for an `ok` that follows an +`ok` cannot always tell; the next firing's outcome corrects the members. + +**Read-only.** Only the server writes these members. A create request carrying one is refused like +any member the request does not define ({{registrations}}), and no request sets them. + +# Security Considerations {#events-security} + +* **Autonomous execution.** Hooks, subscriptions and schedules run without a connected client, so + an event storm or a runaway schedule spends its registrant's resources. The + "Security Considerations" section of {{RESTACT}} bounds every server-initiated invocation by its + registrant's quota and the per-invocation limits. +* **Disclosure through subscriptions.** An event carries metadata (that an object exists, when it + changed, and who changed it) and may carry content a verb published. A verb subscription is a + standing delivery channel with no lifetime bound, so a server MUST read-gate it against its + registrant at registration and at every delivery ({{verb-subscriptions}}); a gate at registration + alone would let a revoked reader keep receiving a topic's events indefinitely, and a gate keyed to + the target verb's execution identity would let any principal route a topic into a runs-as-owner + verb whose owner can read it. A lifecycle hook is the same kind of channel, which is why it is + read-gated against its registrant ({{events}}). +* **Who changed an object.** A lifecycle hook's input and a lifecycle event can name the principal + a write ran as, and an event names its actor under delegation. These are real identifiers, as + the provenance facet (the "The provenance facet (OPTIONAL, feature `object-provenance`)" section of {{RESTACT-DELEGATION}}) + holds them, and each is released on the authority of a principal that may read the object: a + client's own, or the registrant's of a hook or a subscription. The pairwise subject of + the "Caller Identity" section of {{RESTACT}} is not used for them. It keeps a verb's author + from learning who the verb's callers are. Whoever changes an object is not a caller of the hook + or of the verb an event reaches, and the store names principals by real subject throughout, as + in the policy that admitted the write. If a server named the writer by a pairwise subject to + some recipients, an owner who also learned the real one, from the facet or as a client of the + same event, would hold two names for one act and could pick the writer out among the callers of + its own verbs. So a hook or an event names the writer by real subject or not at all. Three + things follow. The code that receives the subject needs no capability, so a verb's `interfaces` + do not show that it learns who writes an object. A registrant who subscribes another owner's + verb gives that verb whatever the events carry, the writer's subject included; if the registrant + is the writer, the verb reads the registrant's pairwise subject in the same frame and can pair + the two. And `actor()` does not name the actor of a delegated write to a hook unless the server + discloses the real identity (the "Delegated tokens (OPTIONAL, feature `delegated-tokens`)" + section of {{RESTACT-DELEGATION}}); the hook's owner learns who it is as any reader of the object + does, from the event or the provenance facet. An operator who does not want a reader to learn who changes an + object leaves the identity out of hook input and the `subject` member out of payloads, and does + not offer the provenance facet; the `actor` of a delegated write stays in the event. +* **Late delivery after a revocation.** Retained events outlive the authorization they were + published under, so replay discloses the history of a topic, not only its current state, and so + does any delivery made after the step that accepted the event: an arrival from another node, a + held or deferred publish, a restart's drain. The per-event read gate alone would not stop these, + because it is evaluated at delivery time. The delivery floor ({{event-sse}}) cuts that history at + a deletion and at every change the server makes to what governs a read of the object: its own or + its governing policy and owner, and a property that a `prop:` matcher in that policy reads. A + reader admitted by such a change does not receive an event published before it. The floor cannot + see a change made elsewhere: a role, group, scope or claim that an identity provider removes from + a subscriber and later restores, or a change to the server's default policy. Nor does it cover a + change that concerns the subscriber rather than the object, such as issuing or revoking a + delegation grant. A subscriber denied and later re-admitted in either way can receive events + published in between; a deployment that relies on such revocations SHOULD keep retention short, + since a subscriber that sends an old cursor can replay whatever is retained since the last change + the floor records. The gap a floor causes carries no content or count, but tells a re-admitted + subscriber that the topic had events it does not receive. +* **Forged events.** Publishing needs no authority over the topic, so any verb that may publish can + reach any topic it can address, and the topic's readers act on what arrives. A server therefore + keeps the lifecycle and gap names to itself (the "Grammar" section of {{RESTACT}}) and attests the + publisher of every event ({{event-publish}}). A client that acts on an event's content checks `$publisher` first, and a + verb that consumes events through its input remembers that its input can come from any caller + its execute policy admits. +* **Firing outcomes.** The outcome of a firing is shown to the registrant, who is not always the + target's author and may not read what the target read. A server therefore records a code from + a closed list, never the target's text, and records nothing for a delivery the read gate + refuses ({{registration-outcomes}}). + +The security considerations of {{RESTACT}} apply. + +# IANA Considerations {#events-iana} + +This document requests the following registrations in registries that {{RESTACT}} creates. It +creates no registry. + +* In the "REST:ACT Feature Tokens" registry: the tokens in the table of {{events-relationship}}, + with `events` registered as reserved. +* In the "REST:ACT Capability Interfaces" registry: `rest-act:plugin/event` ({{event-publish}}). diff --git a/src/content/spec/draft-byrd-restact-http-verbs-00.md b/src/content/spec/draft-byrd-restact-http-verbs-00.md new file mode 100644 index 0000000..e33950c --- /dev/null +++ b/src/content/spec/draft-byrd-restact-http-verbs-00.md @@ -0,0 +1,1249 @@ +--- +title: "REST:ACT HTTP Verbs" +abbrev: "REST:ACT HTTP Verbs" +docname: draft-byrd-restact-http-verbs-00 +category: exp +submissiontype: independent +ipr: trust200902 +area: "Applications" +keyword: + - REST + - WebAssembly + - webhooks + - capability security +stand_alone: yes +pi: [toc, sortrefs, symrefs, comments] +author: + - + ins: N. Byrd +normative: + RFC2104: + RFC3986: + RFC4648: + RFC6234: + RFC6266: + RFC8187: + RFC8259: + RFC9110: + RFC9111: + RESTACT: + title: "The REST:ACT Protocol: Invoking Sandboxed Functionality over REST" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-protocol-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-protocol-00.md + RESTACT-CONNECTORS: + title: "REST:ACT Connectors" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-connectors-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-connectors-00.md + UNICODE: + title: "The Unicode Standard" + author: + - + org: The Unicode Consortium + target: https://www.unicode.org/versions/latest/ + WHATWG-URL: + title: "URL (WHATWG Living Standard)" + target: https://url.spec.whatwg.org/ +informative: + RFC7240: + RFC8126: + RFC9421: + RESTACT-OBJECTS: + title: "REST:ACT Objects and Data" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-objects-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-objects-00.md + RESTACT-EVENTS: + title: "REST:ACT Events" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-events-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-events-00.md + RESTACT-MCP: + title: "REST:ACT Model Context Protocol Facet" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-mcp-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-mcp-00.md + GITHUB-WEBHOOKS: + title: "Validating webhook deliveries (GitHub Docs)" + target: https://github.com/github/docs/blob/44442041dd7f/content/webhooks/using-webhooks/validating-webhook-deliveries.md + STRIPE-WEBHOOKS: + title: "Receive Stripe events in your webhook endpoint: verify webhook signatures (Stripe Documentation)" + date: 2026-10-27 + target: https://web.archive.org/web/20261027051205/https://docs.stripe.com/webhooks + SLACK-SIGNING: + title: "Verifying requests from Slack (Slack Developer Docs)" + date: 2026-10-06 + target: https://web.archive.org/web/20261006064553/https://docs.slack.dev/authentication/verifying-requests-from-slack/ + STANDARD-WEBHOOKS: + title: "Standard Webhooks Specification" + target: https://github.com/standard-webhooks/standard-webhooks/blob/ab6844147ce9cdb0d2dbf2e60d1ea85001fd2554/spec/standard-webhooks.md + +--- abstract + +This document specifies an optional extension to REST:ACT, the protocol for invoking sandboxed +verbs over HTTP. Under it a verb can read the request header fields it declares and set its own +response status, a small set of response header fields and its content type, within limits that +keep the server's own refusals, caching and origin-wide state out of a verb's reach. A second, +separately advertised feature lets a deployer gate a verb behind webhook signature verification +that the server performs before the verb runs, with replay protection and a cost account of its +own. A server advertises each feature with its own token. + +--- middle + +# Introduction {#http-introduction} + +A REST:ACT {{RESTACT}} verb answers with a body. The server chooses the status, the header fields +and, from the verb's declaration, the content type: a successful invocation answers `200`, and a +refusal is a Problem Details document that the server writes. That is enough for a verb that +computes a value. It is not enough for a verb that implements an HTTP resource of its own, such as +one that answers `201 Created` with a `Location`, offers a download under a file name, redirects a +browser after a form post, or receives a webhook, whose sender reads only the status and whose +authenticity rests on a signature in a header field. + +This document defines two optional features: + +* **HTTP verbs** ({{http-guest}} through {{http-codes}}): a verb deployed with the `http` + declaration reads the request header fields it declared and sets its own status, a closed set of + response header fields and a content type from the set it declared. +* **Webhook verification** ({{http-webhooks}}): a verb deployed with `verify` runs only for a + request whose signature the server has verified under a registered scheme, once per signed + delivery, and the compute cost of the delivery is charged to an account of the verb's owner + rather than to the anonymous sender. + +The threat model is that of {{RESTACT}}: the verb, its declarations and every request are +possibly hostile. Every rule below exists so that a verb that controls its own response still +cannot speak for the server, change state that outlives its own response, or reach a credential +that the caller's request carried. + +## Relationship to REST:ACT {#http-relationship} + +This document is a REST:ACT extension, as described in the "Extension specifications" section of +{{RESTACT}}. Its server requirements bind a server that advertises the token that covers the +mechanism they constrain: `verb-http-handler` for {{http-guest}} through {{http-codes}}, and +`webhook-verification` for {{http-webhooks}}. The rules in {{http-features}} for a verb that a +server holds while it does not advertise the token covering it constrain a mechanism that neither +token covers, and bind every server that holds such a verb. A requirement that also names a feature +of another document, such as an accessor verb, binds a server that this document binds when that +server also offers that feature. A client does not assume any behavior of this document from a +server that does not advertise its token. + +| Feature tokens | Section | +|---|---| +| `verb-http-handler` | {{http-guest}}, {{http-deploy}}, {{http-request}}, {{http-response}}, {{http-entries}}, {{http-discovery}}, {{http-codes}} | +| `webhook-verification` | {{http-webhooks}} | + +This document relaxes requirements of {{RESTACT}} at two of the extension points that the +"Extension specifications" section of {{RESTACT}} names, and only while the token is advertised: + +* E12, a verb's own response: an HTTP verb sets its status and content, and a status of `400` or + more carries the verb's own content rather than Problem Details ({{http-response}}), including + in the tool result of the Model Context Protocol facet of {{RESTACT-MCP}} ({{http-entries}}); +* E13, cost attribution: the compute cost of a verified delivery is attributed to the verb owner's + webhook account ({{http-webhook-cost}}). + +It also relies on two rules of {{RESTACT}} without relaxing them: the "Consistency" section of +{{RESTACT}} counts as a verb's error return any return that an advertised extension defines as one, +and this document defines a status of `400` or more as one, at every consistency level +({{http-commit}}); and the +"Verb declaration (deployment profile)" section of {{RESTACT}} requires a server to refuse a +deployment parameter it does not recognize, so a server that does not implement this document +refuses `verify` rather than deploying an unverified receiver. + +{::boilerplate bcp14-tagged} + +# Terminology {#http-terminology} + +The terms of {{RESTACT}} apply. This document also uses: + +HTTP verb: +: A verb deployed with the `http` declaration ({{http-deploy}}). + +Route entry: +: An invocation that a request to a verb's route, `:`, starts, as the "Verb + invocation (the bare verb)" section of {{RESTACT}} defines it. Its root frame is the only frame + that sees the request. + +Synthetic request: +: What every other frame sees in place of the request: no header fields, no query, and a method + ({{http-request}}). + +Verify-gated verb: +: A verb deployed with `verify` naming a webhook scheme ({{http-verify-deploy}}). + +Scheme: +: A registered rule for verifying a webhook signature: the header fields it reads, the content it + signs and the key it uses ({{http-schemes}}). + +Verified delivery: +: A request to a verify-gated verb's own route whose signature the server verified under the + verb's scheme and key before the verb ran ({{http-verify-order}}). + +Webhook account: +: The account to which a server attributes the cost of verified deliveries, one for each principal + that owns a verify-gated verb ({{http-webhook-cost}}). + +# Feature tokens and absent servers {#http-features} + +A server that offers HTTP verbs MUST advertise `verb-http-handler`. A server that offers webhook +verification MUST advertise `webhook-verification`, and MUST NOT advertise it unless it also +advertises `verb-http-handler` and `secrets-management` (the "The mediated secrets mount (OPTIONAL, +feature `secrets-management`)" section of {{RESTACT-CONNECTORS}}). `verb-http-handler` depends on +no other feature. + +While a server does not advertise a token, it emits no discovery member, deployment parameter, +response header field or code that the token covers. In particular: + +* A component that imports the `request` or `response` interface is refused at upload, as the + "The guest contract (WIT)" section of {{RESTACT}} requires for an import the server does not + grant. +* A deployment that carries a parameter of {{http-deploy}} is refused as carrying an unrecognized + parameter (`400`, `invalid-input`, naming the parameter), as the "Verb declaration (deployment + profile)" section of {{RESTACT}} requires, so a server never deploys an unverified receiver + because it ignored `verify`. +* A server MUST NOT invoke an HTTP verb that it holds while it does not advertise + `verb-http-handler`, or a verify-gated verb that it holds while it does not advertise + `webhook-verification`. It answers every invocation of such a verb, through every entry, with + `501` (`unsupported-feature`) naming the missing token, before the verb runs, and omits the verb + from its discovery document and from the OpenAPI document of the "Discovery" section of + {{RESTACT}}. A verify-gated verb therefore never runs unverified, and an HTTP verb never runs as + a verb whose response the server would serve without the rules of this document. + +A client SHOULD check discovery for a token before it sends a parameter that the token covers. + +# The guest contract {#http-guest} + +A server that advertises `verb-http-handler` adds two gated interfaces to the WIT package +`rest-act:plugin`, `request` and `response`, and four worlds that add both to a world of the +package, as the "The guest contract (WIT)" section of {{RESTACT}} provides for a new capability. A +verb keeps its `invoke` export, and its returned payload is the response body. The interfaces, as +the package carries them: + +~~~ wit +interface request { + use types.{invocation-error}; + + /// The method of the request that started this frame, or the + /// method of the synthetic request every other frame sees. + method: func() -> string; + + /// The value of a request header field that the verb declared + /// in `request_headers`, matched case-insensitively; none when + /// the request does not carry it. An undeclared name is an + /// error (`invalid-input`) that names `request_headers`. + header: func(name: string) + -> result, invocation-error>; +} + +interface response { + use types.{invocation-error}; + + /// Set the response status. Refused (`invalid-verb-response`) + /// when the status is outside what this verb may answer. + set-status: func(status: u16) -> result<_, invocation-error>; + + /// Set a response header field from the allowed set. + set-header: func(name: string, value: string) + -> result<_, invocation-error>; + + /// Set the content type, one of the verb's declared types. + set-content-type: func(value: string) + -> result<_, invocation-error>; +} + +world plugin-http-handler { + include plugin; + import request; + import response; +} +~~~ + +The other four worlds take the same form, each named for the world it extends with the suffix +`-http-handler`: `plugin-object-http-handler`, `plugin-object-compose-event-http-handler`, +`plugin-object-compose-event-llm-http-handler` and, on a server that advertises +`webhook-connector` ({{RESTACT-CONNECTORS}}), `plugin-object-compose-event-llm-webhook-http-handler`, +the last being the superset. No other world of the package gains a counterpart. An author whose +verb needs another combination builds it against the smallest of the five that includes it, and the component imports only the interfaces it uses. A +verb's descriptor (the "Discovery" section of {{RESTACT}}) lists among its `interfaces` each of +`request` and `response` that it imports, and names as its `world` the `-http-handler` world named +for the world it would name without them, or that world itself when none of the five is named for +it. + +A component's imports do not make it an HTTP verb; its deployment does ({{http-deploy}}). A server +MUST refuse, with `400` (`invalid-input`) naming the `http` parameter, the deployment of a component +that imports `request` or `response` without the `http` declaration. A verb in a source-only +language runs in the server's shared runtime component, whose imports do not describe the verb +(the "Verb code: source and executable" section of {{RESTACT}}), so for it the declaration alone +decides, and the server enforces it at the host boundary. Such a verb deployed without the `http` +declaration holds neither interface: its call of any function of `request` or `response`, +including `method()`, ends the invocation, and the server answers `500` (`trap`): the fault is in +the verb's code, not in the request. + +**Setters.** Each setter validates its argument when it is called, against the rules of +{{http-response}} that the argument alone decides, and the server validates the assembled response +when the verb returns, against the rules that depend on more than one part of it (a `Location` +with its status, a body with `204`). A later call of a setter replaces the value an earlier call +set. A setter that the server refuses returns an error whose code is `invalid-verb-response`, and +the refusal is sticky: once a setter has been refused, the invocation's outcome is `500` +(`invalid-verb-response`), with a detail that repeats the first refusal, whatever the verb then +sets or returns, unless the invocation ends in a trap or a limit failure, whose outcome is then +that one. A setter called by a frame of a verb that is not an HTTP verb is refused the same way. + +**Frames.** Each frame of an invocation tree keeps its own response state. Only the state of the +root frame of a route entry becomes the HTTP response; the outcome of any other frame is used as +{{http-entries}} sets. A verb that returns an `invocation-error`, traps or exceeds a limit +discards what it set, and the server answers as {{RESTACT}} sets for that outcome. + +# Deployment parameters {#http-deploy} + +A server that advertises `verb-http-handler` and serves the reference deployment profile (the "Verb +declaration (deployment profile)" section of {{RESTACT}}) MUST accept the following query +parameters of `POST /v1/modules`, and MUST provide an equivalent in every deployment interface it +offers: + +* `http`: `true` declares the verb an HTTP verb; `false`, or the parameter's absence, declares + it not one. +* `request_headers`: the request header fields the verb reads, as a comma-separated list of field + names ({{RFC9110}}, Section 5.1), each matched case-insensitively. At most 16 names, each + inside the server's ceiling and outside the fixed deny ({{http-request}}). An empty value + declares none. +* `http_produces`: the media types the verb may set besides its `produces` type, as a + comma-separated list. Each MUST be exactly one media type, with no comma and no control + character, and MUST NOT be one that only the server writes ({{http-content-type}}). At most 16 + types. +* `redirects`: the verb's redirect grant ({{http-location}}): `none` (the default), + `same-origin` or `listed-origins`. +* `verify` and `verify_secret`: webhook verification, under `webhook-verification` only + ({{http-verify-deploy}}). + +A server MUST refuse a deployment, deploying nothing, with `400` (`invalid-input`) and a detail +that names the parameter, when `request_headers`, `http_produces` or `redirects` is present without +`http=true`, when a value breaks the rule above, or when the verb's name is one of the accessor +names that the "Active Properties (Accessor Verbs)" section of {{RESTACT-OBJECTS}} reserves and +`redirects` is other than `none`. A name outside the server's ceiling is refused with the detail +"not in this server's request-header allowlist", the same words wherever that refusal appears; a +name on the fixed deny is refused in the same words, so the refusal does not tell the deployer +which names the server reads identity from. A server MUST also refuse, with `400` +(`invalid-call-graph`), the deployment of an HTTP verb, function or action, whose declared calls +include a call to an action or, on a server that supports the pattern form, a `*:` pattern +({{http-entries}}). + +These are declarations of the verb ({{RESTACT}}'s "Verb declaration (deployment profile)" +section): a replacement of the verb's code alone (`PUT …:verb/code`, or a rollback) preserves +them, and a deployment through a profile re-declares them, except `verify` and `verify_secret`, +which {{http-verify-deploy}} keeps. + +# Request access {#http-request} + +**The ceiling and the deny.** A server MUST keep a **ceiling**: the set of request header field +names that a deployment may declare. Its operator sets it; this document fixes no members of it. +A server MUST also keep a **fixed deny**: names that no deployment may declare and no operator may +add to the ceiling. The fixed deny MUST include at least: + +* `Authorization`, `Proxy-Authorization`, `Cookie` and `Cookie2`; +* every header field from which the server reads the caller's identity or the caller's roles, + groups, scopes or claims, as its configuration names them; +* every header field that the server knows a proxy in front of it injects to carry a credential or + an identity assertion. (Informative: such fields include `X-Forwarded-Access-Token`, + `X-Auth-Request-Access-Token`, `X-Pomerium-Jwt-Assertion`, `Cf-Access-Jwt-Assertion`, + `X-Amzn-Oidc-Accesstoken`, `X-Amzn-Oidc-Data`, `X-Goog-Iap-Jwt-Assertion`, + `X-Ms-Token-Aad-Access-Token`, `X-Forwarded-Client-Cert` and `X-Client-Cert`.); +* the connection-specific fields ({{RFC9110}}, Section 7.6.1). + +A server MUST refuse to start when its operator adds to the ceiling a name on the fixed deny. A +name in the server's own default ceiling that is on the fixed deny is not part of the ceiling. The +ceiling is +the primary control, because no list of names can cover every proxy's credential fields; the fixed +deny is a backstop. A server MUST NOT accept a prefix or a pattern in either: names are exact. + +**Which frame sees the request.** Only the root frame of a route entry sees the request: its +`method()` is the request's method, and `header(name)` returns the declared field's value. Every +other frame sees the synthetic request: no header fields (`header(name)` returns none for a +declared name), no query, and a `method()` that is the HTTP method of the request when the frame +is an accessor that a data-plane request dispatched to, and otherwise the method the verb's kind +requires: `GET` for a function and `POST` for an action. The other frames include every composed +call, every lifecycle hook (including one that a write inside an HTTP request fires), every +subscription delivery and scheduled firing, the Model Context Protocol facet's `invoke_verb` +(which invokes a function as `GET` and an action as `POST` would), and every invocation that a +server's own extension mechanisms start. A server MUST derive what a frame sees from the frame +itself, never from state shared by the frames of one request. + +**Values.** For a declared name, a server MUST: + +* return the value with surrounding whitespace removed; +* combine the field lines of a field whose definition admits a comma-separated list ({{RFC9110}}, + Section 5.3), and refuse the request with `400` (`invalid-input`) when a field that is not a list + occurs on more than one field line. Every field a registered scheme names ({{http-schemes}}), and + every field whose definition the server does not know, is not a list. A server that receives + header fields only after its platform has combined their field lines, as the Fetch API combines + them with a comma and a space, cannot apply this refusal, and passes such a field's combined + value; a verb on that server can therefore read the lines of a repeated field joined by `, `. + Step 4 of {{http-verify-order}} still refuses a repeated field that a scheme names; +* refuse the request with `400` (`invalid-input`) when a value holds a character other than visible + ASCII, space and horizontal tab, rather than drop it, so a verb never reads "absent" for a field + the request carried. + +`header(name)` for a name the verb did not declare returns an error (`invalid-input`) naming the +`request_headers` parameter, never none. + +**A lowered ceiling.** When an operator removes from the ceiling a name that a deployed verb +declared, or the fixed deny comes to include it, a server MUST NOT serve the field as absent. It +answers each route entry of the verb with `501` (`unsupported-feature`) before the verb runs. The +detail names the field and the configuration that removed it, except a field on the fixed deny, +which the detail does not name; the server SHOULD tell its operator which verbs and fields are +affected when it starts. A server SHOULD keep listing such a verb in its discovery document and its +OpenAPI document, with its descriptor unchanged. A client tells that its route entry will answer +`501` by a name in the verb's `httpVerb.requestHeaders` that `service.httpVerbs.requestHeaders` +does not hold ({{http-discovery}}). + +**Query.** A verb reads no query parameter through these interfaces. A function's `?input=` is its +input, as for any verb. + +**Caching.** A server SHOULD list the declared names in the `Vary` field of a function's response, +in addition to the fields {{RESTACT}} requires there. + +# Response control {#http-response} + +## Status {#http-status} + +A server MUST admit the following statuses from an HTTP verb, which are the **baseline**: + +| Verb kind | Baseline | +|---|---| +| function | `200`, `204`, `302` (under a redirect grant), `400`, `403`, `404`, `409`, `410`, `415`, `422` | +| action | `200`, `201`, `202`, `204`, `303` (under a redirect grant), `400`, `403`, `404`, `409`, `410`, `415`, `422` | + +A verb whose name is a reserved accessor name (the "Active Properties (Accessor Verbs)" section of +{{RESTACT-OBJECTS}}) has the baseline of its kind with no `3xx` status, `201` only for `create`, and +`204` only for `create`, `update`, `set` and `delete`, whatever entry invoked it. + +A server MUST refuse every other status, with `500` (`invalid-verb-response`), unless another +feature token that the server advertises admits the status for the verb. The following statuses +are refused for the reasons given, and a document that defines a token admitting one MUST state how +it answers that reason: + +* any `1xx`, and `101` with `Upgrade` above all: a proxy may switch the connection to a tunnel, + past every check it applies to later requests on it; +* `401` and `407`: a challenge the server did not issue, which can lead a client to drop or + replace its credential; +* `408`, `421` and `425`: clients repeat the request on their own, which repeats an action; +* `429` and every `5xx`: they claim the server's own quota or failure, and clients back off, retry + or report a server fault on the verb's word; +* `304` and `412`: they answer a precondition that the server evaluates ({{http-caching}}); +* `301`, `307` and `308`: a browser caches `301` and `308` beyond the verb's life, and `307` and + `308` repeat the method and body at the target with the caller's credential; +* `302` from an action, and `303` from a function: some clients keep `POST` on `302`, so an action + redirects with `303`, and a function, already a `GET`, with `302`. The refusal's detail says + which applies; +* `206` and `416`: range responses that the server did not evaluate; +* any value outside `100` to `599`. + +A response with status `204` MUST have an empty body; a verb that sets a body with it is refused +(`invalid-verb-response`), and the body is never cut silently. A `202` from a verb never carries +`Location`. A `302` or `303` requires a redirect grant and a `Location` ({{http-location}}). + +When no status is set, the status is `200`. + +## Response header fields {#http-headers} + +A verb MAY set only the following response header fields, each at most once. A server MUST refuse +any other name (`invalid-verb-response`), compared case-insensitively: + +* **`Content-Disposition`** ({{RFC6266}}). A server MUST parse the value into a disposition type, + `inline` or `attachment`, and an optional file name given by `filename` or by `filename*` + ({{RFC8187}}), and MUST send a value it builds itself from those parts, never the verb's text. + It MUST refuse any other parameter, and a file name that, decoded, is longer than 255 bytes of + UTF-8 or holds `/`, `\`, `"`, `%`, a code point of general category Cc, Cf, Cn, Co, Zl or Zp + ({{UNICODE}}), or one of category Zs other than U+0020. It checks the decoded name, not the + encoded value. A format character such as U+202E RIGHT-TO-LEFT OVERRIDE can make a download + dialog show the executable `invoicegpj.exe` as `invoiceexe.jpg`; U+200B, U+FEFF and + wide spaces can make names that look the same differ or hide an extension. Category Cn, which + holds the noncharacters, also holds every code point the server's Unicode version leaves + unassigned, so a server with an older version refuses a character that a newer one would + classify, never passes it. The rules of the "Security Considerations" section of {{RESTACT}} + for verb output on the server's origin apply after this field and take precedence, so a + script-capable type stays `attachment` whatever the verb set. +* **`Cache-Control`**, from a function only, as a comma-separated list of the directives + `no-store` and `must-revalidate`, which the server adds to its own ({{http-caching}}). A server + MUST refuse any other directive, and the refusal's detail lists the two allowed directives and + does not repeat the verb's value. +* **`Content-Language`**, a list of language tags ({{RFC9110}}, Section 8.5). +* **`Location`**, with `201`, `302` or `303` only, under the rules of {{http-location}}. + +Only a feature token that a server advertises can admit a further field. A token that admits +further fields MUST NOT admit `Set-Cookie`, `Clear-Site-Data`, `Strict-Transport-Security`, +`Alt-Svc`, `NEL`, `Report-To`, `Reporting-Endpoints`, `Refresh`, `WWW-Authenticate`, +`Proxy-Authenticate`, `Access-Control-*`, `X-Accel-*`, `X-Sendfile`, framing or connection fields +(such as `Content-Length`, `Transfer-Encoding`, `Connection`, `Upgrade` and `Keep-Alive`), or +`Restact-*`. + +A field value MUST consist of visible ASCII, space and horizontal tab, with no line folding, and +the fields a verb sets MUST together be at most 8192 bytes, names and values. Any breach is refused +(`invalid-verb-response`). The detail of a refusal names the rule and the field name, and never +repeats a field value. + +## The Location field {#http-location} + +A `Location` that a verb sets is either a path on the server's origin or, under the +`listed-origins` grant, an absolute URL on an origin the server lists. A server MUST accept a +`Location` only when one of the following holds, and refuse it (`invalid-verb-response`) +otherwise: + +1. **A path.** The value matches the `path-absolute` rule of {{RFC3986}}, optionally followed by + `?` and a query and by `#` and a fragment, each as {{RFC3986}} defines them; its second + character, when it has one, is not `/`; it holds no `\`, no space or control character, and no + `%2F` or `%5C` in either case; and it is at most 2048 bytes. The server then resolves it with + the URL parser of {{WHATWG-URL}} against the request's own origin or, when the server does not + know its public origin, as behind a proxy that ends TLS, any fixed `https` origin of its + choosing. It accepts the value only when the result has that origin and its path, as serialized, + does not begin with `//`. Every such origin gives the same result for a value of this form. + Browsers remove tab and newline and read `\` as `/` before resolving, so the check of the text + alone is not enough, and the resolution alone is not enough for clients that do not use that + parser. +2. **A listed origin.** The verb holds the `listed-origins` grant; the value matches + `absolute-URI` of {{RFC3986}}, optionally followed by `#` and a fragment, with the scheme + `https`, an authority and no `userinfo`, and holds no `\`, space or control character and no + `%2F` or `%5C`; it is at most 2048 bytes; and the origin that + {{WHATWG-URL}} gives for it equals, as serialized, one of the origins the server's operator + listed. The list holds origins only, compared exactly, with no pattern. + +On a server whose base URL has a path prefix (the "Base URL" section of {{RESTACT}}), a path that +names one of the server's resources includes the prefix. A verb learns the prefix only from its +deployer, since no interface carries it. A verb written for a server without a prefix that answers +`201` with `Location: /orders/1` names, on a server whose base URL is `https://h.example/restact`, +a path outside that server's resources; form 1 still accepts it, because it is on the origin. + +A server MUST check the origin of the `Location` value it sends: when it sends a normalized form of +the verb's value, such as one with its dot segments removed, it checks that form. It MUST NOT send a +value that begins with two slashes. + +A `302` or `303` needs a grant: `same-origin` admits form 1, and `listed-origins` admits forms 1 +and 2. The default grant, `none`, admits no redirect. A `201` admits form 1 under every grant, and +form 2 under `listed-origins`. There is no server-wide switch for redirects; the operator's control +is the list of origins, which is empty unless the operator fills it. + +Test vectors. Form 1 values are resolved against `https://h.example`, and the grant "listed" is +`listed-origins` with `https://partner.example` on the operator's list. The last vector passes the +origin check of {{WHATWG-URL}}, which reads `\` as `/`, while some other URL parsers send it to +`evil.example`: + +| Location | Grant | Result | +|---|---|---| +| `/a/b` | any | accepted | +| `/a/b?c=d#e` | any | accepted | +| `//evil.example/` | any | refused (second character is `/`) | +| `/.//evil.example/` | any | refused (resolved, its path begins with `//`) | +| `/\evil.example/` | any | refused (`\`) | +| `/%5Cevil.example/` | any | refused (`%5C`) | +| `/%2F%2Fevil.example/` | any | refused (`%2F`) | +| `/` TAB `/evil.example/` | any | refused (control character) | +| `/` LF `/evil.example/` | any | refused (control character) | +| `https:evil.example` | any | refused (not a path; no authority) | +| `javascript:alert(1)` | any | refused | +| `evil.example/x` | any | refused (not `path-absolute`) | +| `https://partner.example/cb` | `same-origin` | refused | +| `https://partner.example/cb` | listed | accepted | +| `https://user@partner.example/cb` | listed | refused (`userinfo`) | +| `https://partner.example\@evil.example/cb` | listed | refused (`\`) | + +## Content type and body {#http-content-type} + +A verb's content type is its `produces` type unless it sets another. A type it sets MUST be one of +its declared types, the `produces` type and those of `http_produces`, compared by type and subtype +case-insensitively; it MAY carry parameters, such as `charset`. A value that is not exactly one +media type, or holds a control character, is refused (`invalid-verb-response`). + +The media types `application/problem+json`, `application/problem+xml` and `text/event-stream` are +the server's: a server MUST refuse to deploy an HTTP verb that declares one of them, so that a +Problem Details document in a response is always the server's refusal. A server's limits on the +size of a verb's output, and every rule of {{RESTACT}} for a verb's output on the server's origin, +apply to an HTTP verb's response unchanged and run after the rules of this document. + +## Caching and validators {#http-caching} + +A function's response keeps the rules of the "Verb invocation (the bare verb)" section of +{{RESTACT}}: the server marks it `Cache-Control: private` (or `no-store`) and `Vary: +Authorization` ({{RFC9111}}), whatever the verb set, and for an HTTP verb it also marks the +response `no-cache`, so a cache serves it only after the server has validated it for the request +at hand. A directive that a verb sets only adds to the server's own, +and no directive a verb sets is proof that a response is independent of the caller. A server MUST +mark an action's response `Cache-Control: no-store`. + +A server emits a validator for a function's response, and evaluates `If-None-Match` and `If-Match` +against it, only when the status is `200`. For any other status it ignores both fields and sends the +verb's response. For a status that is not `2xx` that is the rule of {{RFC9110}}, Section 13.2.1. A +`204` carries no representation for a precondition to compare, so the rule of the "Verb invocation +(the bare verb)" section of {{RESTACT}} for a function that sends no entity tag does not apply to +it, as E12 of the "Extension specifications" section of {{RESTACT}} permits. The validator covers +the body and the values of `Content-Type`, `Content-Language` and `Content-Disposition`, so two +responses with the same body and different header fields never share one. A verb cannot set `ETag` +or `Last-Modified`. + +A server that lets cross-origin scripts read response header fields SHOULD expose +`Content-Disposition` and `Location`, and MUST NOT vary the exposed list with the verb. + +## The commit predicate {#http-commit} + +A status of `400` or more that an HTTP verb sets is an error return of the verb, as the +"Consistency" section of {{RESTACT}} provides. A server MUST handle it as it handles the verb's +return of an `invocation-error`, at every consistency level and on every entry: it discards every +write of the frame that set it and of the frames beneath it, stores no result under an +`Idempotency-Key`, publishes no event the frame published, fires no lifecycle hook for a discarded +write, and releases a webhook replay claim ({{http-replay}}). A server that otherwise keeps a +verb's writes before the verb returns, as the `eventual` and `conditional` levels permit, MUST NOT +do so for an HTTP verb's frame or any frame beneath it. Likewise, a server holds the events that an +HTTP verb's frame publishes until the frame returns, and publishes them, in the order of the calls, +only when the frame's writes commit. It still checks each event when the verb calls `publish` (the +"Publishing events" section of {{RESTACT-EVENTS}}), so the verb learns of a refused event at once. +A server MUST NOT publish such an event across a delivery floor (the "Delivering events to clients +(SSE)" section of {{RESTACT-EVENTS}}) that a change established after the invocation began, +including a change the invocation itself commits; it drops the event instead. A status below `400` +is a successful return, and the frame's writes commit as for any successful return. A verb can +therefore never tell its caller that a request failed while the request's writes persist. + +A server that cannot include a conditional write, such as the compare-and-swap of `object-cas` +(the "Object Data Access" section of {{RESTACT-OBJECTS}}), in the commit of an HTTP verb's frame +MUST refuse it in that frame, without writing, rather than commit it before the frame returns. + +# Other entries {#http-entries} + +**Calls to actions.** In this version an HTTP verb calls functions only, on every server. A server +MUST refuse a call from an HTTP verb's frame to an action at run time with `403` +(`forbidden-side-effect`), as the "Composition" section of {{RESTACT}} requires for a function's +call to an action, and refuses the deployment that declares one ({{http-deploy}}). A function +neither writes nor publishes (the "Verb invocation (the bare verb)" section of {{RESTACT}}), so no +frame beneath an HTTP verb's frame holds a write that could commit before the HTTP verb's status is +known ({{http-commit}}). A later document can lift this refusal, under a feature token of its own, +for a server that holds the writes of a composed action until the frame that called it returns. + +**Composition.** A composed call to an HTTP verb returns to the calling verb a success holding the +body when the status is below `400`, and otherwise an `invocation-error` whose code is fixed by the +status and whose message names the status: + +| Status | Code | +|---|---| +| `400`, `415`, `422` | `invalid-input` | +| `403` | `forbidden` | +| `404`, `410` | `not-found` | +| `409` | `conflict` | + +Response header fields and the content type are not passed to the calling verb. A refusal that the +server raises for the called verb, such as `invalid-verb-response`, reaches the calling verb as the +"Errors" section of {{RESTACT}} sets for a refusal raised in the tree. + +**Idempotency.** When a server returns an action's original result for a repeated `Idempotency-Key` +("Verb invocation (the bare verb)" section of {{RESTACT}}), the result of an HTTP verb is its +status, the header fields as the server validated and built them, its content type and its body, +and the verb does not run again. A verify-gated verb takes no `Idempotency-Key` ({{http-replay}}). + +**Asynchronous handling.** A server MUST ignore `Prefer: respond-async` ({{RFC7240}}) on an +invocation of an HTTP verb and run it synchronously, as the "Asynchronous Operations" section of +{{RESTACT}} permits. A `202` from such a verb is the verb's own: it never carries `Location`. A +client SHOULD treat a `202` as an asynchronous operation of the server only when it sent `Prefer: +respond-async` and the response carries a `Location`. + +**Accessors.** An HTTP verb MAY serve as an accessor verb (the "Active Properties (Accessor Verbs)" +section of {{RESTACT-OBJECTS}}). Under a data-plane request that a server dispatches to it, it sees +the synthetic request with the request's own method, its statuses are those {{http-status}} sets +for its name, and the commit predicate applies. + +**Registrations.** An HTTP verb that runs as a lifecycle hook, a subscription delivery or a +scheduled firing (the "Events, Triggers, and Scheduling" section of {{RESTACT-EVENTS}}) sees the +synthetic request. A status of `400` or more is a failure of the firing, with the code that the +composition table gives. + +**The Model Context Protocol facet.** On a server that also advertises `mcp-facet` +({{RESTACT-MCP}}), `invoke_verb` of an HTTP verb returns the verb's own response, as E12 of the +"Extension specifications" section of {{RESTACT}} permits. Whatever the status, the result's +structured content is an object that the server writes, never the verb's body in its place: + +* `status`, the status, as a number, always present; +* `location`, the `Location` value the server sent, when the response carries one; +* `body`, the verb's body, unchanged, when it has one and its bytes are valid UTF-8: its JSON value + where the content is JSON, and otherwise the content as text. + +A body whose bytes are not valid UTF-8 is never turned into text, and `body` is then absent. The +server carries it, base64-encoded, in a content item of its own after the first: an image content +item for an `image/*` media type, an audio content item for an `audio/*` media type, and otherwise +an embedded resource whose `uri` is the URI of the invoked route. Its `mimeType` is the response's +media type, or `application/octet-stream` when the response has none. + +A status below `400` is a successful result, and a status of `400` or more is a tool error. The +result's first content item is text that begins "the verb answered NNN", with NNN the status, +followed by "; Location: " and the value when the response carries one, and for a status of `400` +or more by "; its content follows (the verb's own, not a refusal of the server)"; a body that is +valid UTF-8 follows as text. A body cannot stand in for the status the server reports, and a verb's error never takes +the shape of a refusal of the server. The result's `_meta` also carries the member +`restact/http-response`, an object with `status` and, when the response carries them, `location` +and `contentType`. + +# Which rules are fixed {#http-rule-kinds} + +Each rule of this document is one of three kinds. A **fixed** rule is the same on every server. A +**portable minimum** sets what every server meets, and a server chooses beyond it. A **reference +default** is how the reference implementation sets a value that this document leaves to the +server; it is informative. + +| Rule | Kind | Value | +|---|---|---| +| Status baseline and the refused statuses | fixed | {{http-status}} | +| Response header fields a verb may set, and their parsing | fixed | {{http-headers}} | +| Response header bytes | fixed | at most 8192 | +| `Location` grammar and length | fixed | {{http-location}}; 2048 bytes | +| File name length | fixed | 255 bytes | +| Declared request header names per verb | fixed | at most 16 | +| Declared media types in `http_produces` per verb | fixed | at most 16 | +| The fixed deny | portable minimum | the categories of {{http-request}} | +| The ceiling | server's own | reference default in {{http-reference-defaults}} | +| Redirect origins | server's own | empty by default | +| `private, no-cache` on a function's response; no verb directive as proof of caller independence | fixed | {{http-caching}} | +| Commit predicate and composition table | fixed | {{http-commit}}, {{http-entries}} | +| Timestamp tolerance | fixed | 300 seconds, both directions | +| Key floor | fixed, exact | 16 bytes | +| Replay retention | portable minimum | {{http-replay}} | +| Content a server verifies | server's own | reference default 12 MiB, `413` above it | +| Webhook account size | server's own, always finite | reference default in {{http-reference-defaults}} | + +# Discovery {#http-discovery} + +A server that advertises `verb-http-handler` MUST carry in its discovery document's `service` +object the member `httpVerbs`, an object with: + +* `requestHeaders`: the ceiling, as an array of lowercase field names. It never lists a name on the + fixed deny; +* `webhookSchemes`: the schemes the server implements, as an array of registered scheme names, + present only while the server advertises `webhook-verification`. + +An HTTP verb's descriptor (the `verb` object of its discovery entry, and its `meta`) MUST carry the +member `httpVerb`, an object with: + +* `requestHeaders`: the declared names, lowercase; +* `produces`: every type the verb may set, the `produces` type first; +* `redirects`: the grant; +* `verify`: for a verify-gated verb only, an object whose `scheme` member names the scheme. It + never names the secret reference. + +The companion OpenAPI extension that the "Discovery" section of {{RESTACT}} names carries these +members. A server's OpenAPI document SHOULD describe an HTTP verb's operation with the statuses its +grant and kind admit and with its declared request header fields as header parameters. + +A client that offers verbs to a language model as tools SHOULD NOT offer a verify-gated verb, and +SHOULD show it as reachable only by a signed delivery. + +Such a client SHOULD likewise not offer, or SHOULD mark as unavailable, an HTTP verb that declares +a request header field the server's `service.httpVerbs.requestHeaders` does not list. + +# Codes {#http-codes} + +This document defines these codes. Neither is guest-raisable (the "Errors" section of +{{RESTACT}}): + +| Code | Status | Covered by | Meaning | +|---|---|---|---| +| `invalid-verb-response` | 500 | `verb-http-handler` | the verb set a status, header field, content type or body that the rules of {{http-response}} refuse, or called a setter while it is not an HTTP verb; the server discarded what it set and its writes | +| `signature-invalid` | 403 | `webhook-verification` | a request to a verify-gated verb's route did not carry a signature that the server verified ({{http-verify-failures}}) | + +A webhook delivery also meets `conflict` (`409`) for a duplicate in flight ({{http-replay}}), +`quota` (`429`) for an exhausted webhook account ({{http-webhook-cost}}), `unavailable` (`503`) for +a failure on the receiving side ({{http-verify-failures}}), and, at deployment, the `secret-*` +codes of the "Codes of the mediated call" section of {{RESTACT-CONNECTORS}}. + +# Webhook verification (OPTIONAL, feature `webhook-verification`) {#http-webhooks} + +A webhook sender calls a URL anonymously and signs what it sends with a key it shares with the +receiver. A verb could check that signature in its own code, but that would put a primitive for +testing guesses at the key inside untrusted code, and every entry other than the route would +bypass the check. Under this feature the server checks the signature before the verb runs, at the +route only, and the verb never holds the key or a way to compute with it. + +## Declaring verification {#http-verify-deploy} + +A server that advertises `webhook-verification` MUST accept these deployment parameters: + +* `verify`: the name of a scheme the server implements ({{http-schemes}}), or `none`; +* `verify_secret`: the path of the secret reference that holds the key, under the secrets mount + (the "The mediated secrets mount (OPTIONAL, feature `secrets-management`)" section of + {{RESTACT-CONNECTORS}}). + +A server MUST refuse a deployment that sets `verify` to a scheme, deploying nothing, with `400` +(`invalid-input`) and a detail naming the rule, unless all of the following hold. These are +invariants of the verb's record, and a server checks them on every write of it, a write of its +policy (`PUT …:verb/policy`) included: + +* the deployment carries `http=true` and `verify_secret`; +* the verb is an action; +* its route is concrete: every segment of its object path is literal, with no pattern; +* its name is not one that the "Grammar" section of {{RESTACT}} or the "Active Properties + (Accessor Verbs)" section of {{RESTACT-OBJECTS}} reserves, since a request to a route never + reaches a hook or a dispatched accessor; +* its redirect grant is `none`; +* its `execute` policy admits the anonymous principal, because a sender calls anonymously and the + signature is its authentication. The refusal's detail says so: "a webhook sender calls + anonymously; deploy with exec=public (the signature check is its authentication)"; +* its owner is not the anonymous principal. + +A server MUST also refuse with the code that the "Codes of the mediated call" section of +{{RESTACT-CONNECTORS}} gives for the condition, checking in this order and answering only the first +that applies: a `verify_secret` that is not under the mount (`secret-not-mount`); a reference that +the deployer may not read, or that does not exist, answered alike (`secret-denied`); a reference +whose `verifiers` member does not list the route and the deployer ({{http-verifiers}}; +`secret-not-bound`); and, where it can resolve the key at deployment, a key shorter than 16 bytes +(`secret-too-short`). Because `read` is checked before the binding, a deployer learns nothing about +the `verifiers` member of a reference it may not read, or whether such a reference exists. + +**Owner only.** The verb's owner is the principal that accepted the cost of its deliveries +({{http-webhook-cost}}). A server MUST therefore refuse with `403` (`forbidden`) a deployment that +sets `verify` on an existing verb, a replacement of a verify-gated verb that keeps `verify` +(through any deployment interface, `PUT …:verb/code`, or a rollback), and a deployment with +`verify=none`, unless the deployer is the verb's owner. + +A server records with a verify-gated verb the principal whose deployment last set or kept +`verify`. While the verb's owner is not that principal, as after an operator act that reassigns +the owner (E1 of the "Extension specifications" section of {{RESTACT}}), the server refuses every +delivery at step 5 of {{http-verify-order}} until the owner deploys the verb with `verify` itself, +so the acceptance of the cost never passes to a principal that did not make it. + +**Replacement keeps the gate.** A replacement through a deployment profile that omits `verify` +keeps the verb's scheme, its secret reference and its `http` declaration; only `verify=none` +clears them. The server re-checks every invariant above, and the binding, on the record it carries +over, and SHOULD name the declarations it kept in its response. A server MUST refuse with `400` +(`invalid-input`) a deployment with `verify=none` that clears the gate of a verb that runs as its +owner, unless the deployment states `runs_as`. When the deployment states `runs_as=owner` and the +verb's `execute` policy admits the anonymous principal, the server SHOULD warn the deployer that +anyone may now run it as its owner. + +**Model completion.** A server MUST withhold the `llm` capability (the "Model Completion +(OPTIONAL, feature `llm-connector`)" section of {{RESTACT-CONNECTORS}}) from a verify-gated verb +unless the deployment grants it with `llm=allow`, and SHOULD warn the deployer that the spend +policy is then everyone who can make the provider send a signed delivery. A server MAY refuse, with +`400` (`invalid-input`) naming `llm`, a deployment that grants `llm=allow` to a verify-gated verb, +and a deployment that sets `verify` on a verb that holds that grant. + +**Webhook delivery.** In the same way, a server MUST withhold the `webhook` capability (the "Webhook +Delivery (OPTIONAL, feature `webhook-connector`)" section of {{RESTACT-CONNECTORS}}) from a +verify-gated verb unless the deployment grants it with `webhook=allow`, and SHOULD warn the deployer +that anyone who can make the provider send a signed delivery can then cause the verb's outbound +deliveries. A server MAY refuse such a grant, and the setting of `verify` on a verb that holds it, +as for `llm`. + +**Shared secrets.** When the reference's `verifiers` member lists more than one route, a server +MUST warn the deployer in its response to the deployment that a delivery signed with that secret is +accepted once at each listed route, so a delivery captured at one route can run once at another, +and that one secret per route avoids this. A server whose response to a deployment is a JSON object +SHOULD carry each warning as a string in its member `warnings`, an array. + +## The verifiers member {#http-verifiers} + +A secret reference under the mount carries the routes allowed to verify with it in its member +`verifiers`, a string holding the JSON {{RFC8259}} text of an array of objects, each with the +members `route`, the verb's route written as its discovery entry writes it, and `owner`, the +subject of the principal that deploys it. The reference's owner writes it under the reference's +own policy, like its `connectors` member. A server compares both members byte for byte, with no +normalization, and treats a member that does not parse as listing nothing. + +Because only the verb's owner deploys or replaces a verify-gated verb ({{http-verify-deploy}}), +`owner` names the verb's owner. An entry for a route therefore binds the secret to that route only +while the same principal owns the verb there: a verb that another principal later deploys at the +route does not inherit the binding. + +## Verifying a delivery {#http-verify-order} + +For a request to a verify-gated verb, a server MUST take these steps, in this order, before the +verb runs. Each step's failure ends the request with the answer given. + +1. **Size.** The content is no larger than the server verifies; otherwise `413` + (`payload-too-large`). The server reads the whole content before step 6 and never passes a + verb content it has not verified. +2. **Route.** The request's target is the verb's own route: the object path the request names is + the path the verb is defined at, and does not reach the verb by inheritance (the "Verb + Resolution and Inheritance" section of {{RESTACT}}), since no scheme signs the target. Otherwise + `403` (`forbidden`) with the detail "this verb accepts only signed deliveries at its own route". +3. **Authorization.** The server authenticates the request and evaluates the verb's `execute` + policy against the real caller, as for any invocation. +4. **Header fields.** First, every field the scheme names is present (`missing-header`); then each + is on exactly one field line and has the form the scheme gives (`malformed-header`); then the + timestamp, where the scheme has one, is within 300 seconds of the server's clock in either + direction (`stale-timestamp`, `future-timestamp`). Otherwise `403` (`signature-invalid`) with + the first reason that applies ({{http-verify-failures}}). A server that receives header fields + only after its platform has combined their field lines, as the Fetch API combines them with a + comma and a space, treats a field the scheme names as on more than one field line when its + value, before surrounding whitespace is removed, contains a comma followed by a space. No + registered scheme's field holds that sequence on one line. +5. **Key.** The verb's owner is the principal that accepted its deliveries + ({{http-verify-deploy}}), the reference is under the mount, its `verifiers` member lists the + route and the verb's owner, the verb's owner may read the reference, the key resolves, and it + is at least 16 bytes. The server evaluates the reference's `read` for the owner as an + attenuated principal (the "Authorization policy" section of {{RESTACT}}): its subject alone, + with no roles, groups, scopes or claims, and a `deny` rule keyed on a dropped attribute still + applying as that section requires. Every server reaches the same answer this way, including one + that authenticates principals per request and so knows the owner's attributes only while the + owner is the caller. An owner whose `read` comes only through a role or group grants it to its + subject. + A server checks the listing and the owner's `read` on every delivery, so revoking either stops + deliveries at once. Otherwise `503` (`unavailable`), the same answer for every one of these + conditions. +6. **Signature.** The server computes HMAC-SHA256 ({{RFC2104}}, {{RFC6234}}) with the key over the + scheme's signed content, decodes each candidate signature in the header field, and compares the + decoded bytes with the computed MAC in constant time over their full length. Otherwise `403` + (`signature-invalid`), "does not match". +7. **Replay.** The server claims the delivery ({{http-replay}}). +8. **Cost.** The verb owner's webhook account admits the delivery ({{http-webhook-cost}}); + otherwise `429` (`quota`), and the server releases the claim. +9. **Invocation.** The verb runs as the root of a verified delivery. + +A server MUST NOT compute with the key in any way except step 6, and MUST NOT let the key or any +value derived from it reach a verb, a response, a log or an audit record. It MUST compare decoded +bytes, never header text. Steps 1 to 8 do not depend on the executor that runs the verb, so a +server that runs verbs in more than one way verifies identically for each. A server reads the +fields a scheme names from the request whatever its ceiling and fixed deny hold ({{http-request}}); +those govern only what a verb may read, so a ceiling without a scheme's fields neither disables +verification nor lets a verb read them. + +## Scheme rules {#http-schemes} + +Every scheme of this version is HMAC-SHA256 over content that includes the request's content as +received, byte for byte. A **timestamp** is the decimal number of seconds since 1970-01-01T00:00:00Z +without leap seconds, written with ASCII digits only, at most 19 of them. A **hex MAC** is exactly 64 +lowercase hexadecimal digits. Unless a scheme says otherwise, the key is the reference's value as +stored, as bytes. + +`github` {{GITHUB-WEBHOOKS}}: +: The field `X-Hub-Signature-256` holds `sha256=` followed by a hex MAC. The signed content is the + request's content. The scheme has no timestamp. + +`stripe` {{STRIPE-WEBHOOKS}}: +: The field `Stripe-Signature` holds elements separated by `,`, each a key, `=` and a value, split + at the first `=`. An element without `=`, a field with no element `t` or with more than one, and + a field with no element `v1` are malformed. The value of `t` is a timestamp. An element whose key + is not `t` or `v1`, a `v0` element included, is ignored. A `v1` value is a candidate signature; + one that is not a hex MAC never matches, and the delivery verifies when any candidate matches. + The signed content is the value of `t` as received, `.`, and the request's content. + +`slack` {{SLACK-SIGNING}}: +: The field `X-Slack-Request-Timestamp` holds a timestamp, and `X-Slack-Signature` holds `v0=` + followed by a hex MAC. The signed content is `v0:`, the timestamp as received, `:`, and the + request's content. + +`standard-webhooks` {{STANDARD-WEBHOOKS}}: +: The field `webhook-timestamp` holds a timestamp; `webhook-id` holds the message identifier; and + `webhook-signature` holds entries separated by single spaces, each a version, `,`, and a + signature. An entry whose version is not `v1`, an empty entry included, is ignored, and a field + with no `v1` entry is malformed. A `v1` signature is the padded base64 encoding ({{RFC4648}}, + Section 4) of 32 bytes; one in any other form never matches. The signed content is the + `webhook-id` value, `.`, the timestamp as received, `.`, and the request's content. The + reference's value is `whsec_` followed by the base64 encoding ({{RFC4648}}, Section 4) of the + key, or that encoding alone, and the key is the decoded bytes; a value that does not decode is + handled as a key below the floor. The fields `svix-id`, `svix-timestamp` and `svix-signature` + are not read. + +**The key floor.** A server MUST refuse a key shorter than 16 bytes, and MUST NOT refuse a longer +one for its length, so a key that verifies on one server verifies on all. + +**Registry.** Every scheme is an entry of the REST:ACT Webhook Schemes registry ({{http-iana}}). A +server MUST NOT accept a `verify` value that names no entry it implements. + +## Replay {#http-replay} + +A delivery's identity is the verb's route, the reference path and the MAC that the server +computed in step 6, never a header field the scheme does not sign. The route is the verb's route as +defined, not the text of the request target. A server MUST NOT run an accepted delivery a second +time while it retains its identity, and MUST retain it at least: + +* for a scheme with a timestamp, until the delivery's timestamp is more than 300 seconds in the + past, after which step 4 refuses the delivery; a server on more than one node retains it until + step 4 would refuse it on every node, allowing for the difference between their clocks; +* for `github`, for 72 hours after the server accepted it. + +A server MAY retain an identity longer. A server that runs on more than one node over shared +storage MUST share these identities among its nodes, and a server MUST keep them across a restart +and across an operator reset (the "Operator Reset (OPTIONAL, feature `admin-reset`)" section of +{{RESTACT}}), since a reset discards the verbs but not the secrets or the senders that sign with +them. + +**Claims.** A server claims a delivery's identity before the verb runs. While the first delivery is +in flight, a server MUST answer a second with the same identity at once with `409` (`conflict`), +without waiting for the first. When the first delivery's invocation commits, the claim becomes an +accepted delivery, and a server answers a later delivery with that identity with `200`, an empty +body and the header field `Restact-Webhook-Replay: 1`, without running the verb. When the first +delivery's outcome is an error return, a status of `400` or more included ({{http-commit}}), a +refusal of the server, or a request that ended before the verb began to run, the server releases +the claim, so the sender can deliver it again. A server MUST NOT release a claim while the verb may +still commit, or when it cannot tell whether the verb committed. A claim that a server cannot +release, because the process holding it ended, MAY lapse, but not while the first delivery could +still be running. + +**Capacity.** When a server cannot record another identity, for the route's owner or at all, it +MUST answer `503` (`unavailable`) and MUST NOT discard an identity it is required to retain. + +**Anti-replay, not deduplication.** A sender whose scheme signs a timestamp signs again with a new +timestamp when it retries, and some senders send the same event more than once by design, so a +delivery's identity does not identify the event it carries. A verb that must act once per event +deduplicates on the event identifier inside the content. A sender that redelivers the same signed +content, as `github` does, presents the same identity, so the server answers it as a replay unless +the first delivery was released. + +**Idempotency-Key.** A server MUST ignore `Idempotency-Key` on a request to a verify-gated verb; +the replay guard is its deduplication. + +The header field `Restact-Webhook-Replay` is this document's, and the "Extension specifications" +section of {{RESTACT}} reserves it: a server MUST NOT emit it unless it advertises +`webhook-verification`, and a verb cannot set it ({{http-headers}}). + +## The entry gate {#http-entry-gate} + +A server MUST run a verify-gated verb only as the root frame of a verified delivery. Every other +entry is refused before the verb runs: a composed call, a lifecycle hook, a subscription delivery, +a scheduled firing, accessor dispatch, and every invocation that a server's own extension +mechanisms start, each with `403` (`forbidden`) and the detail "this verb accepts only signed +deliveries at its own route". The Model Context Protocol facet's `invoke_verb` answers as the HTTP +request it stands for would, which carries no signature, so it is refused at step 4 at the latest: +`403` (`signature-invalid`), reason `missing-header`, unless an earlier step refuses it first. A server MAY refuse at deployment a declared call, and at registration a +subscription or schedule, that names a verify-gated verb; that refusal is an aid to the deployer, +not the control. + +## Cost of a delivery {#http-webhook-cost} + +The compute cost of a verified delivery's invocation, and of the call tree beneath it, is +attributed to the webhook account of the verb's owner, the extension point E13 of the "Extension +specifications" section of {{RESTACT}}. The owner accepted the cost by its own deployment of the +verb with `verify`, and {{http-verify-deploy}} requires every deployment and replacement that sets +or keeps `verify` to be the owner's own. The cost is what the invocation and the call tree beneath +it consume while they run: execution, composed calls, outbound calls, log output, concurrent +invocations, and the bytes of content they store. A count of objects that a server keeps per owner +is not part of it: an object that the delivery creates counts for its own `$owner`. + +A server MUST keep one webhook account for each principal that owns a verify-gated verb, shared by +all of that principal's verify-gated verbs. It MUST NOT attribute a delivery's cost to the caller, +to the anonymous principal, to an account per route, or to the account that the owner's own +requests draw on. A webhook account is not a principal: no credential authenticates as it, and no +request, policy or registration names it. A server MUST bound each webhook account with finite +limits separate from those of the owner's own account, so that a delivery's own call tree cannot +exhaust the quota that the owner's own requests draw on. The bound is finite on every server, +including one that sets no limit on any principal's own account; its size is the server's choice. +A `429` for an exhausted webhook account says so in its detail. + +A reaction that a delivery's writes or events cause, such as a lifecycle hook or a subscription +delivery, is a separate invocation, and its cost is attributed as {{RESTACT-EVENTS}} sets, to its +registrant. A reaction that the verb's owner registered therefore draws on the owner's own account. + +Besides the attribution of cost, this document only narrows the delivery's authority, relaxing +nothing of the "Execution identity" section of {{RESTACT}}: a server MUST run a verified delivery +with the authority that section sets for the anonymous caller, which is the owner's when the verb +runs as its owner, even when the request also carries a valid credential. The server still +authenticates that credential, and evaluates the verb's `execute` policy against the principal it +authenticates. + +## Failures and audit {#http-verify-failures} + +**On the wire.** A server answers a delivery that step 4 or step 6 refuses with `403` +(`signature-invalid`), with no `WWW-Authenticate` field, since no registered authentication scheme +describes a webhook signature. Its detail is "this route accepts only signed deliveries" followed by +one reason: `missing-header`, `malformed-header`, `stale-timestamp` or `future-timestamp` for step +4, the first that applies, or "does not match" for step 6. Those reasons describe only the request, +which the sender wrote. A failure on the receiving side (step 5) is `503` (`unavailable`) with the +same detail for every condition, so an anonymous sender does not learn whether a reference exists, +who may read it, or how long its key is. + +**Audit.** A server SHOULD record every refusal of a delivery with the route, the scheme and exactly +one reason from this closed set, and never the signature, the key, the key's length or the +content: + +| Reason | Meaning | +|---|---| +| `too-large` | the content is larger than the server verifies (step 1) | +| `wrong-route` | the request reached the verb other than at its own route (step 2) | +| `missing-header` | a field the scheme names is absent | +| `malformed-header` | a field is present more than once or does not have the scheme's form | +| `stale-timestamp` | the timestamp is more than 300 seconds in the past | +| `future-timestamp` | the timestamp is more than 300 seconds in the future | +| `mismatch` | no candidate signature matches | +| `not-bound` | the reference's `verifiers` member does not list the route and the verb's owner, or the reference is not under the mount | +| `secret-denied` | the verb's owner may not read the reference | +| `secret-unavailable` | the key did not resolve | +| `key-too-short` | the key is shorter than 16 bytes | +| `owner-changed` | the verb's owner is not the principal that accepted its deliveries | +| `replay` | the delivery was accepted before | +| `in-flight` | a delivery with the same identity is running | +| `guard-full` | the server cannot record another identity | +| `quota` | the owner's webhook account did not admit the delivery (step 8) | +| `rate-limited` | the server limited work it does for deliveries, such as refreshing a key after a mismatch, without refusing a delivery whose signature verifies against the key the server holds | + +## Handshakes {#http-handshakes} + +Some senders confirm an endpoint by asking the receiver to compute a value with the key over +content the sender chooses. A server MUST NOT compute with a verification key over content that it +has not received signed by that key, since that would make the key a signing key for whoever can +start the handshake. Standard Webhooks endpoint verification and the like are therefore not +supported by this version. A handshake whose request arrives signed, such as Slack's +`url_verification`, is an ordinary delivery: the verb receives it and answers the challenge. + +# Security Considerations {#http-security} + +The considerations of {{RESTACT}} apply. This section names the risks this document's rules +answer, and the ones it leaves. + +* **Header fields that a proxy acts on.** Some front proxies act on response header fields from + the server behind them: an internal redirect, a file read on the proxy's host, a dropped header. + A server cannot know which fields its operator's proxy honors, which is why the fields a verb may + set are a closed list of four and a custom `x-` field is never one of them. +* **Connection takeover.** A `101` or other `1xx` status from a backend can make a proxy turn the + connection into a tunnel, and later requests on it then pass none of the proxy's checks, + including the removal of a client's copy of an identity header. No verb sets a `1xx` status. +* **Origin-wide, lasting state.** `Set-Cookie`, `Clear-Site-Data`, `Strict-Transport-Security`, + `Alt-Svc`, `NEL` and the reporting fields change a browser's state for the whole origin, or a + registrable domain, beyond the response. No verb sets them. +* **Redirects.** `307` and `308` repeat a request's method and body at another URL with the + caller's credential, which runs a write the caller never chose, outside the redirecting verb's + declared calls and budget; a `302` keeps the method of a `PUT` or `DELETE` in many clients. + Hence the per-kind redirect statuses, no `3xx` from accessors, and the `Location` rules. Every + redirect a deployment can produce is visible in its descriptor's grant. A client that attaches a + credential to a request SHOULD NOT follow a redirect from a verb's response to another origin. + A verb that answers `text/html` can still move a browser with markup when the server's content + policy for verb output allows it; the policy of the "Security Considerations" section of + {{RESTACT}} that admits no script reduces that. +* **Credentials that proxies inject.** A proxy that authenticates users often forwards the user's + access token or identity assertion in a header field. A verb able to read that field could carry + the token to its author. The operator's ceiling, not a list of names, is what keeps such fields + out of reach; the fixed deny catches the ones a server knows. +* **Verification oracles.** A verb that could test a MAC under a key, or a handshake that MACs + sender-chosen content, would turn the right to use a key into a way to learn or use it. Neither + exists here, and the failures that depend on the receiver's configuration share one answer. + The `503` for those failures still shows a sender that the route's binding is broken. +* **Replay.** GitHub's delivery identifier is not signed, and GitHub signs no timestamp, so the + server keys replay on signed material and keeps a `github` delivery for 72 hours. GitHub keeps + the identifier and the signed content the same when it redelivers, so a redelivery of an accepted + delivery is answered as a replay. A delivery captured at one route can run once at each other + route whose `verifiers` lists the same secret, which is why a deployment that creates that + situation is warned. A server that lost its record of deliveries on a restart would accept every + one of them again, which is why {{http-replay}} requires the record to survive a restart. +* **Released deliveries.** A delivery that the verb answers with `400` or more, or on which it + traps or exceeds a limit, is released so that its sender can deliver it again, unless the server + cannot tell whether the verb committed. Anyone holding a copy can then deliver it again, without + limit while its timestamp is within the window, and at any time for `github`, which has none, and + every run is charged to the owner's webhook account. The account bounds that spend. A verb SHOULD + answer a delivery it has decided not to act on with a `2xx` status, and keep `4xx` for one + it wants the sender to retry. +* **Work before verification.** A server reads, and computes a MAC over, up to the whole content it + verifies before it knows that a delivery is genuine, so an anonymous sender can make it hash that + much for each request. The bound is the size of content the server verifies, which a server keeps + no larger than its limit on request content, and every check that needs no key, such as the + presence, form and age of the signature fields, comes first. A server does not refuse a delivery + to save that work, since a flood would then refuse genuine deliveries too; an operator who needs + a tighter bound sets the verified size lower or limits request rates in front of the server. +* **The route is unsigned.** No registered scheme signs the target URL, so a verify-gated verb + runs only at the exact path it is defined at, and never as a composed call, hook, firing or + accessor. +* **Content from senders.** A delivery's content comes from a third party, and anyone who can make + the provider send one, for example by opening an issue on a public repository, controls part of + it. A verb that passes it to a language model passes text aimed at the model, which is why + model completion is withheld from a verify-gated verb unless granted. The detail of a verb's + `4xx` response is the verb's text; a client presents it as the verb's, never as the server's. +* **Cost.** The same people can make a provider send deliveries, and so spend the owner's compute. + The webhook account bounds, per owner and on every server, what deliveries' own call trees + spend, and keeps it off the owner's own quota. A hook or subscription that the owner registers + on what a receiver writes or publishes is billed to the owner's own account, at the rate the + senders choose. +* **A failure after writes.** A verb that answered `4xx` after writing would tell its caller that + nothing happened while its writes persisted; the commit predicate discards them. +* **Caching across users.** A `max-age` on a private response can be served to another user of the + same browser profile without a request reaching the server, where identity travels in a cookie + or a proxy-injected field. A verb cannot set one. +* **File names.** A verb can offer a download under any name on the server's origin, such as + `setup.exe`. The server builds the field itself and the hardening of {{RESTACT}} keeps + script-capable types as downloads, but the name is the verb's. +* **Size.** A server that verifies less content than a provider may send refuses those deliveries + with `413`; GitHub, for example, sends up to 25 MB. + +# IANA Considerations {#http-iana} + +This document requests the following registrations in registries that {{RESTACT}} creates, and one +new registry. + +* In the "REST:ACT Feature Tokens" registry: `verb-http-handler` ({{http-features}}) and + `webhook-verification` ({{http-webhooks}}). +* In the "REST:ACT Capability Interfaces" registry: `rest-act:plugin/request` and + `rest-act:plugin/response` ({{http-guest}}), both under `verb-http-handler`. +* In the "REST:ACT Error Codes" registry: the codes of {{http-codes}}, neither guest-raisable. The + entries for `secret-not-mount`, `secret-not-bound`, `secret-denied` and `secret-too-short` that + {{RESTACT-CONNECTORS}} registers also list `webhook-verification`. + +**The REST:ACT Webhook Schemes registry.** This document creates the "REST:ACT Webhook Schemes" +registry, with the registration policy Specification Required {{RFC8126}}. A provider's own +published documentation of its signing method meets that policy. Each entry gives: + +* the scheme's name, lower-kebab-case, permanent, and never reused for a different method; +* a citation of the provider's specification, pinned to a version or commit; +* the signed content, the header fields and the grammar of each, + including the case of hexadecimal digits and the handling of unknown keys and entries; +* whether the scheme carries a timestamp; every scheme with one uses the fixed tolerance of 300 + seconds in both directions; +* the minimum retention of a delivery's identity ({{http-replay}}); +* the key's encoding and, as information only, the key sizes the provider issues; +* test vectors, with their source and licence; a vector computed for the entry rather than + published by the provider says so; +* how the scheme's handshakes, if any, are handled ({{http-handshakes}}); +* a status and a reference. + +A name that only an existing registration elsewhere would explain is avoided: the IANA "HTTP +Signature Algorithms" registry of {{RFC9421}} already holds `hmac-sha256`, so a scheme is named +after the method it describes, not after its primitive. The initial entries are `github`, +`stripe`, `slack` and `standard-webhooks` ({{http-schemes}}), in `registries/webhook-schemes.md`. + +--- back + +# Reference-host defaults (informative) {#http-reference-defaults} + +The reference implementation gives its operator four settings for these features: + +* a switch for HTTP verbs, and with them webhook verification. Off, the server advertises neither + token and treats stored HTTP verbs as {{http-features}} requires; +* a switch that turns webhook verification alone off; +* names to add to the ceiling; +* the origins of the `listed-origins` grant. + +Each switch accepts only a recognized boolean, and the server refuses to start on any other value. +The default ceiling is `accept`, `accept-language`, `content-type`, `x-hub-signature-256`, +`x-github-event`, `x-github-delivery`, `x-github-hook-id`, `stripe-signature`, +`x-slack-signature`, `x-slack-request-timestamp`, `x-slack-retry-num`, `webhook-id`, +`webhook-timestamp` and `webhook-signature`. `user-agent`, the forwarding fields and `referer` +are left out: no use of this version needs them, the first is a fingerprinting surface, the +forwarding fields are spoofable unless a proxy overwrites them, and `referer` can carry a token +from the previous page. The fixed deny includes the proxy fields listed in {{http-request}}. + +The server verifies at most 12 MiB of content. It keeps a delivery's identity until the delivery's +signed timestamp is 360 seconds old, the minimum plus a minute for the difference between a node's +clock and its store's, and a `github` delivery's for 72 hours from acceptance. It offers webhook +verification only over a store that survives a restart, and not over its in-memory store. It sizes +each limit of a webhook account as the owner's own where the operator sets +that limit, so an owner's total compute is at most twice its own limit, and otherwise as a finite +default of its own, over the operator's quota window or else a day: 65536 calls, and +13107200000000 units of fuel, 65536 times the default budget of one invocation, so the count of +calls binds first. Storage and outbound calls take no default of their own; each delivery's own +limits, times the calls the account admits, bound them. Its JavaScript and Python runners let a +script's `handle` function return `{status, headers, body}`, which the runner applies through the +setters. diff --git a/src/content/spec/draft-byrd-restact-mcp-00.md b/src/content/spec/draft-byrd-restact-mcp-00.md new file mode 100644 index 0000000..e6cea67 --- /dev/null +++ b/src/content/spec/draft-byrd-restact-mcp-00.md @@ -0,0 +1,185 @@ +--- +title: "REST:ACT Model Context Protocol Facet" +abbrev: "REST:ACT MCP Facet" +docname: draft-byrd-restact-mcp-00 +category: exp +submissiontype: independent +ipr: trust200902 +area: "Applications" +keyword: + - REST + - WebAssembly + - capability security + - Model Context Protocol + - agents +stand_alone: yes +pi: [toc, sortrefs, symrefs, comments] +author: + - + ins: N. Byrd +normative: + RESTACT: + title: "The REST:ACT Protocol: Invoking Sandboxed Functionality over REST" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-protocol-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-protocol-00.md + MCP: + title: "Model Context Protocol Specification, Revision 2025-06-18" + date: 2025-06-18 + target: https://modelcontextprotocol.io/specification/2025-06-18 +informative: + RESTACT-DELEGATION: + title: "REST:ACT Identity and Delegation" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-delegation-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-delegation-00.md + RESTACT-OBJECTS: + title: "REST:ACT Objects and Data" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-objects-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-objects-00.md + +--- abstract + +This document specifies an optional extension to REST:ACT, the protocol for invoking sandboxed +verbs over HTTP. It defines the MCP facet: a fixed set of four Model Context Protocol tools through +which an MCP client invokes a verb, lists the verbs available to it, and lists and reads objects. +Each tool has the outcome of the equivalent HTTP request made by the same principal. A server +advertises the facet with the `mcp-facet` feature token. + +--- middle + +# Introduction {#mcp-introduction} + +A program that speaks the Model Context Protocol {{MCP}}, such as an agent, calls tools that a +server lists for it. REST:ACT {{RESTACT}} already gives a server verbs to invoke and objects to +read, each governed by policy. This document defines one fixed way to offer them to an MCP client, +so that such a client reaches any server that advertises the `mcp-facet` feature token with the +same four tools, under the authority its credential has over HTTP. + +The decision record for this document is +[ADR-0093](https://github.com/stackumi/restactd/blob/main/spec/decisions/0093-remote-mcp-facet.md) +in the reference implementation. + +## Relationship to REST:ACT {#mcp-relationship} + +This document is a REST:ACT extension, as described in the "Extension specifications" section of +{{RESTACT}}. Its server requirements bind only a server that advertises `mcp-facet`. A requirement +that also names a feature or mechanism of another document, such as the refusal of a path-scoped +sub-token, binds a server that this document binds when that server also offers that feature or +mechanism. A client does not assume any behavior of this document from a server that does not +advertise its token. + +This document uses one of the extension points that section names, E11: {{mcp-facet}} answers a +refusal at `/mcp` in an MCP message, a tool error that carries the Problem Details object or a +JSON-RPC error, where {{RESTACT}} requires an HTTP status and a Problem Details response. It +relaxes no other requirement of {{RESTACT}}. For a cross-origin `POST` to `/mcp`, {{mcp-facet}} +makes mandatory a refusal that {{RESTACT}} recommends. + +{{RESTACT}} reserves the path `/mcp` for this endpoint, on every server. + +{::boilerplate bcp14-tagged} + +# Model Context Protocol Facet (OPTIONAL, feature `mcp-facet`) {#mcp-facet} + +A server MAY expose its verbs and objects to Model Context Protocol {{MCP}} clients through a fixed +set of tools. A server that does so advertises the `mcp-facet` feature token and serves the MCP +Streamable HTTP transport at `/mcp`, under the same base URL as the rest of its interface +(the "Base URL" section of {{RESTACT}}). It MUST NOT +negotiate a revision earlier than the one {{MCP}} specifies, the first with structured tool results; +which later revisions it offers is its choice. The token adds no member to the discovery document. +The facet is another way to reach the interface {{RESTACT}} defines, as the OpenAPI document of +the "Discovery" section of {{RESTACT}} is another way to describe it, and grants no authority of its own. {{RESTACT}} +requires a server that serves the endpoint to advertise the token and forbids any other use of +`/mcp`, so a server on which the facet is off answers requests to `/mcp` as for a path it does not +serve. + +**Requests.** The facet sends no server-initiated messages, so a server answers `GET /mcp` with +`405`. A server MUST authenticate each `tools/call` request on its own, as it does an HTTP request +(the "Authorization and Identity" section of {{RESTACT}}), and run the call as the resulting principal; the anonymous principal is treated as on +the HTTP interface. A server MUST NOT carry an authentication or authorization decision from one +request to another, and SHOULD keep no session state between requests. Because the tool list does +not depend on the caller, a server MAY answer `initialize` and `tools/list` without authenticating +them. A server MUST refuse a call whose credential fails verification, with a tool error carrying a +`401` problem or with an HTTP `401` response. It MUST refuse, for every tool, a credential that +carries less than its principal's full authority, such as the path-scoped and delegated tokens of +{{RESTACT-DELEGATION}}, with a tool error carrying a `403` problem. + +**Tools.** `tools/list` MUST return these four tools, the same for every caller and connection. Each +tool's input schema admits only the members listed for it. + +* `invoke_verb` takes `route`, the route of one verb with every path segment concrete + (`:`, the object path empty for an unbound verb, never a `{id}` pattern), and + an optional object `input`. The server resolves the route as for an HTTP invocation + (the "Verb Resolution and Inheritance" section of {{RESTACT}}) and invokes a function as `GET` and an action as `POST` would, with `input` as + the verb's input. +* `list_verbs` takes no arguments and returns `{"verbs": [...]}`: the `verbs` array of the caller's + discovery document (the "Discovery" section of {{RESTACT}}). +* `list_objects` takes an optional `prefix`, `pageSize` and `pageToken`. On a server that + advertises the `object-listing` feature it returns the object listing `GET /v1` would return the + caller, limited to objects whose path begins with `prefix`; a page MAY hold fewer entries than + `pageSize`, or none, while a `nextPageToken` remains. On a server that does not, it answers with + a tool error carrying a `501` (`unsupported-feature`) problem. (Informative: the listing is the + "Object collection listing" section of {{RESTACT-OBJECTS}}.) +* `get_object` takes `path` and returns the object's stored representation (the "Representations" section of {{RESTACT}}), + as a `GET` of its path served from storage would. It runs no verb. (Informative: an accessor verb + of {{RESTACT-OBJECTS}} is reached through `invoke_verb`.) + +A server MUST NOT list a tool per verb or per route. Further tools, such as tools that write object +data or deploy verbs, and other MCP features such as resources and prompts, come only with a +feature token of their own. + +**Parity.** Each tool's outcome MUST be that of the equivalent HTTP request made by the same +principal: the same policies decide it and the same quotas are charged. A successful result whose +content is JSON is returned as the tool's structured content where the negotiated revision admits +that value there, and other content whose bytes are valid UTF-8 as text. Content whose bytes are not +valid UTF-8 is never turned into text: it is returned base64-encoded, as an image content item for an +`image/*` media type, an audio content item for an `audio/*` media type, and otherwise an embedded +resource whose `uri` is the URI of the equivalent HTTP request. Its `mimeType` is the response's media +type, or `application/octet-stream` when the response has none. A server MAY return content of a media +type that is not textual the same way when its bytes are valid UTF-8. A refusal is a tool error (`isError` true) whose +structured content is the Problem Details object (the "Errors" section of {{RESTACT}}) that the HTTP request would have +received. A verb's own response that an advertised extension admits at E12 of the "Extension +specifications" section of {{RESTACT}} is returned as that extension sets. A server MAY refuse +arguments that do not match a tool's input schema, with a tool error +carrying a `400` (`invalid-input`) problem or with the JSON-RPC invalid-parameters error. A server +MUST NOT rewrite a verb's output. + +**Origin.** A server MUST refuse with `403` (`forbidden`) a cross-origin `POST` to `/mcp` +(the "Security Considerations" section of {{RESTACT}}) unless its origin is one the server names as allowed, or the server allows every +origin and the request is one a browser sends only after a successful preflight. It SHOULD refuse +any other cross-origin request to `/mcp` the same way, and SHOULD refuse a request whose `Host` it +does not recognize. + +# Security Considerations {#mcp-security} + +The facet authenticates every call on its own and carries no +decision from one request to the next, so a credential that stops verifying stops working at the +next call. Without its origin rule, any web page a user opens could call tools on a server that +admits callers without a credential, such as one on the user's own machine. Verb output, object +values and the descriptors `list_verbs` returns are written by other principals, possibly by an +attacker who uploaded a verb, and can carry text aimed at a model. A fixed tool list keeps that +text out of tool names and descriptions, which a client shows its model as instructions; a tool +per verb or route would put it there. A client SHOULD treat every tool result as untrusted data. + +The security considerations of {{RESTACT}} apply. + +# IANA Considerations {#mcp-iana} + +This document requests one registration in a registry that {{RESTACT}} creates: `mcp-facet` +({{mcp-facet}}) in the "REST:ACT Feature Tokens" registry. diff --git a/src/content/spec/draft-byrd-restact-objects-00.md b/src/content/spec/draft-byrd-restact-objects-00.md new file mode 100644 index 0000000..2c03b1b --- /dev/null +++ b/src/content/spec/draft-byrd-restact-objects-00.md @@ -0,0 +1,1113 @@ +--- +title: "REST:ACT Objects and Data" +abbrev: "REST:ACT Objects" +docname: draft-byrd-restact-objects-00 +category: exp +submissiontype: independent +ipr: trust200902 +area: "Applications" +keyword: + - REST + - WebAssembly + - object data + - authorization + - capability security +stand_alone: yes +pi: [toc, sortrefs, symrefs, comments] +author: + - + ins: N. Byrd +normative: + RFC9110: + RFC8785: + RFC6839: + RESTACT: + title: "The REST:ACT Protocol: Invoking Sandboxed Functionality over REST" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-protocol-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-protocol-00.md +informative: + RESTACT-DELEGATION: + title: "REST:ACT Identity and Delegation" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-delegation-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-delegation-00.md + RESTACT-EVENTS: + title: "REST:ACT Events" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-events-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-events-00.md + RESTACT-CONNECTORS: + title: "REST:ACT Connectors" + author: + - + ins: N. Byrd + name: Nathan Byrd + date: 2026-11 + seriesinfo: + Internet-Draft: draft-byrd-restact-connectors-00 + target: https://github.com/stackumi/restact/blob/main/draft-byrd-restact-connectors-00.md + RFC7396: + AIP136: + title: "AIP-136: Custom Methods (Google API Improvement Proposals)" + target: https://google.aip.dev/136 + AIP158: + title: "AIP-158: Pagination" + target: https://google.aip.dev/158 + AIP160: + title: "AIP-160: Filtering" + target: https://google.aip.dev/160 + AIP161: + title: "AIP-161: Field Masks" + target: https://google.aip.dev/161 + JSONAPI: + title: "JSON:API v1.1" + target: https://jsonapi.org/format/ + +--- abstract + +This document specifies an optional extension to REST:ACT, the protocol for invoking sandboxed +verbs over HTTP. It defines what a server may do with the data stored at an object path beyond +reading and writing it whole. A client can list and query the objects under a path and remove a single +property. An object can declare how each of its properties is stored and who may +read or change it. An object's +policy can be inherited from an ancestor, and an object can own the verbs bound to it. A verb can +read and write object data through the `object` capability, and an accessor verb can serve the data +plane for its object. The document also defines deployment history, rollback and conditional +requests on verb management, and a JSON:API representation. A server advertises each feature with +its own token. + +--- middle + +# Introduction {#objects-introduction} + +REST:ACT {{RESTACT}} lets a server store data at an object path and serve it with the ordinary HTTP +methods: `GET` reads the object, `PUT` writes it, and `DELETE` removes it, each gated by the +object's `$policy`. That is enough for a server that keeps object data. +This document defines the optional features that build on it: + +* the object collection listing and its query parameters ({{object-listing}}); +* the object-binding modes, under which an object owns the verbs bound to it, and the rule that + guards creating an object below another principal's ({{object-binding}}); +* policy inherited from a governing ancestor, and governed creation + ({{object-policy-inheritance}}); +* a JSON:API representation ({{optional-json-api-representation}}); +* deployment history and rollback of a verb's code ({{verb-history}}), and conditional requests on + verb management ({{verb-conditional}}); +* the `object` capability, through which a verb reads and writes object data + ({{object-data}}); +* accessor verbs, which serve data-plane methods for an object ({{active-properties}}); +* declared data properties, and the removal of a property by a `null` member of a `PUT` + ({{data-properties}}). + +Each is optional, and a server advertises each one it implements with its own feature token +({{objects-relationship}}). + +## Relationship to REST:ACT {#objects-relationship} + +This document is a REST:ACT extension, as described in the "Extension specifications" section of +{{RESTACT}}. The server requirements of each section bind only a server that advertises a token +that section names, as listed here. A requirement that also names a feature or mechanism of another document, such as a lifecycle hook +or a delegated credential, binds a server that this document binds when that server also offers +that feature or mechanism. A server +that offers a feature with a token advertises the token, and a requirement on a mechanism no token +covers, such as a lifecycle hook outside the data-plane CRUD subset, binds every server that offers +the mechanism (the "Extension specifications" section of {{RESTACT}}). A client does not assume any +behavior of this document from a server that does not advertise its token. A requirement this +document places on a client, or on the author of a verb, binds every client or verb author that +uses the feature or mechanism the requirement concerns. + +| Feature tokens | Section | +|---|---| +| `object-listing`, `object-query`, `object-listing-prefix` | {{object-listing}} | +| `object-binding`, `ancestor-creation-guard` | {{object-binding}} | +| `object-policy-inheritance`, `governed-creation` | {{object-policy-inheritance}} | +| `jsonapi` | {{optional-json-api-representation}} | +| `verb-history` | {{verb-history}} | +| `verb-conditional-requests` | {{verb-conditional}} | +| `object-data-access`, `object-cas`, `verb-object-query`, `object-self-path`, `object-remove`, `object-set-subject`, `object-binary`, `object-binary-write` | {{object-data}} | +| `active-properties`, `set-list-accessors`, `bare-path-accessor-dispatch` | {{active-properties}} | +| `data-properties`, `property-inheritance`, `property-defaults`, `put-null-removes` | {{data-properties}} | +| `binary-values` | {{binary-values}} | + +Most of these features only add requirements. Four of their tokens change a rule of {{RESTACT}}, +each at the extension point that the "Extension specifications" section of {{RESTACT}} names for it, and +only while the token is advertised: + +* `put-null-removes` gives a `null` member of a `PUT` a meaning: it removes the property (E5). +* `object-policy-inheritance` supplies the policy of an object that stores no `$policy` of its own: + that of its nearest governing anchor (E6). +* `active-properties` and `bare-path-accessor-dispatch` serve data-plane methods through accessor + verbs, whose `execute` policy then governs the method (E7). + +A credential's own bounds, wherever this document checks them, are the bounds that an advertised +extension sets on the credential. Such bounds only narrow what the credential may do, which the +"Extension specifications" section of {{RESTACT}} lets any extension do. + +{::boilerplate bcp14-tagged} + +# Object collection listing {#object-listing} + +A server MAY support enumerating the objects that have stored data. When it does, it advertises the +`object-listing` token (distinct from the `data-plane` token for the object data plane itself) and +answers `GET` at the API root (`/v1`) with a JSON object whose `objects` member lists each +client-addressable object the caller may read, as `{ "path", "properties" }` entries (`properties` +is the count of caller-readable members). The listing MUST be filtered by the same per-property read +authorization as `GET` on the object itself, so it never reveals an object — or a property count — +the caller could not already read directly. An object the caller can read but that has zero +caller-readable members MAY be listed with `properties: 0` ONLY when the caller could read the object +directly anyway — for example an empty object the caller OWNS; an object the caller does NOT own and +none of whose members are readable by the caller MUST be omitted entirely (no existence oracle). The reserved internal namespace +(object keys beginning with `@`) MUST NOT appear. + +A server SHOULD paginate the listing ({{AIP158}}): it MAY accept a `pageSize` and a `pageToken` and +return a `nextPageToken` when more results remain, and MAY impose a maximum page size, so a single +request cannot force unbounded work. Because the listing reflects only what the caller may already +read, on an anonymous, public-read deployment it is anonymously enumerable (as the data plane itself +is); a server exposing it to untrusted callers SHOULD require authentication and apply rate limiting. + +A server that advertises the `object-query` token MAY further accept a `filter` parameter +({{AIP160}}) and a `read_mask` parameter ({{AIP161}}) on the listing. The `filter` restricts the +result to objects matching the expression — at minimum a single `key=value` property equality — and +a `key=value` literal matches a stored string byte-for-byte, and any other stored value whose canonical +form {{RFC8785}} equals the literal parsed as JSON (so `n=3` matches `"3"` and `3`). +`read_mask` is a comma-separated set of property names whose values are projected into a `values` +member on each entry. Both MUST operate over only the caller-readable members: a property the caller +cannot read MUST NOT match a `filter` and MUST NOT be projected by `read_mask`, so neither parameter +reveals a value the caller could not already read with `GET` on the object. A malformed `filter` +SHOULD be rejected with a `400` problem (`invalid-filter`) rather than answered with an empty +result. The field mask is spelled `read_mask` on this listing, not the `readMask` of the +"Collections: Listing, Pagination, Filtering, Field Masks" section of {{RESTACT}}. + +A server that advertises the `object-listing-prefix` token accepts a `prefix` parameter on the +listing. Its value, decoded as `application/x-www-form-urlencoded` (so `+` is a space and `%2B` a +literal `+`), is either empty, which is the same as no `prefix`, or ends in `/`. The server MUST then +list only objects whose path begins with that value, compared code point by code point, +case-sensitive and with no normalization: `ws/1/` lists every object below `ws/1` and not `ws/1` +itself. The prefix only narrows the listing; authorization, `filter`, `read_mask`, pagination and +any page-size limit apply exactly as without it. A server MUST reject with a `400` problem +(`invalid-input`) a non-empty prefix that does not end in `/`, and a prefix that no object path can +begin with: one that begins with `/`, contains `//`, or has a segment beginning with `@`. It MAY +reject a prefix holding a character it cannot store in the same way. The trailing `/` keeps a timed +probe to whole path segments ({{objects-security}}). A `pageToken` is bound to the prefix it was issued +under, and the server MUST reject it with a `400` problem (`invalid-input`) when it arrives with a +different prefix or none. A server that does not advertise the token may ignore the parameter, so a +client MUST NOT send it unless the token is advertised. + +# Object Binding {#object-binding} + +A verb is always *bound to* an object — the object named before the colon in its definition path. How +that binding relates to the **existence** of the object varies by deployment: in a function-as-a- +service style, a verb is a free-standing program and the object is merely an addressing handle; in an +object-oriented style (the MOO lineage, after which the "The simple (MOO-style) profile" section of {{RESTACT}} is named), the +object is a first-class entity that must exist before a verb can be defined on it, and it *owns* its +verbs. Rather than prescribe one, this +document defines a vocabulary of **object-binding modes** and requires a server to advertise the one +it enforces in discovery, as the `objectBinding` member of the discovery document's `service` +object, which a server omits for `implicit` (the "Discovery" section of {{RESTACT}}). This is server policy, not a per-verb declaration; a server +MUST NOT advertise a mode it does not enforce. + +The modes are: + +* **`implicit`** — the object and the verb plane are independent. Deploying a verb neither requires + nor creates the object it binds to, and an object's stored data is independent of the verbs defined + on it. It is the mode {{RESTACT}} defines and assumes, and a server whose discovery document + names no mode uses it (the "Conformance and Feature Discovery" section of {{RESTACT}}). Which mode a server uses by default, and when + it warns its operator, follows the "Conformance and Feature Discovery" section of {{RESTACT}}, + which binds every server that supports `strict`. +* **`auto-create`** — the object is the entity that owns its verbs. Deploying a verb on an object that + does not yet exist MUST create that object (an empty, caller-owned record), so it thereafter appears + in the object data plane and listing. +* **`strict`** — the same coupling as `auto-create`, except that deploying a verb on an object that + does not yet exist MUST be refused (a `409`), rather than creating it. + +The two coupled modes (`auto-create`, `strict`) test existence against the **deepest concrete +ancestor** of the verb's binding path: the longest prefix of literal (non-wildcard) segments. A verb +bound to a concrete object (`a/b:verb`) tests `a/b`; a *bound* entity verb whose path ends in a +wildcard (`counters/{id}:verb`) tests its concrete collection ancestor (`counters`); an **unbound** +verb (`/:verb`) binds to no concrete object and is exempt. A verb whose binding path *begins* with a +wildcard (`{id}:verb`) has no concrete ancestor yet binds to every entity; under a coupled mode a +server MUST refuse it with `409` (`object-binding`), since it owns no object, rather than treat it +as exempt. Existence is tested against +the server's object registry, not against the caller's read authorization: an object the caller may not +read still exists for this test, so a coupled mode never creates it again or binds a verb to it for +that caller. Only the answer such a caller receives differs ({{objects-non-reader}}). + +Under a coupled mode, because the object owns its verbs, a server MUST require that the caller is +authorized to **write** the object before defining, replacing, or removing a verb on an object that +already exists — whether the verb is created by upload or by writing its `code`/`policy` property +(the "Verb properties (the program itself)" section of {{RESTACT}}). Defining a verb on an object owned by another principal MUST be refused +(`403`, or, to a caller who may not read the object, the answer an absent object would get, +{{objects-non-reader}}), and the existence rule above applies equally to these property writes (a `strict` server MUST +NOT let `PUT …:verb/code` shadow a verb onto a non-existent object). Creating the first verb on a +not-yet-existing object under `auto-create` makes the caller its owner. This keeps every verb on an +object within the authority of that object's owner, so the cascading `DELETE` below can never remove a +verb the caller could not have removed directly. + +**Ancestor creation.** Under a coupled mode, or on a server that advertises +`object-policy-inheritance`, an object's ancestors carry authority over it: definitions bound on +an ancestor resolve for it (the "Verb Resolution and Inheritance" section of {{RESTACT}}), lifecycle hooks bound there observe its writes +(the "Events, Triggers, and Scheduling" section of {{RESTACT-EVENTS}}), and a governing anchor governs its policy ({{object-policy-inheritance}}). Such a +server, when it has authentication configured, MUST refuse a write that would create an object +while any object stored below the new object's path is owned by a principal other than the +principal the write would record as the new object's owner, with `409` (`ancestor-claim`). For +this rule, an object with no recorded owner and an object owned by the anonymous identity are each +foreign to every writer. (The "Ownership is fixed" section of {{RESTACT}} treats the first as owned +by the anonymous identity only for its own rule and for a `$policy` write.) The refusal MUST NOT identify the object below or its +owner, and SHOULD state that resubmitting the request unchanged will not succeed. A server +evaluates this rule after every other check that would refuse the write (authentication, the +creation rule of a governing anchor, and write authorization); a write refused for another +reason receives that refusal. A server MAY bound the work it spends on this check. A creating +write whose check reaches the bound is refused as if such an object existed, and the refusal's +status, code and detail MUST NOT reveal which of the two occurred. The rule applies to every +interface that can create an object, including a verb's object writes and the object an +`auto-create` deployment would create; a deployment whose object creation the rule refuses MUST +itself be refused. For a write a verb performs, a server reports the refusal to the verb as that +write's error with this code where it can decide it at the write; a refusal it can decide only +when the invocation's writes commit discards them as the "Consistency" section of {{RESTACT}} specifies. A server MAY +exempt the operator subjects named in its configuration, under the restrictions of +the "Operator ownership recovery (OPTIONAL, feature `admin-reown`)" section of {{RESTACT-DELEGATION}} (never a role, group, scope, claim, `public` or `owner` matcher, never the +anonymous identity, a path-scoped sub-token or a delegated request), for requests whose write the +server performs itself rather than through a verb (including an accessor) or hook, and MUST NOT +extend that exemption to a write performed by a verb or hook. The rule governs creation only: it +does not remove, re-own or refuse objects or verbs that already exist, and does not restrict +creating an object below an existing one. A server with authentication configured that enforces +it advertises the `ancestor-creation-guard` feature token, and MUST do so whenever its advertised +object-binding mode is `auto-create` or `strict`, or it advertises `object-policy-inheritance`. + +Object **deletion** is symmetric with the mode. Under a coupled mode, `DELETE` on an object removes +the object together with the verbs bound *exactly* to it (not those merely inherited from an ancestor +or matched through a `{id}` pattern, which belong to other objects) and any object-scoped state those +verbs declared; under `implicit`, `DELETE` removes only the object's stored data and leaves its verbs +in place. The cascade MUST be **fail-closed**: a server MUST refuse the object `DELETE` (rather than +remove anything) unless the caller is authorized to delete *every* verb the cascade would remove — the +same authority a direct `DELETE /obj:verb/code` requires — so the cascade can never remove a verb the +caller could not have removed directly. A coupled `DELETE` also removes every definition whose +binding path's deepest concrete ancestor is the deleted object, under the same fail-closed precheck. +Removing a verb (`DELETE /obj:verb/code`) never deletes the object in any mode. + +The mode governs **deployment and deletion** only; it does not change **invocation**. A deployed verb +is still invoked on any concrete object the resolution rules (the "Verb Resolution and Inheritance" section of {{RESTACT}}) match — including an +entity instance that does not yet hold data — and the verb's own writes bring that instance into +existence, exactly as under `implicit`. + +# Prefix-inherited object policy {#object-policy-inheritance} + +A server MAY additionally support **prefix inheritance** of object policy, advertised as the +`object-policy-inheritance` feature. When supported, `$policy` accepts an OPTIONAL boolean member +`inherit`; a policy with `inherit: true` is a **governing anchor**. The effective policy for an +object is resolved as: (1) if the object stores its own `$policy` (including an empty `{}`), that +policy governs, with `owner`/`prop:` matchers resolving against the object's own `$owner`/members; +(2) otherwise, the nearest strict ancestor (by path hierarchy, nearest first) whose stored `$policy` +is a governing anchor supplies the WHOLE effective policy, with its `owner`/`prop:` matchers +resolving against the ANCHOR's `$owner`/members — an unmarked ancestor policy governs only its own +object and is skipped in this walk; (3) otherwise the omitted-policy defaults apply. A server that +does not advertise the feature ignores the `inherit` member, as the "Native representation" section +of {{RESTACT}} requires. + +Under a governing anchor the effective policy governs descendants **absolutely**: a descendant's own +`$owner` receives no exemption (so revoking a subject at the anchor revokes it everywhere beneath). +Two rules protect the tree: **creation** — a first write that would create a new object under a +governing anchor MUST be admitted by the anchor's `write` policy before first-writer-owns assigns +`$owner` (a denied create behaves as not-found when the creator also cannot read the location, else +as forbidden); and **descendant-policy management** — writing a descendant's own `$policy` (including +the `{}` opt-out) under a governing anchor is a **manage** act that MUST require the anchor's owner, +in place of the descendant's own (the "Native representation" section of {{RESTACT}}). Creating an object is also subject to the ancestor-creation rule +({{object-binding}}). An object's own declared-member ACLs, and the rule that ownership is fixed +(the "Ownership is fixed" section of {{RESTACT}}), are unchanged by inheritance. When the feature is enabled, `?meta=policy` gains an additive +`source` member — `"self"`, `"default"`, or the governing anchor's path — reporting where the +effective policy came from; the `raw=1` view is unchanged (the object's own stored record, including +an `inherit` marker if present). An object's entity tag covers only its own stored `$policy` (the +"Consistency" section of {{RESTACT}}): changing a governing anchor's policy changes the anchor's tag +and not the tags of the descendants it governs, so a client that rewrites a descendant's policy from +its inherited view cannot make that write conditional on the anchor's. + +**Governed creation (OPTIONAL, feature `governed-creation`).** The creation rule above governs only +paths a governing anchor reaches; where none does, first-writer-owns applies and the omitted-policy +defaults (the "Native representation" section of {{RESTACT}}) make the new object world-readable and owned by whoever wrote first. On a +multi-principal deployment that is a squatting surface at every never-yet-written path. A server MAY +therefore support a stricter regime, advertised as the `governed-creation` feature and available +only on a server that also supports prefix inheritance. Under it, a write that would create an +object is admitted only if **either** a governing anchor reaches the path (in which case the rule +above applies unchanged) **or** that same write itself carries an explicit `$policy` for the object +being created — the object self-governs from birth. A creating write satisfying neither MUST be +refused with `403`, and MUST NOT be refused with `404`: there is no anchor whose read-denial a +not-found could mirror, and a server without the feature already discloses strictly more through the +same probe. An explicit `$policy` satisfies the rule whether or not it is a governing anchor +(`inherit: true`); requiring the marked form would make every seeded intermediate parent an anchor +and thereby block the very descendant creations it was seeded to permit. + +This is a **client-observable change to the calling convention**, which is why it takes a feature +token rather than being a silent operator setting: a client that creates an object and then writes +its `$policy` as a second request MUST merge them into a single creating write when the token is +advertised. The feature governs creation only — it applies no retroactive requirement to objects +that already exist, and does not change reads, deletes, ownership (the "Ownership is fixed" section of {{RESTACT}}), or policy management. + +# Optional JSON:API representation {#optional-json-api-representation} + +A server MAY offer the JSON:API media type {{JSONAPI}} (`application/vnd.api+json`) as a +content-negotiated alternative representation, in which child and verb paths are expressed as +`relationships` links. When serving JSON:API, a server MUST NOT use JSON:API's colon-prefixed +extension-member mechanism, as `:` is reserved by {{RESTACT}} as the verb separator. + +# Deployment history and rollback (OPTIONAL, feature `verb-history`) {#verb-history} + +This profile adds two properties to a verb (the "Verb properties (the program itself)" section of +{{RESTACT}}): + +~~~ +GET /obj:verb/history read deployment history +POST /obj:verb/rollback roll code back to a prior deployment +~~~ + +Because every code replacement (the "Verb properties (the program itself)" section of {{RESTACT}}) simply overwrites a verb's registration, an +implementation that retains no further record makes a bad redeploy unrecoverable in place and +attributes no deployer identity distinct from the (possibly unchanged) owner. A server MAY support +this OPTIONAL profile, advertised via the `verb-history` feature token (the "Discovery" section of {{RESTACT}}), to make +deployment reversible without a client round-trip of code bytes. + +**History.** A server supporting this profile MUST maintain, per verb registration, a bounded, +newest-first history of the deployments a code replacement has SUPERSEDED, and MUST expose it via +`GET …:verb/history`. Each entry MUST identify the superseded version's full **hash triple** — the +executable's content address, and, for a source-language verb (the "Verb code: source and executable" section of {{RESTACT}}), the source's content +address together with its media type — and SHOULD additionally record the deployer's identity, when +the code landed, and when it was superseded. A history entry MUST NOT be pushed when a property +write does not change the effective hash triple (for example, a policy-only replacement of +`policy`): pushing on every unrelated write would make the history record cost unbounded in the +number of touches rather than the number of code changes. The response MUST NOT include the code's +bytes; access is governed by the verb's `write` action (the "Authorization and Identity" section of {{RESTACT}}), since a principal entitled to +replace the code is already entitled to see its lineage, while a principal that may merely `execute` +the verb MUST NOT. A server MAY bound the retained history to a fixed depth per registration, +discarding the oldest entries first, and MUST document that bound. + +The `history` response is a JSON object. Its members `sha256`, `sourceSha256` and +`sourceMediaType` give the current version's hash triple, and its `history` member is the array +of entries, newest first. An entry is a JSON object whose `sha256` is the executable's content +address and, for a source-language verb, whose `sourceSha256` and `sourceMediaType` are the +source's content address and media type. For a verb with no source, the response and each entry +omit both members. A content address is the SHA-256 digest of the bytes, written as 64 lowercase +hexadecimal digits. An entry MAY carry +`kind` (`function` or `action`), `deployedBy` (the deployer's subject) and `supersededAtUnix` (when +it was superseded, in seconds since the Unix epoch), and the object MAY carry `kind`, +`deployedBy` and `codeDeployedAtUnix` for the current version. A client ignores a member it does +not recognize. + +**Rollback.** A server supporting this profile SHOULD expose `POST …:verb/rollback` to rebind a +verb's code to a version named in its own history. The request body MUST supply an **expected echo** +of the target entry's full hash triple: a JSON object holding the entry's `sha256` and, exactly +when the entry has them, its `sourceSha256` and `sourceMediaType`, with the values the `history` +response gave. The server MUST refuse the request (`409`) if no entry in +the CURRENT history matches the echo exactly — a stale echo (superseded again since the client last +read `history`, or naming an entry evicted by the retention bound) MUST be refused rather than +silently applied to a different version, so a concurrent redeploy cannot be raced into a rollback the +client did not intend. A rollback of a **wasm** verb rebinds `code` to the named executable +directly. A rollback of a **source-language** verb MUST re-run source deployment (the "Verb code: source and executable" section of {{RESTACT}}) +against the server's CURRENT runtime registered for the entry's source media type, using the +entry's stored source — it MUST NOT reinstate whatever runtime component was current when that +source was originally deployed, since a source-language verb's semantic identity is its source, and +the runtime is host-provided infrastructure a server may have since upgraded. If either the target +executable or source cannot be retrieved, the server MUST fail the request rather than silently no-op. +Because a rollback IS a code replacement, it is authorized identically to `PUT …:verb/code` +(the "Verb properties (the program itself)" section of {{RESTACT}}) — including the runs-as-owner and, where supported, invoker-grant +(the "Caller Identity" section of {{RESTACT}}) restriction to the owner, and the lifecycle-hook restriction to the +owner (the "Events, Triggers, and Scheduling" section of {{RESTACT-EVENTS}}) — except that, under a coupled object-binding mode +({{object-binding}}), a server MUST exempt rollback from that mode's ancestor-ownership +requirement, since a rollback can only rebind code to a hash triple already recorded in the +route's own history, named by an exact expected echo, and therefore never introduces code the +caller was not already authorized to install. It MUST itself push the ROLLED-BACK-FROM +version into history, so that rolling forward again is simply another rollback. A rollback MUST NOT +change the verb's owner or policy, and MUST NOT accept parameters that would. + +# Conditional verb management (OPTIONAL, feature `verb-conditional-requests`) {#verb-conditional} + +A server MAY support conditional requests on the verb-property plane (the "Verb properties (the program itself)" section of {{RESTACT}}) and its +deployment profile (the "Verb declaration (deployment profile)" section of {{RESTACT}}), advertised via the `verb-conditional-requests` feature token +(the "Discovery" section of {{RESTACT}}). It lets a client change a verb without silently overwriting a concurrent change, +and create a verb without silently replacing one a concurrent deployer created. A server that does +not advertise the token need not honour these preconditions (the "Verb properties (the program +itself)" section of {{RESTACT}}). (Informative: +the reference host honours `If-Match` on `PUT …:verb/code` whether or not it advertises the token.) + +**Per-property validators.** A server supporting this profile MUST give each mutable verb property +its own strong entity tag ({{RFC9110}}, Section 8.8.3): `code`, whose tag is the one `GET …:verb/code` returns for +the verb's source representation (or its executable, for a verb with no source representation, +the "Verb code: source and executable" section of {{RESTACT}}); `policy`; and, where the server exposes it, `props` (in the +representation of {{data-properties}}). A `GET` of +each MUST carry its tag in `ETag`, and a successful `PUT` of it, or a rollback ({{verb-history}}) +for `code`, MUST return the property's new tag. A property's tag MUST change whenever that +property's value changes and MUST NOT change when only a different property changes, so a policy +change never invalidates a precondition on the code, nor the reverse. A server MAY return the same +tag for an identical value. + +**Preconditions on writes.** A server supporting this profile MUST honour `If-Match` on +`DELETE …:verb/code`, on `POST …:verb/rollback`, on `PUT …:verb/policy` and on `PUT …:verb/props`, +as well as on `PUT …:verb/code`. A rollback's precondition is compared against the CURRENT `code` +tag, the version the rollback would supersede; it is independent of the request's expected echo, +which names the target. The comparison is strong, and `*` matches any existing verb. On a mismatch +the server MUST respond `412` (`precondition-failed`, the "Errors" section of {{RESTACT}}) and change nothing. Each +precondition is compared against the property as a `GET` at the request's own path would serve it +(the "Verb Resolution and Inheritance" section of {{RESTACT}}). + +**Create-only deployment.** A server supporting this profile MUST honour `If-None-Match: *` on its +deployment profile (`POST /v1/modules` in the reference profile). If the request would otherwise be +a replacement (the "Verb declaration (deployment profile)" section of {{RESTACT}}), because a definition exists on the same path pattern and verb name, +the server MUST respond `412` and change nothing, unless the deployer could not have replaced the +existing verb, in which case that refusal (`401`/`403`) comes first (Evaluation, below). Path +patterns are compared as for replacement (the "Verb declaration (deployment profile)" section of {{RESTACT}}); a server that accepts other spellings of +a pattern MUST canonicalize them identically for both comparisons. The existence check and the creation MUST be one atomic step: of +concurrent create-only requests for the same pattern and verb name, at most one succeeds, and every +other receives `412`. `If-None-Match: *` is the only precondition the deployment profile accepts +under this profile; a server MUST refuse any other `If-None-Match` value, and any `If-Match`, with +`400` (`invalid-input`) rather than ignore it. This deliberately fails loud where an unsupported +precondition is commonly ignored: a client that expected a conditional replacement must not +silently replace. A conditional replacement uses `If-Match` on `PUT …:verb/code`. + +**Evaluation.** Authentication, authorization (the "Authorization and Identity" section of {{RESTACT}}) and any object-binding refusal +({{object-binding}}) MUST be decided before these preconditions are evaluated, so a caller without +authority for the write receives that refusal and learns nothing from the tag comparison. Other +failures are ordered as {{RFC9110}}, Section 13.2.1 allows: a server MAY answer `412` before it +validates the request content, for example for a stale `If-Match` on a `PUT …:verb/code` whose body +is also invalid, or a create-only deployment whose module it has not yet compiled. Apart from create-only, a precondition here carries +at least the best-effort semantics of the `conditional` level (the "Consistency" section of {{RESTACT}}). A server SHOULD +evaluate it in the same serialized step as the write, so that at most one of two concurrent +conditional writers to the same property succeeds. + +# Object Data Access {#object-data} + +The "world" tier of the "Capability Model" section of {{RESTACT}} is an OPTIONAL feature (token `object-data-access`). Its first increment lets +a verb read and write the **declared data properties** ({{data-properties}}) of the object it is +bound to, through a gated `object` capability interface the verb imports: + +* `path() -> option` returns the path of the bound object itself (OPTIONAL feature, token + `object-self-path`). The value MUST be the **concrete** object the verb was invoked on, never the + route pattern the verb was deployed at: a verb deployed at `ws/{id}/pages/{id}:render` and invoked + on `ws/w1/pages/p3` MUST read `ws/w1/pages/p3`. It MUST be none when, and only when, there is no + bound object — an `unbound` verb (the "Verb Resolution and Inheritance" section of {{RESTACT}}), or a verb the server has not granted the `object` + capability. It is a property of the INVOCATION: a server MUST NOT vary it with the runs-as-caller + principal (so a verb executing under runs-as-owner reads the object it was addressed at, not its + owner's), and under composition each frame MUST observe its OWN bound object rather than its + caller's. Where a server dispatches an invocation the caller did not name — a representation + accessor ({{active-properties}}) or a lifecycle hook (the "Events, Triggers, and Scheduling" section of {{RESTACT-EVENTS}}) — the value is the concrete + object dispatched for, respectively the requested object and the mutated one. It is a pure read + disclosing only what the caller supplied in the request URL, so it grants no authority and a + `function` verb MAY call it. +* `get(name) -> option` reads a property of the bound object. A property the caller is not + permitted to read (per its ACL, {{data-properties}}) is indistinguishable from an absent one + (both return none). A value is a `property-value`: `text` carries a stored string raw, and `json` + carries any other JSON value as JSON text in the RFC 8785 canonical form {{RFC8785}} (feature + `typed-values`; top-level `null` is not a value). A write of `json` whose text is invalid, breaks + the number rule (the "Representations" section of {{RESTACT}}) or is `null` fails with `invalid-input`, and a `json` that + parses to a string is stored as that string. The same type is used by `set`, `get-at`, `set-at` + and `set-at-if` (including its `expected`), and in the `query` row. +* `set(name, value) -> result<_, invocation-error>` writes a property of the bound object. A write the caller + is not permitted to make returns `forbidden`; when the caller may not read the object it returns + what a write to an absent object would (`not-found`, or the creation refusal, {{objects-non-reader}}). A + write to an already-set write-once (`final`) property returns `property-final`. +* `get-at(path, name) -> option` reads a property of another object (an ancestor on the + inheritance chain, or any other path), gated by that object's `read` policy and the property's read ACL — both must allow. As with + `get`, a read-denied property is indistinguishable from an absent one. +* `set-at(path, name, value) -> result<_, invocation-error>` writes a property of another object by path. The + write is permitted only where the **runs-as-caller** principal could have written it directly (the + cross-object write-policy intersection), so a verb is never a confused deputy; the same + `forbidden`/`not-found`/`property-final` rules as `set` apply, and the + reserved (`@`/`$`) namespaces and `shared`-scoped properties are refused. +* `set-at-if(path, name, value, expected) -> result<_, invocation-error>` writes a property of another object + by path only if its stored value equals `expected`; otherwise it fails with `precondition-failed` + and writes nothing (OPTIONAL feature, token `object-cas`). It is authorized, and refused, as a + `set-at` of the same `path` and `name` is, except where its `expected` is not compared (below). + `expected` is compared with the stored value by stored form: a string byte-for-byte, any other + value by its canonical form, and a string never equals a non-string. An `expected` of none + matches a property that is not set. The comparison is made only for a principal who may read the + property. Where an object is stored at `path` and a `get-at` of the same `path` and `name` would + withhold the property from the principal for want of read authority (the object's `read` policy, + the property's read `acl`, or any other bound on what the principal or its credential may read), + the server MUST NOT compare `expected` with the stored value or with anything else stored with + the object: once the authority the write needs is decided, and before `final` or any other check + on stored state, the call MUST fail with `precondition-failed` and write nothing, whatever + `expected` is, none included. The server MUST decide whether the principal may read on the state + the comparison would be made against, in one atomic step with it. Were the comparison made, a + failed call, which changes nothing, would let a principal who may write a property and may not + read it test guesses at its value, and `get-at` does not tell that principal even whether the + property is set. This failure does not clear on a retry, so a verb's compare-and-swap loop needs + a bound, and a verb that must compare-and-swap for such a principal needs to run under an + authority that may read the property. At a path that holds no object nothing is stored, and + `expected` is evaluated as for any caller; that discloses only whether an object exists there, + which a principal who may write it is not kept from learning + (the "Refusing a caller who may not read" section of {{RESTACT}}). +* `set-subject(name) -> result<_, invocation-error>` and `set-subject-at(path, name) -> result<_, invocation-error>` + write, as the value of a property of the bound object or of the object at `path`, the subject of + the frame's **runs-as-caller** principal (OPTIONAL feature, token `object-set-subject`). The + value is the real subject, the string that the `owner`, `sub:` and `prop:` matchers compare (the + "Authorization policy" section of {{RESTACT}}), whatever form the `identity` interface gives the + verb (the "Caller Identity" section of {{RESTACT}}). A verb uses it to name its caller in a + property that a `prop:` matcher reads, which a pairwise subject cannot do. In a frame that + runs as the verb's owner or as a registrant (the "Execution identity" section of {{RESTACT}}), + the principal is that owner or registrant, not whoever invoked the verb, and no function writes + the real subject of the frame originator. Each call is authorized, refused and committed exactly + as a `set` or a `set-at` of the same property with a string would be, whoever the principal is, + and a `function` verb that calls either gets `forbidden-side-effect`. Only a call that would + otherwise succeed depends on the subject: for the anonymous principal, which has none, it fails + with `forbidden` and writes nothing. The + functions return nothing of the subject, but the property then holds it, and whoever may read the + property reads it, the verb's own later `get` included: the functions add a convenient way to + learn the caller's real subject to the ways this capability already gives (the "Security + Considerations" section of {{RESTACT}}), and no protection against a verb that wants it. +* `remove(name) -> result<_, invocation-error>` removes a property of the bound object (OPTIONAL feature, token + `object-remove`). Afterwards the property reads as one that was never set: absent, or, for an + `inherit` property, the inherited value or the declared `default` ({{data-properties}}). It is + authorized exactly as a `set` of the same name, and a `shared`-scoped property is removed from the + state of its declaration, where `set` writes it. Removing a property that is not set succeeds and + changes nothing. +* `remove-at(path, name) -> result<_, invocation-error>` removes a property of another object by path (token + `object-remove`), under the same cross-object write-policy intersection as `set-at`: it is + permitted only where the **runs-as-caller** principal could have written that property directly, + so a verb is never a confused deputy. It returns `not-found` when no object is stored at `path`, + since a removal never creates an object, and it refuses the reserved (`@`/`$`) namespaces and + `shared`-scoped properties as `set-at` does. A `remove-at` of the verb's own bound object is + equivalent to `remove`. +* `shape() -> object-shape` and `shape-at(path) -> object-shape` enumerate an object's shape — the + `properties` it exposes (readable property names), its direct `children` (readable child object + paths), and the `verbs` invokable on it — each ACL-filtered against the runs-as-caller principal + (verb names follow the runs-as-caller principal's discovery listing (the "Discovery" section of {{RESTACT}})). `shape` reflects committed state. +* `get-bytes() -> option>>` and `get-bytes-at(path) -> option>>` read the binary value ({{binary-values}}) of the bound object or of the object at + `path`, as its media type and its bytes (OPTIONAL feature, token `object-binary`). Each is gated by + the `read` policy of the object it reads, as a `GET` of that object by the **runs-as-caller** + principal would be. An absent object, an object with no binary value, an object the caller may not + read and a path that does not address an object all return none, so the call is no existence + oracle. An unbound verb's `get-bytes`, and either call by a verb the server has not granted the + `object` capability, also return none. Both see the invocation's own earlier `set-bytes` and + `set-bytes-at`. A server that fails to read a stored value MUST fail the invocation rather than + return none. A server MAY fail the invocation with `memory-limit` when the value is larger than a + bound it sets for the frame's memory. Both are pure reads, so a `function` verb MAY call them. +* `set-bytes(content-type, data) -> result<_, invocation-error>` and `set-bytes-at(path, content-type, data) -> + result<_, invocation-error>` write the binary value of the bound object or of the object at `path` (OPTIONAL + feature, token `object-binary-write`). Each is authorized exactly as a binary `PUT` of that object + by the **runs-as-caller** principal would be ({{binary-values}}), and `set-bytes-at` under the same + cross-object write-policy intersection as `set-at`, so a verb is never a confused deputy. + A `content-type` that is not exactly one media type, that contains a control character, or that + is one of the JSON media types of {{binary-values}} fails with `invalid-input`; an empty one + stores `application/octet-stream`. A `set-bytes-at` whose path does not address an object, such + as an empty path or one in the reserved `@` namespace, fails with `forbidden`. A value over the + server's size cap fails with `object-too-large` and a refused write with `forbidden`; when the + caller may not read an existing object, the result is what the same call gets with nothing stored + there ({{objects-non-reader}}). The object's properties are left as they are. `set-bytes` commits + with the verb's own bound-object writes and `set-bytes-at` commits as `set-at` does, and a + `set-bytes-at` of the bound object is equivalent to `set-bytes`. A `function` verb that calls either + gets `forbidden-side-effect`. A server that advertises `object-binary` or `object-binary-write` MUST + also advertise `binary-values`. +* `query(prefix, order-by, descending, predicate, limit, cursor) -> query-page` reads a PAGE of the + objects under a path prefix — each row carrying the object's path and its caller-**readable** + property map — in ONE call, rather than one `get-at` per property per object (OPTIONAL feature, + token `verb-object-query`). Rows order by the named property's type first (strings and absent, then numbers, + booleans, arrays, objects), then within a type: strings bytewise, with an absent property + ordering as the empty string, numbers numerically, `false` + before `true`, arrays and objects unordered, with the path breaking ties (`order-by` absent = path + order). `predicate` is a single `key == literal` equality, the + literal being a string that matches a stored string byte-for-byte and any other stored value whose + canonical form equals the literal parsed as JSON, applied to the **readable** value, so a property the caller may not read never matches and the filter is no + information-leak oracle; `cursor` is an opaque keyset continuation the caller threads back + unmodified. A server MUST bound the page: it MUST clamp `limit` to a server-chosen maximum and + MUST NOT interpret any `limit` as unbounded, so a guest cannot force an unbounded result set into + its runtime. A page MAY be shorter than `limit` while further rows remain, so a caller MUST drive + pagination off the returned cursor rather than off a short page. Every row is filtered by exactly + the gate `get-at` applies — the query is an access *accelerator*, never a widening of authority — + and it is a pure read, so a `function` verb MAY call it. + +Access is evaluated against the **runs-as-caller** principal (the "Authorization and Identity" section of {{RESTACT}}): a verb can read or write a +property only where the caller could on the data plane — where the object's own policy allows it **and** the property's ACL allows it. The capability is gated +exactly like composition — a server MUST link it only for components that import it, and a server +that does not implement `object-data-access` MUST refuse at upload a component that imports the +`object` interface, with `403` (`disallowed-import`), as it refuses any import it does not implement +(the "Capability Model" section of {{RESTACT}}). Property storage +semantics (scope `instance`/`shared`, `final`, ACL) are those of {{data-properties}}; a value is a +`property-value` as above. + +The interface is `object` in the WIT package `rest-act:plugin` (the "Guest Contract (WIT package +`rest-act:plugin`)" appendix of {{RESTACT}}). Its types and functions are the following. Each function is bound to the feature +token given for it above, and `object-data-access` covers those for which no other token is given. +The error of a `result` is the package's `invocation-error`, whose `code` is a registered +`restact_code` (the "Errors" section of {{RESTACT}}). + +~~~ wit +interface object { + use types.{invocation-error}; + + variant property-value { text(string), json(string) } + + record object-shape { + properties: list, + children: list, + verbs: list, + } + + record query-cursor { order-value: string, path: string } + + record query-object { + path: string, + properties: list>, + order-value: property-value, + } + + record query-page { + objects: list, + cursor: option, + } + + path: func() -> option; + get: func(name: string) -> option; + set: func(name: string, value: property-value) + -> result<_, invocation-error>; + get-at: func(path: string, name: string) + -> option; + set-at: func(path: string, name: string, + value: property-value) + -> result<_, invocation-error>; + set-at-if: func(path: string, name: string, + value: property-value, + expected: option) + -> result<_, invocation-error>; + set-subject: func(name: string) + -> result<_, invocation-error>; + set-subject-at: func(path: string, name: string) + -> result<_, invocation-error>; + remove: func(name: string) -> result<_, invocation-error>; + remove-at: func(path: string, name: string) + -> result<_, invocation-error>; + shape: func() -> object-shape; + shape-at: func(path: string) -> object-shape; + get-bytes: func() -> option>>; + get-bytes-at: func(path: string) + -> option>>; + set-bytes: func(content-type: string, data: list) + -> result<_, invocation-error>; + set-bytes-at: func(path: string, content-type: string, + data: list) + -> result<_, invocation-error>; + query: func(prefix: string, order-by: option, + descending: bool, + predicate: option>, + limit: u32, cursor: option) + -> query-page; +} +~~~ + +In a `query-object`, `properties` is sorted by name, and `order-value` is the value the row was +ordered on: the `order-by` property, or the path as `text` when `order-by` is none, and `text("")` +when the property is absent. A `query-cursor` is opaque to the verb, which passes back the one it +received unchanged. + +Whether mutations are durable, and their consistency across a composition tree, follow the server's +advertised consistency level (the "Consistency" section of {{RESTACT}}). At every level, a verb's writes +to its own bound object are buffered and committed only when the invocation succeeds; a server +advertising only `conditional` MAY apply that commit property by property, last-writer-wins +against concurrent writers, rather than as one atomic step. A `set-at` write +to a foreign object commits at the call rather than as part of the verb's bound-object transaction — +so on a server advertising only `conditional`, a foreign `set-at` is NOT rolled back if the invoking +verb later traps; only the verb's OWN bound-object writes (buffered and committed on success) are +atomic with the invocation. A precondition on an action request is therefore refused (the +"Consistency" section of {{RESTACT}}). A verb that needs a lost-update-free write makes it through +its object capability instead (`object-cas`). A server providing a transactional consistency level +MAY make the whole tree atomic. + +A server that advertises both `atomic-conditional` (the "Consistency" section of {{RESTACT}}) and +`object-cas` exposes the atomic compare-and-swap of `atomic-conditional` to verb code as a +per-property compare-and-swap on the object capability, a write conditioned on the property's current value, so a verb can run a +read-modify-write loop that loses no update. At the `atomic-invocation` level (the "Consistency" +section of {{RESTACT}}) a server MUST NOT admit the `object-cas` compare-and-swap within an +invocation — the call MUST fail without writing — and MUST NOT advertise the `object-cas` feature: +a compare-and-swap commits against committed state synchronously and therefore cannot join a +buffered frame. A server MAY re-admit it at the `atomic-invocation` level only by committing the +compare-and-swap atomically with the invocation's write set. + +A server MUST evaluate a `remove` or `remove-at` call in the following order and return the error +of the first step that fails. A call that fails removes nothing. + +1. The verb has been granted the `object` capability; else `forbidden`. +2. The verb is not a `function` (the "Verb invocation (the bare verb)" section of {{RESTACT}}); else `forbidden-side-effect`. +3. The name, and for `remove-at` the path, pass the checks `set` and `set-at` make, with the same + `forbidden` refusals: no name in the reserved `@` or `$` namespaces, so no verb removes `$policy` + or `$owner`; no path that is not client-addressable (the "Addressing" section of {{RESTACT}}); no member the server + reserves at that path, such as `value` and `version` on a secrets-mount path (informative example: the "The mediated secrets mount (OPTIONAL, feature `secrets-management`)" section of {{RESTACT-CONNECTORS}}); + and, for `remove-at`, no `shared`-scoped name. The credential's own bounds + ({{objects-relationship}}) are checked at this step too: they do not depend + on what is stored, so their refusal is the same whether or not an object exists (the "Refusing a caller who may not read" section of {{RESTACT}}). +4. For an `instance`-scoped or undeclared name (an undeclared name is `instance`-scoped, + {{data-properties}}), an object is stored at the target, as the + invocation sees it with its own buffered writes applied; else `not-found`. The target is the + bound object for `remove` and `path` for `remove-at`, even when the property is declared on + another object. A `remove` of a `shared`-scoped name skips this step, since the state of a + declaration is not an object and need not exist. +5. The caller has the authority a `set` of the same name needs: the object's `write` policy and the + property's write `acl` ({{data-properties}}), or, for a `shared`-scoped name, that `acl` alone, + as for `set`. A refused caller who may read the object gets `forbidden`, and one who may not + gets `not-found` ({{objects-non-reader}}). +6. A `final` property that is set gives `property-final`. +7. The removal is recorded with the invocation's writes (the "Consistency" section of {{RESTACT}}): a `remove` with the + bound object's buffered writes, and a `remove-at` at the call, as a `set-at` commits. Whether the + property is set is decided against the state the removal commits to. A property that is not set + there is left alone, and the call still succeeds. + +Authority is decided before `final` and before the property's presence, so a caller who lacks it +learns neither. The two functions are bound to the `object-remove` feature token +(the "The guest contract (WIT)" section of {{RESTACT}}). A server that advertises `object-data-access` but not `object-remove` MUST +refuse at upload a component that imports either function, with `403` (`disallowed-import`), as it +refuses any import it does not support. + +# Refusing a caller who may not read {#objects-non-reader} + +The non-reader rule (the "Refusing a caller who may not read" section of {{RESTACT}}) covers the +requests this document defines: the `object` capability's `set`, `set-at`, `set-at-if`, `set-subject`, `set-subject-at`, `remove` and +`remove-at` ({{object-data}}); a `PUT` with `null` members ({{data-properties}}); a refusal by a +declared member's `acl` ({{data-properties}}); and, under a coupled object-binding mode +({{object-binding}}), defining, replacing or removing a verb bound to the object, a coupled +`DELETE`'s authority over the verbs it would remove, and a coupled mode's authority over the +object's verbs. + +The rule governs only how a refusal is answered, so it does not refuse a `set-at-if` by a principal +who may write a property and may not read it. That call fails with `precondition-failed` without +comparing its `expected` ({{object-data}}), as an `If-Match` from such a caller fails without the +object's entity tag (the "Refusing a caller who may not read" section of {{RESTACT}}). + +For a path that holds no object, the answers to these requests are: + +* a `remove` or `remove-at` of an `instance`-scoped or undeclared property gets an + `invocation-error` with code `not-found`, since a removal never creates an object. A data-plane + `PUT` with `null` members is a write and gets the answer of the next item; +* a write that would create the object gets the answer of the creation rules + ({{object-policy-inheritance}}). Those rules refuse it as not-found where a governing anchor's + `write` policy refuses the caller and its `read` policy does too, as `forbidden` (`403`) where that + anchor's `read` policy admits the caller, and, on a server advertising `governed-creation`, with + that feature's `403` where no anchor reaches the path and the write does not carry a `$policy` of + its own. At the verb tier the same refusal is an `invocation-error` with code `not-found` or + `forbidden`; +* under `strict`, a verb definition or a write to a verb's `code` or `policy` property gets `409` + (`object-binding`). + +A request that would succeed at a free path, and that the non-reader rule therefore refuses as +not-found, includes a write the creation rules admit (no governing anchor reaches the path and +first-writer-owns applies, or an anchor's `write` policy admits the caller) and a deploy under +`auto-create`, which creates the object. The server MUST NOT define the verb. + +# Active Properties (Accessor Verbs) {#active-properties} + +Retrieving or mutating an object's representation MAY be mediated by code rather than served from +storage, using ordinary verbs under a naming convention. This feature is entirely OPTIONAL: a +server that does not implement it serves stored representations. + +The verb names `get`, `list`, `create`, `update`, `set`, and `delete` are RESERVED as +representation accessors. These are the standard data-method names that {{AIP136}} already forbids +as custom-method names, so they do not collide with application verbs. An accessor verb produces +(for reads) or accepts (for writes) the representation of the object or property it is bound to, +and MAY compose child accessors. For example, `GET /pet/dog:get` invokes the `get` accessor, which +MAY itself invoke `/pet/dog/tail:get`, `/pet/dog/legs:get`, and so on, assembling the result. This +is ordinary composition (the "Composition" section of {{RESTACT}}); the shared budget, cycle detection, depth and fan-out +bounds, and authority attenuation all apply unchanged. + +A `get` or `list` accessor is a function (no observable side effects), so it is safe and cacheable +per the "Verb invocation (the bare verb)" section of {{RESTACT}}; `set`, `update`, `create`, and `delete` accessors are side-effecting (actions). A +server MUST reject an accessor deployed with a kind inconsistent with this (a non-function `get`/`list` +or a non-action `create`/`update`/`set`/`delete`). When a server dispatches a bare-object data-method +request to an accessor, it maps the HTTP method to the accessor as follows, trying each candidate in +order and dispatching to the first one defined: + +| Method | Accessor (preference order) | +|--------|----------| +| `GET` | `get` (own representation), else `list` (collection enumeration) — both functions | +| `PUT` | `update` (full replace, action) | +| `PATCH` | `set` (partial/property write), else `update` — both actions | +| `POST` | `create` (action) | +| `DELETE` | `delete` (action) | + +A server that dispatches the `set` (`PATCH`) and `list` (`GET`-collection) accessors in addition to +`get`/`update`/`create`/`delete` advertises the `set-list-accessors` feature; the `get`→`list` and +`set`→`update` fall-throughs make the extension backward-compatible (an object defining only the latter +four behaves unchanged). The accessor's result and errors propagate to the outer response. A data method that a `set`, +`update`, `create` or `delete` accessor serves is an action, so a server MUST refuse it with `400` +(`invalid-input`) when it carries `If-Match` or `If-None-Match`, and the accessor does not run +(the "Consistency" section of {{RESTACT}}). A `get` or `list` accessor is a function, and a precondition on it is evaluated +against its output tag, as for any function (the "Verb invocation (the bare verb)" section of {{RESTACT}}). Because the dispatched verb is +invoked through the ordinary invocation path, its own `execute` policy governs the request — so an +accessor's policy is the object-level authorization for that operation, layered above the baseline +object policy (the "Representations" section of {{RESTACT}}) that applies when no accessor is defined. Accessor verbs resolve +up the inheritance chain (the "Verb Resolution and Inheritance" section of {{RESTACT}}), so a base type MAY define default accessors that a subtype +overrides and MAY invoke explicitly (a "super" call). A server MAY use a `readMask` (the "Collections: Listing, Pagination, Filtering, Field Masks" section of {{RESTACT}}) +to limit which child accessors a `get` composes. + +Whether a request to an object's data path (for example, `GET /pet/dog`) is served from storage or +dispatched to a defined accessor verb is a server-selected behavior: a server MAY dispatch by default, +MAY serve stored representations by default, or MAY make it configurable, and a server that dispatches +MUST advertise it in discovery (the "Discovery" section of {{RESTACT}}): the `bare-path-accessor-dispatch` feature, and +`true` as the `accessorDispatch` member of the discovery document's `service` object while +dispatch is enabled (a document without the member describes a server that does not dispatch). When dispatch is enabled but no accessor is defined for the request, the +server serves the stored representation unchanged. A bare-path request names no verb, so it is never +answered `verb-not-deployed`; an explicit accessor invocation such as `GET /pet/dog:get` is an +ordinary invocation. Whether an accessor wraps underlying storage or +computes a purely virtual representation is determined solely by the capabilities granted to the verb +(the "Capability Model" section of {{RESTACT}}); neither {{RESTACT}} nor this document defines a +separate mechanism for it. + +A server MAY mediate any of the data-plane methods on an object (the "Object data (the noun)" +section of {{RESTACT}}) through a defined accessor verb, in which case the accessor's `execute` +policy governs. + +A request that a server dispatches to an accessor verb passes its body to the verb as it arrived, +`null` members included; the rules for `null` members ({{data-properties}}) govern only the +server's own handling of `PUT`. + +# Declared Data Properties {#data-properties} + +This OPTIONAL feature (token `data-properties`) lets an object **declare** named data properties with +storage and access semantics, so that shared or sensitive state is defined deliberately rather than +emerging by accident. A server that does not implement it treats all object state as undeclared (see +below). A server that does SHOULD advertise `data-properties` in discovery, and MAY advertise each +object's declarations. + +A **declaration** has a `name` (a data-property name; user data MUST NOT use a `$`-prefixed name, +which is reserved for system fields, or an `@`-prefixed name, which is reserved for the server's +internal storage), an optional advisory `type`, an optional `default` value, and +the following modifiers: + +- **`scope`** — `instance` (default) or `shared`. An `instance` property's value is stored on the + concrete object the verb is invoked on, so sibling instances under one bound-verb definition (for + example `counters/{id}`) have independent values. A `shared` property's value is stored on the + object the property is **declared on** (the definition object — the resolution ancestor reached by + the inheritance walk, the "Verb Resolution and Inheritance" section of {{RESTACT}}), so every instance observes and updates one common value. A + global counter is a `shared` property; the absence of a declaration MUST NOT be treated as shared. + +- **`final`** — when true, the property is write-once: a write to a value that is already set, and a + removal of a value that is already set (by a `null` member of a `PUT` under `put-null-removes`, as + this section describes, or by `remove` or `remove-at`, {{object-data}}), MUST fail with + `property-final` (409) and MUST NOT mutate state. Removing a `final` property that is not set + changes nothing. The refusal does not depend on the value offered: a write of the value already + stored is refused like any other, so `property-final` tells a principal who may write the + property and may not read it that it is set, and nothing about its value. + +- **`inherit`** — when true (default false), value inheritance is enabled: reading a concrete object + that has no locally-stored value for the property returns the value stored on the **nearest + ancestor** object on the inheritance chain (the "Verb Resolution and Inheritance" section of {{RESTACT}}), and if no ancestor holds one, the + declared `default`. When false the property never inherits a value (an absent value reads as absent), + preserving plain stored-representation behavior. Inheritance and the declared `default` apply only to an object that + exists, that is, one holding stored data of its own: an object that does not exist yields neither, + whether it is read through the object data plane (`not-found`) or through a verb's object-data + capability (the value is absent), so a verb invoked on a path where no object exists reads no + inherited value. Within one invocation, the writes the invocation has made and not yet committed + count toward existence, so once a verb has written to the object it is bound to, its reads of + that object inherit. `inherit` applies only to `instance` scope — a + `shared` property already resolves to a single value — and a server SHOULD reject `inherit` on a + `shared` declaration. Inheritance MUST be applied identically whether the property is read through + the object data plane or through a verb's object-data capability (the "Capability Model" section of {{RESTACT}}), and is gated by + the property's read `acl` exactly as a local read is, so it never reveals more than a direct read. + For an inherited value that `acl` is evaluated against the ancestor that holds the value, not the + object being read: `owner` matches that ancestor's `$owner` and `prop:` reads that ancestor's + stored values (the "Authorization and Identity" section of {{RESTACT}}), so a value reaches a principal through a descendant only if the + principal could read it on the ancestor directly. + +- **`acl`** — an optional `{ read, write }` pair, each a list of authorization subjects (the "Authorization and Identity" section of {{RESTACT}}: + `public`, `owner`, `sub:`, `role:`, `group:`, `scope:`, `claim:`). A read or write is permitted only if the + caller (the runs-as-caller principal, the "Authorization and Identity" section of {{RESTACT}}) matches a listed subject; an omitted list defaults + to `read: [public]`, `write: [owner]`. The property ACL is evaluated **in addition to** the object's own policy + (`$policy`, the "Representations" section of {{RESTACT}}, or the policy it inherits from a governing anchor) and, for an + access made through a verb, the verb's own `execute` policy. It can only further restrict, never widen: + a read needs both the object's `read` and the property's `read`; a write needs both the object's + `write` and the property's `write` (a write that creates the object, or the first write to an + existing object with no recorded owner, passes the object-level gate exactly as it would for an + undeclared member); and a server MUST NOT let a property ACL admit a principal the object's policy + refuses. A `shared` property is state of its declaration, not of an object: its writes are gated by + its ACL and `final`; a read of it through an object path additionally needs that object's `read`. A denied read behaves as if the property is + absent; a denied write MUST fail with `forbidden` (403), or as for an absent object when the caller + may not read the object ({{objects-non-reader}}), and MUST NOT mutate state. This version + defines exactly the two property actions `read` and `write`; finer per-property actions (e.g. a + separate `manage`, or distinct code-vs-value actions) are a reserved increment, and a server MUST + reject an `acl` naming an unknown action with `400 invalid-input` rather than silently ignoring it. + +An **undeclared** property is equivalent to `{ scope: instance, final: false, acl: { read: +[public], write: [public] } }` — i.e. governed by the object's own policy alone, the pre-existing behavior — so adding +this feature is backward-compatible. A write refused under `final` or `acl` MUST abort the +invocation, discarding any other state changes it made (an `atomic-invocation` server, the "Consistency" section of {{RESTACT}}, +already guarantees this). Concurrent writers of a `shared` property MUST NOT lose updates; a server +MAY serialize them or use the optimistic-concurrency / transactional mechanisms of +the "Consistency" section of {{RESTACT}}. + +How declarations are submitted is server-defined: a server MAY derive them from the object's +schema, or accept them through a `props` verb property (the "Verb properties (the program itself)" +section of {{RESTACT}}). A server that exposes `props` serves and accepts it as a JSON object whose +`dataProperties` member is an array of declarations. A declaration is a JSON object with the +members `name`, `scope`, `final`, `type`, `default`, `inherit` and `acl` described above, of which +only `name` is required; `acl` holds `read` and `write`. A `PUT` of `props` replaces every +declaration of the verb, and a server MUST refuse with `400` (`invalid-input`), changing nothing, +a body with any other member at any of these levels, other than one that a feature the server +advertises defines. + +**Removing a property (OPTIONAL, feature `put-null-removes`).** On a server that advertises +`put-null-removes`, a `PUT` body member whose value is JSON `null` removes that property, the +meaning a JSON merge patch gives `null` {{RFC7396}}; every other member keeps its rule +(the "Representations" section of {{RESTACT}}). The property then reads as one that was never set: absent, or, for an +`inherit` property, the inherited value or the declared `default` ({{data-properties}}). A `null` +member is authorized exactly as a write of that member would be, by the object's `write` policy, +the member's `acl` and the credential's own bounds ({{objects-relationship}}), +and it gets any refusal such a write would get. A `null` for a `final` member that is set MUST be +refused with `409` (`property-final`). The server MUST decide that authority before it checks +`final` or a precondition (the "Consistency" section of {{RESTACT}}), and the "Refusing a caller who may not read" section of {{RESTACT}} applies unchanged. + +A `PUT` that mixes sets and removals is one write, under the rule of the "Object data (the noun)" +section of {{RESTACT}}. A `null` for a property that is not set changes nothing for that property, but the `PUT` around it is still a write: it needs write authority, as a `PUT` that +changes no value does, and once admitted it is handled as such a `PUT` is. A `PUT` whose members +are all `null`, sent to a path that holds no object, creates an empty object as `PUT {}` would, +under the same creation rules ({{object-policy-inheritance}}, {{object-binding}}) and with the same +answers to a caller who may not create it ({{objects-non-reader}}). A removal never deletes the object, even +when it removes the last data member: the object keeps its `$owner`, and only `DELETE` deletes it. +The rules for a `null` system field follow. A server that does not advertise `put-null-removes` +refuses every `null` member, as the "Native representation" section of {{RESTACT}} requires. + +**A `null` system field (feature `put-null-removes`).** On a server that advertises +`put-null-removes`, `"$policy": null` in a `PUT` removes the object's own policy, and the object +falls back to its governing anchor's policy ({{object-policy-inheritance}}) or to the +omitted-policy defaults of the "Native representation" section of {{RESTACT}}. Since that can widen access, the removal needs exactly the authority that writing `$policy` +needs there. Removing a governing anchor's own policy changes, in the same way, the effective policy +of every descendant that stores no policy of its own. A server MUST refuse the removal where it +requires an object to carry a policy of its own, since the removal would leave an object the server +would not let anyone create. On a server advertising `governed-creation`, that requirement covers a +path no governing anchor reaches, and the refusal there is that feature's `403`. (Informative: +{{RESTACT-CONNECTORS}} names two more such places.) + +The server decides these refusals after the authority decision, so a caller without that authority +gets only the authority answer ({{objects-non-reader}}), and it decides them on the path and on the policy +the write would leave, whatever is stored there. At a path that holds no object there is no policy +to remove: a `PUT` whose only member is `"$policy": null` is `PUT {}` and gets that request's answer +there, and a `null` `$policy` never counts as a creating write's own `$policy` +({{object-policy-inheritance}}). + +`put-null-removes` does not change the answer to `"$owner": null`: the "Ownership is fixed" section +of {{RESTACT}} refuses it with `400` (`invalid-input`) on every server, in place of the `403` it +gives other `$owner` members, since ownership is fixed and no request removes it. On a server that +advertises `put-null-removes`, a `null` for any other `$`-prefixed name MUST be refused with `400` +(`invalid-input`). + +A removal of a property, whether a `null` member of a data-plane `PUT` (the "Native representation" section of +{{RESTACT}}, at extension point E5) or a call +to the `object` capability's `remove` or `remove-at` ({{object-data}}), is a write. It joins the +write set exactly as a write of the same property would: a `remove` commits with the invocation's +other writes to its bound object, a `remove-at` commits at the call as a `set-at` does, and at +`atomic-invocation` both join the invocation's write set, which commits on return or is discarded +as a whole. Unlike the compare-and-swap, `remove` and `remove-at` are admitted at every level. The +invocation's own later reads see a removal and answer as for a property that was never set, and +of a `set` and a `remove` of the same property, the later call wins. Where a `set` and a later +`remove` of the same property are buffered in one write set at a path that holds no object, nothing +is written there for that property. Unless another buffered write leaves a property or a binary +value set at that path, the invocation's later calls see no object there, as if neither call had +been made, and its commit creates none. A removal is decided against +the state it commits to: a property that is not set there is left alone, a server that re-checks a +buffered write at commit re-checks a removal the same way, and an object deleted while the +invocation ran is not a refusal, since there is nothing left to remove. + +# Binary values (OPTIONAL, feature `binary-values`) {#binary-values} + +A server that advertises `binary-values` lets an object hold a **binary value**: bytes stored as a +client wrote them, with the media type they were written with, beside the object's properties +({{data-properties}}). + +A `PUT /v1/` whose body is not empty and whose `Content-Type` is a single media type other than +`application/json`, `text/json`, and a type with the structured syntax suffix `+json` {{RFC6839}} +writes the body as the object's binary value, with that media type. A body with one of those JSON +media types keeps the meaning that the "Object data (the noun)" section of {{RESTACT}} gives it. +That section also has a server refuse with `415` (`invalid-input`) a `PUT` whose body is not empty +and whose `Content-Type` is absent or is not exactly one media type, and has a server that does not +advertise `binary-values` refuse a body of any other media type the same way. A server MUST refuse +with `422` (`invalid-input`) a binary write whose `Content-Type` contains a control character. + +A binary write is authorized exactly as any other write of the object (the "Object data (the noun)" +section of {{RESTACT}}): by the object's `write` policy, and, for a caller who may not read an +existing object, with the answer an absent object would get. Property ACLs do not apply to it. It +replaces the object's binary value and leaves the object's properties as they are, and a `PUT` with +a JSON body leaves the binary value in place. Like any other `PUT`, a binary write counts as one +write for everything that observes writes, such as events and lifecycle hooks. A server MAY cap the +size of a +binary value, and MUST refuse a larger one with `413` (`object-too-large`). + +A `GET` of an object that holds a binary value returns that value: the stored bytes unchanged, with +the stored media type as the `Content-Type` and a strong entity tag that changes whenever the bytes +change; a matching `If-None-Match` returns `304`. The object's properties are not part of that +response, and a verb reads them through the `object` capability ({{object-data}}). Such a response +is content a client supplied, so a server MUST send it with the headers, and the handling of +script-capable media types, that the "Security Considerations" section of {{RESTACT}} requires for a +verb's output. A server MUST NOT answer `404` for an object whose stored binary value the server +fails to read: a +store failure is `503` (`unavailable`), and a stored value whose bytes are missing or no longer match +what was written is a server error (`500`). + +# Security Considerations {#objects-security} + +* **Listing by prefix.** A listing narrowed by a client-chosen prefix ({{object-listing}}) still + reads, and then drops, each object in range that the caller cannot read, so its response time + grows with the number of such objects. Were any string accepted as a prefix, a caller could extend + it one character at a time toward whichever request ran slow and recover the names of paths it + cannot read. Requiring the prefix to end in `/` limits each probe to one whole guessed path + segment; timing still reveals whether unreadable objects sit below a guessed name, and roughly how + many. A server exposing the listing to untrusted callers SHOULD require authentication and SHOULD + rate-limit it. +* **Declaration is not a grant.** A data-property declaration can only narrow access to the objects + its route reaches. Were a property ACL able to admit a principal the object's policy refuses, any + principal able to declare a property on a verb whose route reaches another principal's object could + open it. Declarations can still narrow, hide (a read ACL), make a member write-once (`final`), or + supply values (`inherit`, `default`) across every object their route reaches, so who may declare is + itself an authority: under a coupled object-binding mode ({{object-binding}}) only the owner of the + route's deepest concrete ancestor may. +* **Existence of unreadable objects.** The limits in the "Security Considerations" section of + {{RESTACT}} apply here. A caller who may not read an object gets the answer an absent object would + get from the listing ({{object-listing}}) and from a refused coupled-mode verb definition + ({{objects-non-reader}}). A request that succeeds at a free path includes a write the creation + rules admit ({{object-policy-inheritance}}) and a deploy under `auto-create` ({{object-binding}}). + Under a coupled object-binding mode the discovery document lists the definition path of each verb + the caller may see, so an object with such a verb bound to it is known to that caller to exist. +* **Binding under authentication.** Under `implicit`, a principal can bind a verb on an ancestor + of another principal's objects and act on requests to them. The coupled object-binding modes tie + each binding to ownership of the bound object, and the ancestor-creation rule keeps a principal + from creating an ancestor above objects it does not own ({{object-binding}}). +* **Size of an object a writer may not read.** A server's per-object size cap is checked against + the object as the write would leave it, with the stored members and the new value. A principal who may + write an object but may not read it, such as a drop box with `write` open to the public and `read` + kept to the owner, can therefore vary the size of what it writes until the answer turns from + success to `object-too-large`, and so learn roughly how much is stored. The rule of the "Refusing + a caller who may not read" section of {{RESTACT}} governs refusals for want of authority. This + writer has the authority, and `object-too-large` is decided after it, so the rule does not apply. + The cap is not relaxed for it, since checking only the new value would let the + stored object grow past the cap. A deployment where that size is sensitive keeps such objects + apart from the ones untrusted principals write, for example one object per writer. + +The security considerations of {{RESTACT}} apply. + +# IANA Considerations {#objects-iana} + +This document requests the following registrations in registries that {{RESTACT}} creates. It +creates no registry. + +* In the "REST:ACT Feature Tokens" registry: the tokens in the table of {{objects-relationship}}. +* In the "REST:ACT Error Codes" registry: the codes in the table below. +* In the "REST:ACT Verb Property Names" registry: `props` ({{data-properties}}), and `history` and + `rollback` ({{verb-history}}). +* In the "REST:ACT Capability Interfaces" registry: `rest-act:plugin/object` ({{object-data}}). + +The error codes this document defines, with the HTTP status of each, are: + +| `restact_code` | Status | Meaning | +|---|---|---| +| `object-binding` | 409 | a coupled object-binding mode ({{object-binding}}) refused the deploy/bind: the object is absent, the caller may not read it, or the verb's path begins with a wildcard ({{objects-non-reader}}) | +| `invalid-filter` | 400 | a malformed collection/listing `filter` ({{object-listing}}) | +| `ancestor-claim` | 409 | the object was not created because objects stored below its path might be owned by another principal ({{object-binding}}) | +| `property-final` | 409 | write to a write-once (`final`) data property, or removal of one that is set | diff --git a/src/lib/specmd.ts b/src/lib/specmd.ts index de17383..da5a75f 100644 --- a/src/lib/specmd.ts +++ b/src/lib/specmd.ts @@ -49,6 +49,22 @@ export const DRAFT_FILE = 'draft-byrd-restact-protocol-00.md'; export const PV_FILE = 'draft-byrd-restact-presentation-00.md'; export const DRAFT_PATH = '/spec/draft/'; export const PV_PATH = '/spec/presentation-verbs/'; + +/** The extension drafts and the page each one renders at. Each is a file in the specification repository. */ +export const EXTENSION_DRAFTS = [ + { slug: 'objects', file: 'draft-byrd-restact-objects-00.md', label: 'Objects draft' }, + { slug: 'events', file: 'draft-byrd-restact-events-00.md', label: 'Events draft' }, + { slug: 'delegation', file: 'draft-byrd-restact-delegation-00.md', label: 'Delegation draft' }, + { slug: 'connectors', file: 'draft-byrd-restact-connectors-00.md', label: 'Connectors draft' }, + { slug: 'mcp', file: 'draft-byrd-restact-mcp-00.md', label: 'MCP facet draft' }, + { slug: 'http-verbs', file: 'draft-byrd-restact-http-verbs-00.md', label: 'HTTP verbs draft' }, +].map((d) => ({ ...d, path: `/spec/${d.slug}/` })); +/** A draft file in the specification repository to its on-site page. */ +const DRAFT_PAGES = new Map([ + [DRAFT_FILE, DRAFT_PATH], + [PV_FILE, PV_PATH], + ...EXTENSION_DRAFTS.map((d) => [d.file, d.path] as [string, string]), +]); export const REGISTRIES_PATH = '/spec/registries/'; export const SPECS_REPO = 'https://github.com/stackumi/restact'; @@ -88,6 +104,10 @@ const RFC_TITLES: Record = { RFC2119: 'Key words for use in RFCs to Indicate Requirement Levels', RFC3986: 'Uniform Resource Identifier (URI): Generic Syntax', RFC5234: 'Augmented BNF for Syntax Specifications: ABNF', + RFC6234: 'US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)', + RFC6266: 'Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)', + RFC8187: 'Indicating Character Encoding and Language for HTTP Header Field Parameters', + RFC9421: 'HTTP Message Signatures', RFC6749: 'The OAuth 2.0 Authorization Framework', RFC6750: 'The OAuth 2.0 Authorization Framework: Bearer Token Usage', RFC7232: 'Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests', @@ -184,10 +204,19 @@ function parseFront(text: string): FrontMatter { // Link policy // -------------------------------------------------------------------------------------------- +/** A link to a draft file in the specification repository on GitHub, as its on-site page and fragment, or null. */ +export function draftPageFor(url: string): string | null { + const m = url.match(new RegExp(`^${SPECS_REPO.replace(/[.]/g, '\\.')}/blob/main/(draft-byrd-restact-[a-z-]+-00\\.md)(#.*)?$`)); + const page = m && DRAFT_PAGES.get(m[1]); + return page ? page + (m[2] ?? '') : null; +} + /** Rewrites a link found in a vendored file. Returns null to drop the link and keep its text. */ export function rewriteHref(href: string, opts: { file?: string; idPrefix?: string } = {}): string | null { if (href.startsWith('#')) return opts.idPrefix ? `#${opts.idPrefix}${href.slice(1)}` : href; if (/^https?:/.test(href)) { + const onSite = draftPageFor(href); + if (onSite) return onSite; // The reference host's decision records and spec directory are not public pages yet. if (/^https:\/\/github\.com\/stackumi\/restactd\/(?:blob|tree)\/main\/spec(?:\/|$)/.test(href)) return null; return href; @@ -203,8 +232,9 @@ export function rewriteHref(href: string, opts: { file?: string; idPrefix?: stri } if (abs) { const fragPart = frag ? `#${frag}` : ''; - if (abs === DRAFT_FILE) return DRAFT_PATH + fragPart; - if (abs === PV_FILE || abs === 'presentation-verbs.md') return PV_PATH + fragPart; + const page = DRAFT_PAGES.get(abs); + if (page) return page + fragPart; + if (abs === 'presentation-verbs.md') return PV_PATH + fragPart; if (abs === 'registries/README.md') return `${REGISTRIES_PATH}#registries`; const reg = abs.match(/^registries\/(.+)\.md$/); if (reg && REGISTRY_FILES.some((r) => r.slug === reg[1])) return `${REGISTRIES_PATH}#${reg[1]}${frag ? `-${frag}` : ''}`; @@ -220,6 +250,7 @@ export function rewriteHref(href: string, opts: { file?: string; idPrefix?: stri const DOC_LABELS: Record = { [DRAFT_FILE]: 'draft', [PV_FILE]: 'presentation draft', + ...Object.fromEntries(EXTENSION_DRAFTS.map((d) => [d.file, d.label.toLowerCase()])), 'presentation-verbs.md': 'Presentation verbs', 'registries/README.md': 'Registries', 'registries/feature-tokens.md': 'Feature Tokens', @@ -384,7 +415,7 @@ function engine(opts: EngineOpts) { const sec = opts.sections?.get(key); if (sec) return `${sec.label}`; const ref = opts.refs?.find((r) => r.key === key); - if (ref) return `[${esc(key)}]`; + if (ref) return `[${esc(key)}]`; if (/^RFC\d+$/.test(key)) return `[${key}]`; throw new Error(`specmd: unresolved reference {{${key}}} in ${opts.file}`); }, @@ -553,7 +584,7 @@ export function renderDraft(file: string = DRAFT_FILE): DraftDoc { .sort((a, b) => a.key.localeCompare(b.key, 'en', { numeric: true })) .map( (x) => - `
[${esc(x.key)}]
${esc(x.title)}${/^RFC\d+$/.test(x.key) ? `, RFC ${x.key.slice(3)}` : ''}. ${esc(x.target.replace(/^https?:\/\//, ''))}
`, + `
[${esc(x.key)}]
${esc(x.title)}${/^RFC\d+$/.test(x.key) ? `, RFC ${x.key.slice(3)}` : ''}. ${esc(draftPageFor(x.target) ? x.target.replace(/^.*\/(draft-[^/#]+?)\.md.*$/, '$1') : x.target.replace(/^https?:\/\//, ''))}
`, ) .join(''); const refsHtml = diff --git a/src/pages/llms.txt.ts b/src/pages/llms.txt.ts index 293070d..8537c1b 100644 --- a/src/pages/llms.txt.ts +++ b/src/pages/llms.txt.ts @@ -20,6 +20,12 @@ A verb is a WebAssembly component. It runs with the caller's permissions, can us - [The draft](${u('/spec/draft/')}): the normative text, "${DRAFT.title}" - [The draft's Markdown source](${raw}): the same text, as written - [Specification overview](${u('/spec/')}): the draft section by section, feature tokens, the guest contract, and tests +- [Objects and data](${u('/spec/objects/')}): the extension draft for object listing and queries, property access, policy inheritance, accessor verbs and deployment history +- [Events](${u('/spec/events/')}): the extension draft for lifecycle hooks, subscriptions, schedules and delivery over Server-Sent Events +- [Identity and delegation](${u('/spec/delegation/')}): the extension draft for ownership reassignment, path-scoped sub-tokens and grants +- [Connectors](${u('/spec/connectors/')}): the extension draft for the secrets mount, mediated outbound calls, model completion and webhook delivery +- [Model Context Protocol facet](${u('/spec/mcp/')}): the extension draft for the four MCP tools +- [HTTP verbs](${u('/spec/http-verbs/')}): the extension draft for request headers, response status and headers, and webhook signature verification - [Presentation verbs and their media type](${u('/spec/presentation-verbs/')}): application/vnd.restact.ui+json, the extension draft, normative - [Registries](${u('/spec/registries/')}): the registries the draft requests diff --git a/src/pages/sitemap.xml.ts b/src/pages/sitemap.xml.ts index fceb653..a1d26ff 100644 --- a/src/pages/sitemap.xml.ts +++ b/src/pages/sitemap.xml.ts @@ -1,7 +1,8 @@ import type { APIRoute } from 'astro'; +import { EXTENSION_DRAFTS } from '../lib/specmd'; // Every page of the site, absolute on `site` (restact.org). The list comes from the page files, so -// a new page joins it with no edit here; the 404 page and endpoints like this one are left out. +// a new page joins it with no edit here (the extension drafts come from their dynamic route's list); the 404 page and endpoints like this one are left out. // No : search engines ignore one that is not exact, and the pages carry no edit date. const files = Object.keys(import.meta.glob('./**/*.{astro,md,mdx}')); @@ -10,6 +11,7 @@ export const GET: APIRoute = ({ site }) => { .map((f) => f.replace(/^\.\//, '').replace(/\.(astro|mdx?)$/, '')) .filter((p) => p !== '404' && !p.split('/').some((s) => s.startsWith('_') || s.startsWith('['))) .map((p) => (p === 'index' ? '/' : `/${p.replace(/\/?index$/, '')}/`)) + .concat(EXTENSION_DRAFTS.map((d) => d.path)) .sort(); const urls = paths.map((p) => ` ${new URL(p, site).href}`).join('\n'); return new Response( diff --git a/src/pages/spec/[slug].astro b/src/pages/spec/[slug].astro new file mode 100644 index 0000000..2745461 --- /dev/null +++ b/src/pages/spec/[slug].astro @@ -0,0 +1,28 @@ +--- +import Docs from '../../layouts/Docs.astro'; +import SpecBody from '../../components/SpecBody.astro'; +import { renderDraft, EXTENSION_DRAFTS, SPECS_REPO } from '../../lib/specmd'; + +export function getStaticPaths() { + return EXTENSION_DRAFTS.map((d) => ({ params: { slug: d.slug }, props: { file: d.file } })); +} + +const { file } = Astro.props; +const doc = renderDraft(file); +const f = doc.front; +const sourceUrl = `${SPECS_REPO}/blob/main/${file}`; +--- + + + + + diff --git a/src/pages/spec/index.astro b/src/pages/spec/index.astro index 7bf75f9..e6e9bb3 100644 --- a/src/pages/spec/index.astro +++ b/src/pages/spec/index.astro @@ -74,6 +74,42 @@ const wit = witSummary(); const documents = [ { name: 'The Internet-Draft', href: DRAFT_PATH, status: 'Normative', covers: 'The protocol: grammar, methods, capabilities, limits, discovery' }, + { + name: 'Objects and data', + href: '/spec/objects/', + status: 'Normative, extension draft', + covers: 'Listing and querying objects, property storage and access, inherited policy, accessor verbs, deployment history, JSON:API', + }, + { + name: 'Events', + href: '/spec/events/', + status: 'Normative, extension draft', + covers: 'Lifecycle hooks, topic subscriptions, schedules, publishing events, delivery over Server-Sent Events', + }, + { + name: 'Identity and delegation', + href: '/spec/delegation/', + status: 'Normative, extension draft', + covers: 'Ownership reassignment, path-scoped read-only sub-tokens, grants under which one principal acts for another', + }, + { + name: 'Connectors', + href: '/spec/connectors/', + status: 'Normative, extension draft', + covers: 'Secrets mount, mediated outbound calls, model completion, signed webhook delivery', + }, + { + name: 'Model Context Protocol facet', + href: '/spec/mcp/', + status: 'Normative, extension draft', + covers: 'Four MCP tools for invoking verbs and listing and reading objects', + }, + { + name: 'HTTP verbs', + href: '/spec/http-verbs/', + status: 'Normative, extension draft', + covers: 'A verb reads declared request headers and sets its response status and headers; webhook signature verification before the verb runs', + }, { name: 'Presentation verbs', href: '/spec/presentation-verbs/', diff --git a/src/site.config.ts b/src/site.config.ts index 158f271..8593c2b 100644 --- a/src/site.config.ts +++ b/src/site.config.ts @@ -126,6 +126,12 @@ export const DOCS_NAV: NavGroup[] = [ items: [ { label: 'Specification', href: '/spec/' }, { label: 'The Internet-Draft', href: '/spec/draft/' }, + { label: 'Objects and data', href: '/spec/objects/' }, + { label: 'Events', href: '/spec/events/' }, + { label: 'Identity and delegation', href: '/spec/delegation/' }, + { label: 'Connectors', href: '/spec/connectors/' }, + { label: 'MCP facet', href: '/spec/mcp/' }, + { label: 'HTTP verbs', href: '/spec/http-verbs/' }, { label: 'Presentation verbs, normative', href: '/spec/presentation-verbs/' }, { label: 'Registries', href: '/spec/registries/' }, ],