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

Quickstart

Both tools are on npm — nothing to clone. Run these commands outside a source checkout (inside this repository, npm resolves the local workspace package):

# 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/.)

Running from source

Node.js 20 or newer is required. From the repository root:

npm install
npm run build

# Create and save an identity with the locally built CLI
npm run keygen

# Start the editor in development mode
npm run dev

The editor prints its local URL (normally http://localhost:5173). The CLI can be invoked as node packages/cli/dist/altweb.mjs <command>. Do not use npx altweb inside the checkout: npm may select the local workspace package, whose executable does not exist until it has been built.

The documentation site is intentionally a separate npm project rather than a workspace. To run it locally:

npm install --prefix site
npm run dev --prefix site

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.

Copyright © 2026 Daniel C. ȘOIMU. Bundled third-party components keep their own (permissive) licenses — see NOTICE.