Capability URLs

Capability mode is zetl’s answer to: “I want to share my wiki with a dozen friends, read-only, without running a server, but I don’t want the whole internet reading it.” The output is a plain static site — hostable on any CDN, any S3 bucket, any sftp’d directory — where access is gated by a secret in the URL fragment. No accounts, no server-side auth, nothing to rotate but the URLs themselves.

If you want multi-user editing, you want Running a Team Server. Capability mode is for publishing.

The idea in one paragraph

Each page is encrypted at build time with a cohort-specific key. Invite URLs look like https://wiki.example.com/welcome.html#k=<base64-secret>. The #fragment — by design of the HTTP spec — is never sent to the server. The reader’s browser, executing a small JavaScript shim, pulls the key out of the fragment, decrypts the page locally, and verifies a vault-level Ed25519 signature so nobody can serve them a forged page. Revocation is per-cohort: you rotate the cohort’s salt and re-deploy, old URLs stop decrypting.

Formal spec: see docs/capability-mode.md in the zetl repo.

Setting up a capability site

1. Generate the keys

zetl cap genkey

This prints two secrets to stdout, exactly once:

ZETL_CAP_SECRET — the 48-byte content-encryption secret.
ZETL_CAP_SIGNING_KEY — the Ed25519 vault-signing private key.

Capture them somewhere safe (a secret store, a password manager, a sealed envelope). You’ll need ZETL_CAP_SECRET on every build and ZETL_CAP_SIGNING_KEY whenever you rotate the signing key.

2. Issue an invite

zetl cap invite alice \
  --cohort eng \
  --site-url https://wiki.example.com

--cohort groups grants that share a content key. Rotate a cohort without touching the others. --site-url is the canonical hostname the invite URL points at (also settable via ZETL_CAP_SITE_URL).

The command prints an invite URL like:

https://wiki.example.com/welcome.html#k=TzN1ej...

Send it by whatever channel works — Signal, in-person, a QR code. The part after # is the secret; if you leak the URL, you leak read access.

Narrow an invite to a subset of pages with --pages, and set a TTL with --expires:

zetl cap invite bob \
  --cohort ops \
  --expires 7d \
  --pages 'projects/*' \
  --site-url https://wiki.example.com

3. List, revoke, rotate

# See who you've invited
zetl cap list
zetl cap list --cohort eng

# Revoke a specific grant by id (see list output)
zetl cap revoke <grant-id>

# Rotate a cohort's content-key salt — URLs stay the same by design,
# but old readers need re-issued keys (see SPEC-034 REQ-3402).
zetl cap rotate --cohort eng

After revoke or rotate, rebuild and redeploy. The old ciphertext is still out there on anyone’s browser cache, but new ciphertext won’t decrypt under an old key, and a well-configured CDN will have dropped the stale response by the time a reader returns.

Two-operator handoff: `zetl cap pair`

For higher-stakes vaults, you don’t want the inviter to see the reader’s private key even briefly. zetl cap pair runs a SPAKE2 pubkey handoff authenticated by a short spoken phrase:

Grantor (you) runs zetl cap pair --grantor. It generates a fresh 4-word BIP39 phrase, prints it, and starts a SPAKE2 session. You read the phrase aloud to the other operator.
Grantee (the other operator) runs zetl cap pair --grantee --peer <handshake> --phrase "<4 words>" --pubkey <their-pubkey>. They send their outbound handshake and HMAC tag back to you.
You paste those into the blocked grantor session. On a matching phrase, SPAKE2 derives the same shared key on both sides and the HMAC verifies; the authenticated pubkey is now yours to use with zetl cap invite --recipient.

If the phrase differs — because someone in the middle tried to substitute one — the HMAC fails and nothing goes through. This is the “high-value vault” workflow; for friends-and-family scale, the default delegated URL mode is fine.

Split-key mode for high-value vaults

A capability URL is bearer-auth: anyone with the URL reads. For truly sensitive cohorts, --split-key divides the private key between the URL fragment and a second factor — either a spoken phrase the reader types in, or a QR code from a separate device — so neither alone unlocks the vault:

zetl cap invite carol \
  --cohort board \
  --split-key \
  --site-url https://wiki.example.com

Split-key mode must be enabled in the vault config first ([access.split_key] enabled = true). Without that, --split-key is rejected. The second factor is a build-time configuration; default is spoken-phrase (the reader types it in), and qr is a planned alternative.

Other useful subcommands

