morphit/docs/adr/0047-tor-onion-and-hardening-by-default.md

# ADR-0047 — Tor onion service and host hardening on by default

**Status:** Accepted (implemented), 2026-06-28
**Supersedes:** none
**Superseded by:** none

## Context

Privacy is Morphit's first stated priority, and "as much security by default"
is the operator-facing corollary. Both were *supported* but *opt-in*:

- **Tor** was a first-class endpoint, but reaching it required the operator to
  generate a hidden-service key (`scripts/generate-onion.sh` / `mkp224o`) and
  paste the resulting `.onion` into `MORPHIT_INSTANCE_TOR_ADDRESS`. Most
  operators never did, so most instances shipped with no onion at all — the
  worst outcome for a privacy-first project.
- **Host hardening** shipped as a complete, idempotent Ansible role
  (`ops/ansible/roles/hardening`, OPERATIONS §37 + §34) plus a `morphit-ops
  harden` checklist generator, but running it was a deliberate operator choice.
  A first-time operator following the happy path could expose an un-hardened
  internet-facing box.

The friction was the problem, not the capability. The fix is to flip both
defaults to on while keeping every escape hatch intact.

## Decision

### 1. Every instance generates and serves a Tor `.onion` by default

- The setup wizard (`morphit-ops init`) **generates a v3 onion in the
  background** while the operator answers the other prompts — instant, no wait,
  no vanity grinding. Generation uses Node's built-in `crypto` only (new
  `apps/ops-cli/src/init/torOnion.ts`, zero new dependencies) and follows
  rend-spec-v3 §6 exactly: `address = base32(pubkey ‖ SHA3-256(".onion
  checksum" ‖ pubkey ‖ 0x03)[:2] ‖ 0x03) + ".onion"`; the 96-byte
  `hs_ed25519_secret_key` is the `== ed25519v1-secret: type0 ==` header plus
  `clamp(SHA-512(seed))`. The implementation is cross-checked against PyNaCl
  (libsodium), Python's stdlib base32, a from-spec checksum, and a fixed-seed
  vector.
- The wizard **never asks** about Tor and **never overwrites** an operator-set
  address: if `MORPHIT_INSTANCE_TOR_ADDRESS` already exists in the environment
  or an existing config, that value is kept.
- The hidden-service key files are written to `tor-hidden-service/`
  (`hs_ed25519_secret_key` mode 0600, dir 0700) **only on the success path**,
  so an aborted wizard leaves no orphan keys.
- The shipped **`tor` Ansible role** (`ops/ansible/roles/tor`, `enable_tor`
  default-on in `group_vars/all.yml`) installs Tor and points its
  `HiddenServiceDir` at the wizard's keys (`morphit_tor_key_src`), so the
  daemon serves the *same* address the site advertises.
- Reachability lights up automatically: the address flows from the env var →
  indexer config → `/v1/instance` `alt_networks.tor` → the web instance store →
  the footer Tor pill and the `Onion-Location` response header (so Tor Browser
  offers the onion with no user action).

### 2. Host hardening is applied by default, and the wizard hand-holds it

- The Ansible `hardening` role already imports **all 16 sub-features
  unconditionally** (SSH, unattended-upgrades, sysctl, mounts, auditd,
  AppArmor, AIDE, secrets-perms, outbound, alerting, rkhunter, GRUB, password
  policy, UFW, fail2ban) and runs with no `when:` gate — so the automated path
  was already maximal. No change was needed there.
- The wizard's hardening step now **walks the operator through the major
  pillars** (SSH lockdown, firewall + fail2ban, automatic updates, kernel
  hardening, intrusion detection) as a short run of yes-default confirmations,
  and records them so the generated `morphit-hardening-checklist.md` reflects
  what the operator confirmed.

## Why generate the onion locally instead of letting Tor do it

Tor can generate its own hidden-service key on first start, but then the
address is **not known at config-write time**. Generating it locally in the
wizard means the address can be written into the config, surfaced in the footer
pill + `Onion-Location`, and printed for the operator in the *same* setup run —
none of which is possible if the address only appears after the Tor daemon
boots later. Local generation is also instant and dependency-free at setup
time (Tor need not even be installed yet).

## Security notes

- The HS **secret key** is treated like any other secret: written 0600 on
  success only, and **structurally excluded from the save-as-you-go progress
  file** (`WizardProgress = Partial<Omit<WizardAnswers, … | 'torOnion'>>` plus a
  defense-in-depth `delete safe.torOnion` in `saveProgress`). Only the public
  `.onion` address is ever remembered (in `altNetworks.tor`).
- The wizard choices in pillar (2) **never weaken the automated path** — the
  Ansible playbook applies every hardening sub-feature regardless; a declined
  pillar only annotates the by-hand checklist ("strongly reconsider").

## Consequences

- Every fresh instance is Tor-reachable by default — a direct privacy win, and
  the onion pill/`Onion-Location` now appear for the common case rather than the
  rare configured one.
- Operators get a hardened host on the default path, with informed-consent
  framing rather than silent application.
- Setup produces one extra artifact (`tor-hidden-service/`); operators serving
  the onion must point the `tor` role's `morphit_tor_key_src` at it.
- A **vanity** `.onion` remains a deliberate manual step (generate on operator
  hardware, paste via `morphit-ops alt-address`); pasting one simply replaces
  the basic address and is never overwritten.

## Alternatives considered

- **Keep Tor opt-in** — rejected; the friction is exactly why most instances
  had no onion, which contradicts the project's first priority.
- **Let the Tor daemon generate the key on first start** — rejected; the
  address would be unknown during the wizard run (see "Why generate locally").
- **Vanity onion by default** — rejected; prefix grinding is slow and unbounded,
  defeating the "instant, no wait" property. Vanity stays a manual choice.