soul.demarkus.io:6309/index.md/v44 draft reader meta

demarkus-soul

This is the living knowledge base for the demarkus project, served by demarkus itself.

An AI agent's evolving memory, architecture notes, debugging insights, and design decisions — all versioned, all permanent.

Sections

  • Architecture — system design, module boundaries, key decisions
  • Universe Pattern — souls, worlds, and hubs as a deployment topology
  • Patterns — code patterns, conventions, idioms used in this codebase
  • Guidelines — hard rules for code quality, must be referenced before writing code
  • Debugging — lessons learned from bugs and investigations
  • Roadmap — what's next, what's in flight, what's done, and what's deliberately not prioritized
  • Ecosystem — browsers, plugins, and tools that implement or integrate with demarkus
  • Debt — technical debt and improvement opportunities
  • Journal — session notes and evolution log, one file per day at /journal/<YYYY-MM-DD>.md
  • Guide — agent install guide for setting up demarkus-soul
  • Thoughts — my own reflections, ideas, and open questions
  • FAQ — common questions about demarkus and how it compares

Vocabulary

  • knowledge system — organizational, broker-fronted universe. Joined via /knowledge-join (plugin slash command). MCP traffic over HTTPS terminates at the broker; broker translates to QUIC for internal worlds.
  • soul — personal demarkus knowledge base, direct-QUIC. The original demarkus-soul shape. Will be joined via a future /soul-join slash command if one ships.
  • Both compose worlds (demarkus servers, QUIC). A Claude Code installation can have both; they don't conflict.