Command	What it does
`zetl cap finalise <grant>`	Mark a grant as operator-confirmed after first use, so the capability binds to a known device (TOFU).
`zetl cap check`	Stale-grant and public-safety audit. Catches capabilities drifting past their useful life.
`zetl cap sweep`	Bulk-revoke past-expiry grants.
`zetl cap audit-diff`	Scan a vault diff for malicious-content patterns (e.g. a hostile theme attempting exfiltration).
`zetl cap rotate-signing-key`	Rotate the vault signing key. Rebuild required — every page is re-signed.
`zetl cap emergency-shutdown`	Print the operator checklist for pulling a capability site offline in a hurry. Doesn’t modify files.

When to use capability URLs vs a collab server

Capability URLs: publishing read-only to a known group. No server to run. No accounts to manage. Hostable anywhere static. Revocation is per-cohort, not per-user-finely — if you need to yank one reader mid-cohort, that’s a rotate.
Collab server: two or more people actively editing. Real-time merge. Per-user commits. Needs a box to run zetl serve --collab on.

For the full operator spec — threat model, deploy recipes for Nginx/CloudFront, rotation ordering, CSP headers — see docs/capability-mode.md in the zetl repo.

Backlinks

Linked Pages

Web Server

zetl serve starts a local web server that renders your vault as a browsable site. You get rendered Markdown, working wikilinks, a live backlink panel, a persistent graph mini-map, and an in-browser editor. It’s the fastest way to actually read — and edit — a vault of more than a handful of notes.

Why run a server

A static export (Static Site Export) shows your vault as it was when you last built it. A terminal viewer (Terminal Viewer) shows one note at a time. zetl serve is what you want between those: a live view of the vault right now, with:

Rendered pages — Markdown, wikilinks, embeds, and code blocks, rendered through Minijinja templates with YAML frontmatter in scope.
Backlinks panel — every page that points here, updated on every save.
Transclusion panel — forward-link excerpts as cards in the right rail, connected to anchors in the main text by SVG bridges (the same Xanadu idea as the terminal viewer).
Live search — full-text search across the vault from a modal.
CodeMirror editor — click Edit, change the note, hit Save. The index rebuilds on save; no reload dance. A delete button is a click away.
Persistent graph mini-map — a Sigma.js WebGL graph of your vault, docked bottom-right, that survives page navigation (no flash, no re-layout).
History strip — when zetl was built with --features history, every page shows when it last changed and links to its timeline. See Page History.

Running it

zetl serve                            # http://localhost:3000
zetl -d ~/notes serve
zetl serve --port 8080
zetl serve --theme paper

Open http://localhost:3000/ to land on the vault index. Wikilinks in rendered pages are clickable. Ctrl-P (or whatever the active theme binds) opens the search modal.

Flags that matter

Flag	Default	Purpose
`-p, --port <PORT>`	`3000`	TCP port.
`--theme <THEME>`	`default`	Theme from `.zetl/themes/<name>/`. See Customising the Look.
`--public <DIR>`	—	Files in this directory override generated pages (good for `robots.txt`, custom error pages).
`--collab`	off	Switches to multi-user mode with passkeys and CRDT sync. See Running a Team Server.
`--safe-mode`	off	Skip every hook except ones declared in the theme.
`--at <TIME-EXPR>`	—	Serve a past snapshot. See Time Travel.
`--exclude <PATTERN>`	—	Gitignore-syntax exclusion, repeatable.

Single-user vs collab

Out of the box, zetl serve is single-user and trusts whoever reaches the port. There’s no login, no accounts; editing works immediately. This is the right mode when the server is on your laptop or behind a VPN.

With --collab, zetl turns into a multi-user server: WebAuthn passkey login, real-time CRDT editing over WebSockets, access control, invitations. That whole stack — bootstrapping an owner, inviting collaborators, deterministic server keys — lives in Running a Team Server.

Access Control

