Skip to main content

Trusted documents (allowlist)

Trusted documents allow only pre-registered operations to execute, reducing attack surface and enabling predictable performance.

Practices implemented​

Implementer guidance​

Client implementer​

  • Detect trusted-document requirements from endpoint service capabilities.
  • Extract operation documents at build time, hash, and publish to a registry.
  • At runtime, send the operation ID (hash) instead of the full document text.
  • Keep hash algorithm and canonicalization aligned with server expectations.

Server implementer​

  • Store and version trusted operations received during publish.
  • Ensure documents stored in the registry are trusted.
  • Resolve incoming operation IDs to canonical documents.
  • Reject requests without an ID.
  • Reject requests with an unknown operation ID.
  • Optionally cache parse and validation results keyed by operation ID.

Tooling implementer​

  • Provide CI checks that all shipped operations are published.
  • Fail builds when operation IDs are missing or mismatched.
  • Support rollback/revocation workflows for operations.
  • Track which versions of which applications use which operation IDs. This can aid with schema evolution decisions.

See also​

Cautions​

  • Enforce strict canonicalization to avoid hash drift.
  • Plan operational procedures for publish failures and rollback.
  • Third-party APIs do not trust their incoming documents and typically cannot require users to pre-register documents.

Problems addressed​