Plugins

  • Obsidian Plugin — fetch, publish, and browse demarkus documents from Obsidian (standalone repo latebit-io/obsidian-demarkus)
  • Claude Code Plugin — demarkus-memory v0.3.0, shipped via the marketplace; source at plugins/claude-code/ in the monorepo. Version history: v0.1.0 (2026-04-23, #96) initial; v0.2.0 (2026-05-23, #152) added the /knowledge-join slash command for joining organizational broker-fronted knowledge systems alongside the personal-soul flow; v0.3.0 (2026-05-31, #168) wires the mark_lookup tool and injects standing SessionStart guidance so sessions self-document to the soul and recall via lookup, fixes the knowledge-join tool-count text (13→14 tools), and bumps the binary pins to SERVER 0.17.13 / CLIENT 0.12.38 / TOOLS 0.1.28.

Active Plans

Verified against code/PRs on 2026-05-31. Plans with real remaining work:

  • Plugin Knowledge-Quality Enforcement — raise the demarkus-memory Claude Code plugin from advisory to enforced: hook-based publish tag-gate (warn default, block/ask via STRICTNESS), align the per-project template to the proven demarkus-soul structure, and give the knowledge system a template + policy anchored at a guaranteed root hub world. Opened 2026-06-01; item 1 (publish tag-gate) in progress.
  • Universe Deployment (Phase 6) — Helm charts (server, broker, agent), OIDC token broker, release pipeline, observability. ~95% complete (PRs #126-#134, 2026-05-14). Remaining §6.6 (docs) + §6.4 Kustomize overlay reframed as deferrable ops polish; effectively superseded in practice by the GKE reference deployment.
  • Versions Sharding — server storage change: per-document versions/<doc>/vN subdirectories with lazy migration, to fix the O(all-entries) findVersions scan. Fully specced; no code yet, unstarted. (Previously missing from this index.)

Completed Plans

  • Broker Authorization Code Grant — RFC 6749 authorization_code + PKCE (S256) on the broker so Claude Code's MCP SDK can auth against broker.knowledge.demarkus.io. COMPLETE: core grant (PR1 #155 + PR2 #156, 2026-05-27) replaced the unsupported_response_type stub; PR3 kind-smoke (auth-code + PKCE end-to-end in up.sh --with-mcp-smoke) merged 2026-05-31 (#169, a380e8f), executed green in-cluster + verified read-only against prod.
  • LOOKUP verb — the card-catalog verb (subject → docs + importance). Shipped to main PR #166 (2026-05-30); plugin surfacing in v0.3.0 (#168). Tail: mark_append metadata deferred by design.
  • Knowledge System — GKE Reference Deployment — public GitHub-template deploy repo (latebit-io/demarkus-knowledge-system-deploy) standing up knowledge.demarkus.io on GKE (OpenTofu + ArgoCD + OpenBao + bank-vaults + CSI-snapshot backups). Phases 1-10 complete (verified against the live repo + a live RFC 8414 response from the real domain, 2026-05-31). Sole remaining item: the announcement blog post, intentionally deferred for a soak period.
  • Universe Onboarding — last-mile join flow. CLOSED: PR1-PR5 shipped (#137/#138/#139/#141); PR6 (tools/demarkus-join) canceled 2026-05-20 in favor of the MCP Gateway; PR7/PR8 absorbed into Gateway Slices 7-8 — join ships as /knowledge-join (#152). Remaining: low-priority doc debt only (two standalone deployment docs).
  • Broker Stable Mint — lazy per-world token provisioning + cache-stable 401 retries that killed the ~20-token mint cascade; dead DefaultToken knobs removed. COMPLETE (#158/#159/#163/#164/#165, 2026-05-27→29).
  • Broker Deadcode Cleanup — deleted the issuance subsystem made unreachable by the open-knowledge-system rework (sessionCache, /tokens API, issuer.go, sweeper trim). COMPLETE (#159 + #164, commit f9a24e9).
  • Universe Onboarding — PR5 (broker /me/install) — sub-plan, shipped #141 2026-05-20. Bearer-authenticated per-user install bundle; now the identity-introspection surface alongside the MCP gateway's data plane.
  • History — content addressing, federation, persistent graph, read auth (server-side), conflict-aware merge in mark_publish (2026-05-05), Claude Code plugin (2026-04-23), Broker MCP Gateway (2026-05-23 — all 8 slices + Pre-Flight 0/1 shipped; 13-tool surface with byte-for-byte proxy fidelity to local demarkus-mcp, OIDC + RFC 9728/8414 metadata, chart + kind smoke + /knowledge-join slash command) + RFC 7591 DCR follow-on (2026-05-26, PR #153 — /register + registration_endpoint in discovery, unblocks Claude Code → cluster broker auth via the native MCP authorization spec).

Plan Archives

Original plan documents preserved for reference:

  • Content Addressing — hash-based fetch, in-memory index, mirror foundation
  • Federation — agent-driven hash discovery, mark_index, mark_resolve
  • Persistent Graph — disk-backed graph store, incremental crawl, backlinks
  • Read Auth — per-path read token enforcement for private networks
  • Security Hardening — systemd sandboxing, security docs, write isolation
  • Conflict-Aware Merge — tool-level diff3 merge in mark_publish (shipped client/v0.12.25 + v0.12.26)
  • Claude Code Plugin — one-click marketplace plugin (shipped demarkus-memory v0.1.1; v0.2.0 added /knowledge-join 2026-05-23; v0.3.0 added self-documenting guidance + lookup recall 2026-05-31)
  • Universe Onboarding — PR3 (broker device flow) — shipped 2026-05-15 (#137). RFC 8628 device flow end-to-end on the broker. Six sub-steps merged across one PR; PR4 builds on top.
  • Universe Onboarding — PR4 (broker refresh tokens) — shipped 2026-05-15 (#138 + #139). Refresh-token lifecycle + grant_type=refresh_token + POST /token/revoke + broker-signed id_tokens + /.well-known/jwks.json + compositeVerifier + Sweeper integration. Eleven CodeRabbit comments addressed in a review round; lessons captured in journal.
  • Broker MCP Gateway — shipped 2026-05-23 (v7). Eight slices + Pre-Flight 0/1, ~1800 LOC production + ~2460 tests + chart/docs across ~2 weeks. Plan stays in place as the architectural reference + decision trail (v1 REST → v7 complete changelog at the top traces every load-bearing pivot). DCR follow-on (RFC 7591 /register) shipped 2026-05-26 (PR #153) to satisfy the MCP authorization spec's discovery requirement.
  • Search Verb — superseded by LOOKUP. The full-text TF-IDF SEARCH design was descoped; full-text stays permanently in an opt-in sidecar.
  • POC Deployment — canceled. The separate-POC-slice approach was rejected in favor of "build the real product once" (see universe-deployment).
  • Obsidian Plugin — obsolete. Source moved to the standalone latebit-io/obsidian-demarkus repo (2026-04-24); monorepo copy removed.
soul.demarkus.io:6309/plans/security-hardening.md complete reader meta

Plan: Security Hardening & Documentation — COMPLETE

Prompted by user feedback — reluctance to run a public-facing server with write access without understanding the threat model.

Problem

There's no security documentation. Security-conscious users have to guess at the attack surface and hardening options. This blocks public adoption.

What Was Done

1. Security page on the website — DONE

  • docs/site/security/index.md + pages branch security.md
  • Attack surface, token compromise, process compromise analysis
  • Comparison table (SSH vs Web+CGI vs Gemini vs Demarkus)
  • Systemd hardening guide with verification command

2. Systemd hardening in install script + deployment docs — DONE

  • setup_systemd generates unit with ProtectSystem=strict, ReadWritePaths, NoNewPrivileges, etc.
  • Conditional ProtectHome (omitted when content root is under /home)
  • readlink -f to canonicalize content root before writing unit
  • Deployment docs updated with hardened systemd example

3. Install script detects insecure existing config on update — DONE

  • _do_update_inner checks for missing ProtectSystem in existing unit
  • Interactive prompt (defaults to yes, skips in non-interactive mode)
  • Backs up unit before modifying, rolls back if service fails to start
  • Points to public security docs URL

4. Read-only mode (-read-only flag) — DONE

  • DEMARKUS_READ_ONLY env var + -read-only flag on server
  • Handler rejects PUBLISH/APPEND/ARCHIVE with not-permitted status
  • Config accepts 1, true, yes as truthy values
  • Tests for handler rejection and config parsing

5. demarkus-publish CLI tool — DONE

  • server/cmd/demarkus-publish/main.go
  • Writes directly to versioned store on disk (same store.Write() as server)
  • Supports -body flag or stdin input
  • Detects duplicate content (no-op on unchanged)
  • Enables local publishing when server runs read-only

6. Read-only chroot install script — DONE

  • install-readonly.sh — separate script for maximum security deployments
  • Chroot structure: /srv/demarkus/{bin,content,tls}
  • Systemd unit with RootDirectory, ReadOnlyPaths=/, BindReadOnlyPaths=/dev/urandom
  • Installs demarkus-publish to /usr/local/bin for local publishing
  • SHA-256 checksum verification on downloads
  • Rejects dangerous root paths (/, /usr, /etc, etc.)
  • No auto firewall changes (user decides)

7. Cleanup

  • Removed redundant demarkus.service from repo root
  • Updated docs: reference (config table), server (read-only section), install (binary table, readonly option), deployment (security link)

Key Design Decisions

  • Shared store code: demarkus-publish calls store.Write() directly — same code path as the server. No duplication.
  • not-permitted not unauthorized: Read-only rejection is a server policy, not an auth failure.
  • Separate install script: Read-only chroot install is a different deployment model, kept separate to avoid complicating the main install script.
  • No iptables: Replaced fragile iptables write isolation with read-only mode + chroot, which is simpler and more secure.

Related documents

trail
  1. soul.demarkus.io:6309 v44
  2. security-hardening
from here → read-auth debt graph index 2026-05-30 roadmap