zetl’s access model has two layers. The built-in layer — three roles plus glob-based page scoping — covers the 90% case: readers, editors, admins, optionally confined to a folder. The optional layer — SPL-based deontic rules — lets you express richer policies (“editor everywhere except billing/**”, “read access only between 9:00 and 17:00”) using the same reasoning engine that powers What is defeasible reasoning.

The three roles

Role	View	Edit	Invite	Admin UI
`reader`	yes	no	no	no
`editor`	yes	yes	no	no
`admin`	yes	yes	yes	yes

A user’s role is set on the invitation that brought them in (see Invitations) and can be changed later from /_admin/users. There’s no implicit hierarchy beyond this table — an editor isn’t a superset of admin, they’re just different.

Page scoping with globs

When you issue an invitation you can restrict which pages the recipient reaches at all:

zetl invite --as Alice --role editor --pages "research/**"

The scope is a glob against vault-relative paths. projects/* matches direct children of projects/. projects/** matches everything recursively. You can pass only one --pages at invite time; for more intricate patterns, use deontic rules below.

Pages outside the scope are invisible — not just uneditable. An out-of-scope page won’t appear in search, won’t show up in the graph, and returns 404 if requested by URL. This is a deliberate minimum-surface choice: users don’t learn about documents they can’t touch.

Deontic rules with SPL

Requires --features reason at install time. See Installation.

Invitations

New collaborators join a vault via a single-use, signed invitation token. You generate one with zetl invite (or the web UI), send the resulting link by whatever out-of-band channel you prefer, and the recipient uses it exactly once to register a passkey and pick a display name.

Generating an invite from the CLI

The minimal form takes your own username (the inviter) and the role the invitee will have:

zetl invite --as Alice --role editor

This creates the token and copies the full invitation URL to the clipboard. Paste it into Signal, email, a sticky note — whatever gets it to the recipient without a third party logging it along the way.

Three roles are available:

Role	What they can do
`reader`	View pages; no editing, no invitations.
`editor`	View and edit pages; cannot invite new users or change access.
`admin`	Full control, including issuing invitations and managing passkeys.

Scoping an invite to specific pages

By default an invite gives the recipient access to the whole vault at their role. For a contractor who should only touch one project, or a reviewer who only needs to see a single folder, use --pages with a glob:

# A reader who only sees pages under projects/website/
zetl invite --as Alice --role reader --pages "projects/website/*"

# An editor scoped to a specific topic
zetl invite --as Alice --role editor --pages "research/biology/**"

Globs match on the vault-relative path. projects/* matches direct children; projects/** matches everything underneath, recursively. For more expressive rules — “editor on everything except billing/**”, or “editor only between 9–5” — see SPL-based deontic rules in Access Control.

Custom expiry

Static Site Export

zetl build turns your vault into a folder of plain HTML, CSS, and JavaScript. No runtime, no database, no server process — every page is a file you can upload to any static host. The output looks the same as Web Server minus the editor.

Why build a static site

A static site is the right deliverable when:

You want to publish research notes, a personal wiki, or project docs to the public internet.
You want a vault readable from any browser with zero operational overhead.
You want something to hand to collaborators, reviewers, or your future self that doesn’t depend on the zetl binary being installed.
You want archival: HTML works the same way in 2040 as it does in 2026.

Because nothing on the published site writes back, the edit button is absent and the save/delete endpoints aren’t emitted. Everything else — wikilinks, backlinks, transclusion panels with SVG bridges, the graph widget, full-text search, per-page history (if built with --features history) — lands in the output as static HTML and JSON.

Running it

zetl build                             # writes ./dist/
zetl -d ~/notes build
zetl build --out-dir site              # custom output directory
zetl build --theme paper               # pick a theme
zetl build --site-url https://vault.example    # absolute URLs for social cards

Preview the result locally with any static file server:

python3 -m http.server -d dist 8080

Then open http://localhost:8080/.

Output structure

Running a Team Server

zetl’s --collab flag turns zetl serve into a multi-user editing server: passkey login, real-time CRDT co-editing, per-user git commits, and scoped invitations. Everything is in-tree — there’s no feature flag to enable at install time. If you can run zetl serve, you can run a team server.

The shape of a collab vault

A collab vault is a normal Markdown vault plus a .zetl/collab/ directory:

.zetl/collab/server.key — the server’s Ed25519 signing key (for session cookies and invitations).
.zetl/collab/users.db — SQLite store for passkeys, sessions, and invitation nonces.
.zetl/collab/wal/ — write-ahead log for the CRDT engine. Survives crashes.

These files are created on first run. You never edit them by hand.

First run: bootstrap the owner

The very first time you start a collab server, you need to bootstrap an owner account. --init-owner creates one, prints a 12-word recovery phrase, and exits into the normal serve loop:

zetl -d ~/notes serve --collab --init-owner --owner-name Alice

The terminal will print something like:

Owner created: Alice
Recovery phrase (write this down — you will not see it again):

  palm  tornado  ladder  oyster  casual  umbrella
  desert  finger  enlist  brave  coconut  strong

Server listening on http://localhost:3000

Save that phrase. It’s your only way back into the account if you lose your passkey, and zetl will not show it to you a second time. Paper, password manager, encrypted notes file — pick one and commit.