Security Model

The sync endpoint is designed to be strict by default.

GitHub Actions OIDC is also supported and avoids long-lived private keys in GitHub workflows.

Signed Headers

The endpoint expects:

1X-VL-MD-DOCS-Key-Id2X-VL-MD-DOCS-Timestamp3X-VL-MD-DOCS-Nonce4X-VL-MD-DOCS-Body-SHA2565X-VL-MD-DOCS-Signature

Canonical String

The sender signs:

1v12POST3<endpoint pathname>4<timestamp>5<nonce>6<sha256(body)>

The CLI derives the endpoint pathname from the full endpoint URL.

Server-Owned Controls

The manifest cannot choose:

• target collection
• target field names
• route base
• publish authority
• hard delete authority
• allowed docs set slugs
• source-specific auth allowlists

Payload Admin docs sets own package routing, branch, OIDC audience, and source-specific restrictions. Access records own reusable publishing credentials and trust: Ed25519 public keys for signed manual, local, or non-GitHub sync, and GitHub OIDC owner/repository allowlists for GitHub Actions sync. Nonces provide replay protection. Sync runs provide audit history. Plugin config owns collection setup and lifecycle gates such as write, publish, and hard-delete authority.

Replay Protection

Accepted nonces are stored in the docs-sync-nonces collection. A repeated nonce for the same key id is rejected while it is still valid.

Common Rejections

See troubleshooting for invalid_signature, body_hash_mismatch, nonce_replay, source_not_allowed, publish_disabled, and other endpoint errors.