Documentation · Releases · Caduceus

Caduceus — hub-side codex integration

v.Chronos.Caduceus.0 — legacy v.H.1.19 (Caduceus.1 ships as commits; live VERSION_LABEL bumps on the next forest mint)

One encrypted hub-side codex, sealed under the master key, Prime Codex Seed + CodexPrime atomically derived, signing pipeline wired to the @stoachain package ecosystem, /hub/codex admin surface for bootstrap + backup + delete.

Caduceus.1 ships the hub-side codex by consuming the published @stoachain/* package ecosystem (kadena-stoic-legacy + stoa-core + ouronet-core all at 4.3.0, ouronet-codex at ^0.2.0 — the version that introduces the structural Prime Codex Seed + CodexPrime invariants) instead of re-implementing the codex from scratch. A new server-side codex vault (lib/codex-vault.ts) enforces the prime invariants in its CRUD: the first kadena seed added is auto-flagged isPrime, a Standard Ouronet Account is atomically derived from the same mnemonic via createOuronetAccount(registry, { mode: 'seedWords' }) and flagged as CodexPrime with parentSeedId linkage to the prime seed, and both prime entities are unremovable as individual rows — the only path to remove them is the whole-codex delete. A new server-side signer (lib/codex-signer.ts) wraps @stoachain/stoa-core/signing's CodexSigningStrategy with a lazy-loaded singleton, reading the in-memory codex via dynamic imports (the worker runs CJS via tsx and the @stoachain packages are ESM-only, so all runtime imports are dynamic). A new /hub/codex admin page renders either a three-choice bootstrap landing (Generate fresh / Restore from seed words / Import from JSON) when no codex exists yet, or a populated-codex view with the codex info card, the Kadena seeds list, the Ouro accounts list (both read-only; rotations + multi-seed land in follow-ups), a backup download button (V1.2 JSON byte-compatible with the OuronetUI export format), and a danger-zone delete-codex modal with a type-DELETE typing gate + fresh-confirm password gate. The mnemonic display, for fresh-generated codexes, uses a single-checkbox + type-CONFIRM gate (per the operator's pre-confirmed UX) and the 24 words are shown exactly once. The earlier Caduceus.0 attempt was ripped (~70 files including 16 API routes, 10 hub pages, the lib/codex/ directory, lib/stoa-bootstrap.ts, 2 cronoton handlers, 3 docs pages, and 22 test files) and replaced wholesale.

Why “Caduceus”

The Caduceus is the staff of Hermes — two serpents intertwined around a herald's rod, the symbol of negotiated transit between domains. Hermes carries it as the messenger between the divine and mortal worlds, the conductor of souls, the authorised passenger between two realms — never the resident of either, always the legitimised crossing.

For this release, “Caduceus” names the codename of the capability that lets the AncientHoldings hub act as a sovereign agent across the StoaChain boundary. The hub holds its own codex of seeds and derived keys; signs Pact transactions with those keys; and submits them to the chain. The hub becomes the herald that carries signed transactions between two worlds — the off-chain hub control plane and the on-chain Pact execution layer — rather than a passive infrastructure surface.

What changed for the operator

Caduceus.1 is the actual ship; Caduceus.0 was the codename mint that preceded an implementation which never reached parity. The earlier work was ripped out wholesale (see the “1-e” wave in the changelog) and replaced with the package-consumption approach below.

  • New admin page at /hub/codex. Ancient- admin only. Shows the bootstrap wizard when no codex exists, or the populated view when one does.
  • Three bootstrap choices.“Generate fresh codex” mints a 24-word BIP-39 mnemonic, displays it once behind a write-this-down checkbox + type-CONFIRM gate, derives the Prime Codex Seed + CodexPrime atomically, and seals them. “Restore from seed words” takes an operator-pasted mnemonic and runs the same atomic kickstart. “Import from JSON backup” lands in a follow-up.
  • Read-only entity display.Seeds + ouro accounts render with their public metadata; the Prime Codex Seed + CodexPrime carry gold “Prime” badges signalling they are structurally unremovable.
  • V1.2 backup download. Produces an AncientCodex_*.json file byte-compatible with the OuronetUI export format. The codex password (managed by the hub) is required to decrypt individual entries; keep the file with any master-key recovery notes.
  • Whole-codex delete. The only path to remove the prime entities. Two-layer gate: type the literal word DELETE in the typing gate, then re-enter your admin password. After delete, the bootstrap wizard reappears.
  • Server-side signing. The hub can now build and sign Stoa Pact transactions against any codex-held key — used today by admin REST routes, used in a follow-up by cronoton handlers when the operator picks the first scheduled transaction.

Architecture (hub-asset model)

The codex is treated like the SSH keys the hub already holds for the servers it controls — just another encrypted-at-rest asset under the SECRETS_MASTER_KEY umbrella. There are two encryption layers:

  • Outer. The codex blob + the codex password are both sealed under SECRETS_MASTER_KEY in secrets_vault via the existing seal/unseal. Rotating the master key re-seals two rows; no inner-entry re-encryption needed.
  • Inner. Individual seed mnemonics + ouro account secrets are smartEncrypt'd inside the codex blob under a separate 32-byte random codex password (generated lazily at first kickstart, sealed under the master key as a second vault row).

This is the fundamental architectural divergence from the OuronetUI codex (which is browser-local, user-typed password, browser-side signing). The hub model is: server-stored, master-key-sealed, auto-unlocked at boot, signed by server-side code. The ancient admin never types a separate codex password.

What's deferred to follow-ups

  • Cronoton handler wiring. The cronoton scheduling scaffolding (tables + 30s worker tick) is preserved, but the actual cronoton-fire handler is unregistered until the operator picks the first real scheduled transaction. When that lands, the handler is re-added in lib/handlers/registry.ts wired to lib/codex-signer.ts::signAndSubmit().
  • Rotation modals. rotate-guard / rotate-payment-key / rotate-sovereign. They depend on chain-side guard fetching + gas station capability orchestration.
  • Import from V1.2 JSON.Cross-machine codex recovery path. The bootstrap wizard's third card shows the placeholder.
  • Add-seed / add-ouro-account flows. Multi-seed codex management. The inaugural ship starts with one Prime Codex Seed + one CodexPrime.
  • Pure keypairs + address book CRUD. Land alongside rotation work.

Operator notes

  • Package surface. @stoachain/kadena-stoic-legacy@4.3.0 + @stoachain/stoa-core@4.3.0 + @stoachain/ouronet-core@4.3.0 + @stoachain/ouronet-codex@^0.2.0. The ^0.2.0 pin is mandatory (v0.1.0 lacks the Prime Codex Seed protection).
  • ESM/CJS constraint. The Caduceus.0 hotfix (no static @stoachain/* imports in worker boot path) is preserved + generalised across lib/codex-vault.ts and lib/codex-signer.ts.
  • Audit trail. Uses the existing codex.create / codex.restore_seedwords / codex.export / codex.remove_seed actions; mnemonic plaintext NEVER appears in audit detail JSON.
  • Live version stamp. lib/version.ts's forest-derived VERSION_LABEL continues to read Caduceus.0 until the operator runs the placement-skill mint ceremony for Caduceus.1; the commit-message coordinate (v.Chronos.Caduceus.1-{a,b1,b2,c,d,e,f}) is authoritative for the work shipped.