@attestto/vcp

Embed-first content envelope CLI. Sign, verify, and inspect VCP metadata blocks inside PDF, JPEG, or as a .vcp.json sidecar for anything else.

Working Draft v0.1. Envelope spec: spec.attestto.com/vcp. Apache-2.0.

What it does

vcp sign embeds a signed metadata block inside a host file. The block carries:

• Issuer DID (currently did:key and did:pki)
• Optional subject DID
• Content-type
• SHA-256 hash of the host file with the vcp block excluded (hash_scope: host-file-minus-vcp-block)
• Timestamp
• Optional profile identifier (e.g. spec.attestto.com/vcp/profiles/id-evidence/v1)
• Optional IEAL claim (see spec.attestto.com/ieal)
• Ed25519 signature over the canonical (JCS RFC 8785) metadata

Legacy readers ignore the block. vcp-aware tools verify it. No encryption in v0.1 — see the roadmap.

Install

pnpm add -g @attestto/vcp
# or
npx @attestto/vcp help

Quickstart

# 1. Generate a fresh ed25519 keypair and get a did:key
vcp keygen --out-priv ./issuer.priv --out-pub ./issuer.pub
# → did: did:key:z6Mk...

# 2. Sign a file (auto-selects carrier by extension)
vcp sign ./contract.pdf \
  --issuer did:key:z6Mk... \
  --key ./issuer.priv

# 3. Verify
vcp verify ./contract.pdf
# → OK ./contract.pdf

# 4. Inspect without re-verifying
vcp inspect ./contract.pdf

Carriers (v0.1)

Host format	Where the block lives	Notes
PDF	%%vcp:begin / %%vcp:end block appended after %%EOF	Non-PAdES, backward-compatible. Full PAdES integration deferred to a follow-on ticket.
JPEG	APP1 XMP segment with xmlns:vcp namespace	Base64url of the canonical envelope inside a vcp:envelope element.
Any other	Sidecar file <host>.vcp.json	hash_scope: host-file-unmodified; host file is never touched.

Carrier is auto-selected by file extension. Force the sidecar with --sidecar.

DID methods (v0.1)

• did:key — universal quickstart. Public key resolves from the DID; no external lookup needed.
• did:pki — accepted as an opaque issuer identifier at sign time. On verify, the public key must currently be supplied via --public-key <hex|base64url> because the @attestto/did-pki resolver is not yet published. Full resolution against national CA hierarchies (starting with Costa Rica Firma Digital) is v0.2.

Envelope shape

{
  "metadata": {
    "spec": "https://spec.attestto.com/vcp/",
    "spec_version": "0.1",
    "issuer": "did:key:z6Mk...",
    "subject": "did:key:z6Mk...",
    "content_type": "application/pdf",
    "content_hash": "2b8c9ecbeda66f...",
    "hash_scope": "host-file-minus-vcp-block",
    "timestamp": "2026-07-01T13:40:22.482Z",
    "profile": "https://spec.attestto.com/vcp/profiles/id-evidence/v1",
    "ieal": { "capture": "C1", "algorithm": "A2", "storage": "S2", "composite": "L3" }
  },
  "signature": {
    "alg": "EdDSA",
    "value": "pEgWY3OA..."
  }
}

The signature.value is the raw Ed25519 signature over the canonical (JCS) JSON of metadata. To verify, canonicalize metadata, resolve the issuer DID to an Ed25519 public key, and run ed25519.verify.

Roadmap

Version	Adds	Ticket
v0.1 (this)	Embed-first sign+verify for PDF, JPEG, sidecar. did:key + did:pki (opaque).	shipping
v0.2	MP3 (ID3v2.4 PRIV frame) + MP4 (ISOBMFF uuid box) support	ATT-773
v0.2	Full PAdES integration for PDF (proper /Sig dictionary + /ByteRange)	tbd
v0.2	@attestto/did-pki resolver against Firma Digital CA hierarchy	tbd
v0.2	Standalone .vcp envelope with encryption (X25519 + XChaCha20-Poly1305)	tbd
v0.3	Inheritance / Shamir threshold recovery block	tbd
v2.0	Post-quantum hybrid signature suite (ML-DSA + Ed25519)	tbd

Testing

pnpm test
# ✔ 8 tests, 0 failures

Contributing

VCP is an open specification. Feedback via issues, PRs, or open@attestto.com. Specification editor: spec.attestto.com/vcp (to be published as v0.1 lands).

License

Apache-2.0. Copyright 2026 Attestto Identity Standards Group.