Skip to content

AGENTS.md

Latest commit

 

History

History
78 lines (65 loc) · 3.51 KB

AGENTS.md

File metadata and controls

78 lines (65 loc) · 3.51 KB

Ghost Key Development Guide

Overview

Ghost Keys provide anonymous, verifiable identities backed by Freenet donations. This crate implements the cryptographic primitives shared across the website, CLI, and API.

Core Flow

  1. User donates via Stripe and generates an Ed25519 key pair locally.
  2. Public key is blinded (RSA blind signatures, RFC 9474) before being sent to the server.
  3. Server signs the blinded key with its notary RSA key and returns the signature.
  4. Browser unblinds the signature and combines it with metadata to form the Ghost Key certificate.
  5. Trust chain: Freenet master key → notary certificate → Ghost Key certificate.

Terminology — "notary", "delegate", and "vault"

The PKI intermediate (this crate's NotaryCertificateV1) was historically called "delegate certificate". It was renamed to "notary" in 0.2.0 (issue #24) because it collided with Freenet's own Delegate (sandboxed WASM agent) concept.

Three distinct concepts, do not confuse them:

  • notary certificate — the PKI intermediate, defined here. The key that witnesses a donation and signs an attestation.
  • Freenet Delegate — the generic Freenet platform primitive: a sandboxed WASM agent running inside a Freenet node.
  • Ghostkey Vault — the specific freenet/ghostkeys delegate that stores user ghost keys and handles identity operations. "Vault" is its product name (see ghostkeys/ui/), which is what humans should reach for when talking about where users store their keys. Issue #24 called it a "wallet delegate", but the actual product name is vault — use that.

Deprecated delegate_* type aliases and the delegate_certificate module path are preserved through the 0.2 release line and slated for removal in a future release.

Key Modules

  • armorable.rs: Base64 serialization trait for cryptographic objects.
  • notary_certificate.rs: Notary key management and verification (was delegate_certificate.rs).
  • delegate_certificate.rs: Deprecated stub re-exporting the renamed types.
  • ghost_key_certificate.rs: Certificate creation and validation logic.
  • util.rs: Blind signature helpers and cryptographic utilities.
  • errors.rs: Error types used across the library.

Building & Testing

cd rust/gklib
cargo build
cargo test

Workspace commands:

cargo make build-wasm-dev       # Build browser WASM module (uses this crate)
cargo make build-wasm-release
cargo make integration-test
./test_cli_commands.sh          # CLI integration tests exercising certificates

Browser Integration

  • rust/gkwasm/ exposes Ghost Key functionality to the browser (wasm-bindgen).
  • WebAssembly output is copied to hugo-site/static/wasm/.
  • hugo-site/content/ghostkey/create/index.html demonstrates the end-to-end flow.

Security Notes

  • Blind signatures ensure server never sees the real public key.
  • Certificates verify back to the master key (FREENET_MASTER_VERIFYING_KEY_BASE64).
  • Keep an eye on revocation, delegation chains, and threshold signatures when extending.

Useful CLI Commands

ghostkey generate-master-key
ghostkey generate-notary --master-signing-key master.pem --info "test"
ghostkey generate-ghost-key --notary-dir path/to/notaries --output-dir path/to/ghost
ghostkey verify-ghost-key --ghost-certificate ghost.pem
ghostkey sign-message --ghost-certificate ghost.pem --ghost-signing-key key.pem --message "test"

The old generate-delegate / verify-delegate / --delegate-dir / --delegate-certificate spellings are still accepted as deprecated aliases.