archy/.planning/intel/decisions.md

# Decisions (from ADRs)

Extracted from 10 classified ADRs. All are `locked: true` (Status: Accepted) and cannot be auto-overridden by any lower-precedence source.

## ADR-001: Podman Over Docker
- source: docs/adr/001-podman-over-docker.md
- status: locked (Accepted)
- decision: Use Podman as the container runtime instead of Docker. Rootless by default, daemonless, Docker-compatible, native systemd integration, OCI-compliant. Use `archy-net` custom network for inter-container DNS.
- scope: container runtime, rootless containers, systemd integration, archy-net network

## ADR-002: DID Key Method for Node Identity
- source: docs/adr/002-did-key-method.md
- status: locked (Accepted)
- decision: Use `did:key` (Ed25519) as the primary DID method for node identity. Self-contained, offline-capable, local resolution. Known gaps (no rotation, no service endpoints, no revocation) mitigated via federation trust lists and separately-stored service endpoints; future migration to did:peer/did:web possible if rotation is needed.
- scope: node identity, DID methods, Ed25519 keys, peer authentication, federation trust lists, verifiable credentials

## ADR-003: Nostr Relays for Node and App Discovery
- source: docs/adr/003-nostr-for-discovery.md
- status: locked (Accepted)
- decision: Use Nostr relays (NIP-78, kind 30078) for both node discovery and marketplace app manifests. Query multiple relays in parallel with dedupe; local cache with 15-minute TTL; trust scoring (DID verification, relay consensus, federation trust); hashtag filtering (`archipelago-marketplace`); NIP-33 replaceable events for updates; Tor-compatible via SOCKS proxy.
- scope: node discovery, app discovery, marketplace app manifests, NIP-78, NIP-33 replaceable events, trust scoring, relay caching

## ADR-004: Tor Hidden Services for Peer Communication
- source: docs/adr/004-tor-for-peer-communication.md
- status: locked (Accepted)
- decision: Use Tor hidden services (.onion addresses) for all inter-node communication. Scoped to RPC/control plane only — bulk data (container images) pulled from registries. Retry with backoff; `archy-tor` container runs automatically with host networking; federation sync interval (5 min) tolerates occasional failures.
- scope: inter-node communication, federation sync, archy-tor container, RPC/control plane, NAT traversal

## ADR-005: ChaCha20-Poly1305 for Backup Encryption
- source: docs/adr/005-chacha20-backup-encryption.md
- status: locked (Accepted)
- decision: Use ChaCha20-Poly1305 (AEAD) with Argon2id key derivation for backup encryption at rest, chosen over AES-256-GCM and XChaCha20-Poly1305. Random nonce per backup stored alongside ciphertext; Argon2id with 64MB memory cost and 3 iterations for password-to-key derivation.
- scope: backup encryption, AEAD, Argon2id key derivation, nonce handling

## ADR-006: Nostr Relays for Marketplace Discovery
- source: docs/adr/006-nostr-marketplace-discovery.md
- status: locked (Accepted)
- decision: Use Nostr relays (NIP-78, kind 30078 events) for decentralized app manifest discovery instead of a centralized marketplace server. Developers publish signed manifests to public relays; nodes query multiple relays; trust scoring via cross-relay verification count, DID-linked developer reputation, optional community endorsements. Trust tiers: Verified (known developer, 3+ relays, DID-verified), Community (2+ relays, valid manifest, unsigned/new developer), Unverified (single relay, new developer). Local relay-response caching; built-in curated list for essential apps; manifest signature verification before installation.
- scope: marketplace, app manifest discovery, trust scoring, trust tiers, manifest signature verification

## ADR-007: DID-Based Federation Trust
- source: docs/adr/007-did-federation-trust.md
- status: locked (Accepted)
- decision: Use bilateral DID-based verification with single-use invite codes for federation trust establishment. Invite code carries DID, .onion address, and shared secret; exchanged out-of-band; both nodes verify DIDs via signed challenges over Tor; ongoing communication is DID-authenticated over Tor hidden services. Trust levels: Trusted (full access), Observer (read-only), Untrusted (blocked). Discovery (ADR-003) finds nodes; federation trusts them.
- scope: federation, DID verification, invite codes, trust levels, Tor hidden services, Ed25519 keys
- cross-refs: ADR-003

## ADR-008: Dual Key Strategy (Ed25519 + Secp256k1)
- source: docs/adr/008-dual-key-strategy.md
- status: locked (Accepted)
- decision: Maintain two key pairs per node identity, both derived from one master seed: Ed25519 as canonical identity (DID documents, verifiable credentials, federation auth, backup encryption via X25519 DH) and secp256k1 for Nostr/Bitcoin/Lightning (event publishing, node discovery, Lightning channel auth). Secp256k1 key linked to the DID via Nostr profile (NIP-05). Backup captures the master seed; DID document includes both verification methods.
- scope: node identity, key derivation, master seed, Ed25519, secp256k1, DID documents, federation authentication, backup encryption, Nostr event publishing, node discovery, Lightning Network

## ADR-009: Manifest-Level Container Security Enforcement
- source: docs/adr/009-manifest-container-security.md
- status: locked (Accepted)
- decision: Enforce mandatory container security defaults at the manifest level, applied automatically during container creation. Non-negotiable defaults: `readonly_root: true`, `no_new_privileges: true`, non-root user (UID > 1000), drop ALL capabilities (add back only required), pinned image tags (no `latest`), default seccomp profile. `core/container/` validates manifests (parse → validate → reject violations → apply security context at `podman create`). Optional overrides (`readonly_root: false`, extra capabilities like NET_ADMIN) require explicit listing and documented justification, with audit trail.
- scope: container security, app manifests, manifest validation, podman container creation, security defaults, capability restrictions, seccomp
- cross-refs: docs/app-manifest-spec.md, core/container/src/, core/security/src/

## ADR-011: DWN Deprioritization
- source: docs/adr/011-dwn-deprioritization.md
- status: locked (Accepted)
- decision: Deprioritize Web5 DWN spec compliance following TBD's November 2024 shutdown. Keep existing custom DWN store code (`core/archipelago/src/network/dwn_store.rs`) for peer file catalogs and federation state; stop calling it "Web5 DWN" in user-facing text; do not invest in DWN spec compliance; prioritize Nostr + Tor federation for peer discovery and data exchange; re-evaluate only if DIF produces a viable Rust SDK or the spec regains maintainers.
- scope: DWN, Web5, dwn_store.rs, Nostr, federation, peer discovery, peer data sync