ALTWEB — signed context capsules

Signed context capsules for AI agents — Markdown compiled into self-contained, verifiable, optionally encrypted artifacts + an MCP loader that refuses unsigned or untrusted context. Verify before you inject.

AI agents run on plain-text context: instructions, personas, skills, memory files. None of it has provenance — anything that can write those files can poison them. ALTWEB gives context a chain of custody, and makes the loader refuse anything that lacks one:

Capsule — markdown compiled into a single .altweb.html file (or URL): content compressed (deflate), optionally encrypted (AES-256-GCM), optionally signed (ECDSA P-256). Self-contained — opens in any browser, verifies offline, needs no server: you hand someone a file, not a database.
Verified context loading — the altweb-context MCP server loads a capsule into your agent only when the signature is valid and the signer's public key is in your trust file. Unsigned, tampered, or untrusted capsules are refused at load time, with an explicit reason. Refusal is the default: an empty trust file rejects everything, signed or not.

you write MD ──► altweb compile --sign ──► capsule (.altweb.html / URL)
                                              │
agent asks for context ──► altweb-context ──► verify signature + trust
                                              │
                              trusted ──► markdown injected
                          everything else ──► REFUSED (reason)

Packages

Package	What it is
`altweb`	CLI: `altweb compile / decode / verify / keygen` (`packages/cli`)
`altweb-context`	MCP server: `load_capsule`, `verify_capsule`, `list_trusted_keys` (`packages/mcp`)
`@altweb/core`	Headless engine: content model, codec, crypto, markdown, sanitize (bundled into both; npm release planned)
`@altweb/editor`	Notion-style editor (built on Novel) with one-click capsule export
`site/`	Documentation site (Astro + Starlight)

Quickstart

Both tools are on npm — nothing to clone:

# create your signing identity (deterministic from a passphrase; only the
# public key + fingerprint are stored, in ~/.altweb/identity.json)
npx altweb keygen --save

# write, compile, sign
echo "# My agent's operating notes" > notes.md
npx altweb compile notes.md -o notes.altweb.html --sign

# verify anywhere, offline
npx altweb verify notes.altweb.html

Wire the loader into an MCP client (Claude Code example):

claude mcp add altweb-context -- npx -y altweb-context

(From source: npm install && npm run build, then use the bundles under packages/*/dist/.)

Trust a signer by adding its full public key to ~/.altweb/trusted-keys.json (the UNTRUSTED_KEY refusal message hands you the ready-made entry; the short fingerprint is a human label, not the trust anchor):

{ "keys": [ { "name": "Me", "publicKey": "<base64url SPKI>", "fingerprint": "ab:12:..." } ] }

What a signature proves — and what it does not

A valid signature proves who authored the capsule and that the bytes are intact. It does not make the content safe or true. The trust file is your policy; keep it short.

Pick a long passphrase. Identities derive deterministically from your passphrase via Argon2id with a fixed protocol salt (that is what makes them portable with nothing stored). Memory-hardness makes mass dictionary attacks economically hostile, but the passphrase's entropy is still the identity's foundation. Use a 16+ character diceware-style phrase; the tooling enforces a minimum strength.

Security

Content is sanitized with DOMPurify on decode; artifacts carry a CSP; the codec validates structure with zod. See site/ docs → Security model for the full write-up, including the encrypted-capsule caveat (the signature covers the decrypted payload, so verification completes after decryption).

Roadmap

Near-term, in rough order:

@altweb/core on npm — the engine as an installable library, for programmatic use (the CLI and loader already ship it bundled).
Hardware-backed identity (FIDO2 / passkeys) — an optional identity type alongside the passphrase one: the private key lives in a security key or secure enclave, never extractable, signing requires physical presence. The passphrase identity stays the default — "a passphrase is a keypair" — hardware keys add something you have for those who want it.

Credits

Built on excellent open source: Novel (Apache-2.0) and Tiptap (MIT) for the editor; DOMPurify, marked, pako, zod, @noble/curves in the engine. See NOTICE.

License

ALTWEB is dual-licensed:

Open source: AGPL-3.0-or-later. Free to use, study, modify, and share — with one core obligation: if you modify ALTWEB and distribute it or run it as a network service (e.g. hosting altweb-context for others), you must release your modified source under the AGPL.
Commercial: by agreement. To use ALTWEB in a closed-source product, or as a hosted service without publishing your changes, you need a separate commercial license. See COMMERCIAL.md.

ALTWEB Context Loader