Dev

.factory/init.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+bun install --frozen-lockfile

.factory/library/architecture.md

@@ -0,0 +1,149 @@
+# Architecture
+
+How the system works at a high level for this mission.
+
+**What belongs here:** major components, relationships, data flows, and invariants that workers need to preserve.
+**What does NOT belong here:** step-by-step task instructions, exact release commands, or port allocations.
+
+---
+
+## Runtime Modes
+
+Igloo Server has two runtime modes that matter to this mission:
+
+- **Database mode**: multi-user mode with SQLite persistence, session/API-key auth, web UI, and the NIP-46 service.
+- **Headless mode**: environment-driven mode without the DB-only management surfaces.
+
+This mission's NIP-46 work and the cross-surface validation contract depend on **database mode**. The HTTP `/api/nip44/*` routes exist in both modes, but the shared API/RPC interop proof must use one DB-mode instance because NIP-46 is only available there.
+
+## Mission-Relevant Component Map
+
+Workers should know the main files before changing anything:
+
+- `src/routes/index.ts` — top-level request router and auth/mount behavior
+- `src/routes/nip44.ts` — HTTP `/api/nip44/encrypt` and `/api/nip44/decrypt`
+- `src/routes/crypto-utils.ts` — peer normalization and shared-secret derivation
+- `src/routes/nip46.ts` — DB-mode NIP-46 HTTP/session management endpoints
+- `src/db/nip46.ts` — persisted NIP-46 sessions, requests, and policy data
+- `src/nip46/service.ts` — NIP-46 request processing, policy auto-approval, and `nip44_*` RPC execution
+- `docs/openapi/openapi.yaml` — released HTTP API contract
+- `package.json` / `CHANGELOG.md` — source release metadata
+- `../igloo-server-store/igloo-server/umbrel-app.yml` — Umbrel store manifest
+- `../igloo-server-store/igloo-server/docker-compose.yml` — Umbrel store image/runtime pin
+
+## HTTP API Path
+
+The request router in `src/routes/index.ts` applies auth and routes API traffic into focused handlers.
+
+For the NIP-44 HTTP surface:
+
+1. The router authenticates the request and builds a route context.
+2. `src/routes/nip44.ts` validates request shape, enforces request-size and rate-limit checks, normalizes `peer_pubkey`, and requires an active signing node.
+3. `src/routes/crypto-utils.ts` performs peer normalization and derives the raw shared secret (`shared_x`) from threshold ECDH.
+4. The NIP-44 route must transform that raw shared secret into the **NIP-44 conversation key** before calling `nostr-tools` NIP-44 encrypt/decrypt helpers.
+
+### Mission-critical invariant
+
+- The value returned by threshold ECDH is **input keying material**, not the final NIP-44 conversation key.
+- Only NIP-44 surfaces apply the `nip44-v2` conversation-key derivation step.
+- This mission must **not** broaden into the separate NIP-04 behavior.
+
+## NIP-46 RPC Path
+
+`src/nip46/service.ts` runs the remote-signer request loop for NIP-46.
+
+High-level flow:
+
+1. A client establishes a NIP-46 session and transport.
+2. Session and policy state are created/updated through `src/routes/nip46.ts` and persisted in `src/db/nip46.ts`.
+3. Requests are stored/tracked, then either auto-approved by policy or held in a pending queue for manual handling.
+4. `nip44_encrypt` and `nip44_decrypt` eventually call the same underlying shared-secret path used by the HTTP NIP-44 surface.
+5. Responses are returned over the NIP-46 transport using the original request ID.
+
+### Mission-critical invariants
+
+- HTTP `/api/nip44/*` and NIP-46 `nip44_*` must derive the **same** standards-compliant NIP-44 conversation key from the same signer/peer relationship.
+- Method-specific NIP-46 policy grants remain separate: `nip44_encrypt` and `nip44_decrypt` can be granted independently.
+- Ungranted NIP-46 requests should remain pending until handled; they must not falsely succeed.
+
+## Surface Contracts Workers Must Preserve
+
+| Surface | Input shape | Output shape | Mode/auth constraints |
+| --- | --- | --- | --- |
+| HTTP `/api/nip44/encrypt` | JSON `{ peer_pubkey, content }` | JSON `{ result: <ciphertext> }` or JSON error | Mounted in both modes; auth-gated by router |
+| HTTP `/api/nip44/decrypt` | JSON `{ peer_pubkey, content }` | JSON `{ result: <plaintext> }` or JSON error | Mounted in both modes; auth-gated by router |
+| NIP-46 `nip44_encrypt` | RPC params `[peer_pubkey, plaintext]` | RPC `{ id, result }` or `{ id, error }` | DB mode only; requires a connected session and approval/policy |
+| NIP-46 `nip44_decrypt` | RPC params `[peer_pubkey, ciphertext]` | RPC `{ id, result }` or `{ id, error }` | DB mode only; requires a connected session and approval/policy |
+| NIP-46 `get_public_key` | no payload beyond request envelope | signer user pubkey | Used by interop harness to derive peer-side standards-compliant ciphertext |
+
+### Defense-in-depth auth behavior
+
+Even when `AUTH_ENABLED=false`, the route handlers for `/api/nip44/*`, `/api/sign`, and `/api/nip04/*` still return `401` for unauthenticated requests. The router only injects `authInfo` when `AUTH_CONFIG.ENABLED` is true, but the handlers themselves require an explicit `authenticated` auth context. This means smoke tests that set `AUTH_ENABLED=false` must still provide a valid authenticated session or API key to reach these routes.
+
+When testing these routes in a hermetic smoke, either:
+- Set `AUTH_ENABLED=true` and authenticate with a valid session or API key, or
+- Use the test harnesses that bypass the router's auth enforcement for unit/contract tests.
+
+## Shared Crypto Boundary
+
+The shared crypto boundary for this mission is:
+
+- `xOnly(...)` / peer normalization
+- threshold ECDH shared-secret derivation
+- NIP-44 conversation-key derivation
+
+Workers should preserve these invariants:
+
+- Accept x-only and compressed peer-key forms consistently across HTTP and NIP-46 surfaces.
+- Fail fast on malformed request shapes before claiming cryptographic success.
+- Keep the NIP-44 fix surgical: update only the NIP-44 paths that currently misuse the raw shared secret.
+- Do not add a legacy decrypt fallback; the mission requires standards-only behavior.
+
+### Single source of truth for NIP-44 conversation-key derivation
+
+The `deriveNip44ConversationKey` helper in `src/routes/crypto-utils.ts` is the single source of truth for NIP-44 v2 conversation-key derivation across both HTTP and NIP-46 surfaces. Any future NIP-44 crypto work must use this helper instead of raw ECDH output to maintain interop. The helper applies HKDF-extract with salt `"nip44-v2"` to the threshold ECDH shared secret (`shared_x`).
+
+## Release and Store Artifact Lineage
+
+This mission spans two repos and two release artifacts.
+
+### Source repo (`igloo-server`)
+
+Target end state for this mission:
+
+1. Work lands on the mission branch based on `origin/dev`.
+2. Release preparation flows through the source repo's release process (`scripts/release.sh` and merge to `master`).
+3. `.github/workflows/release.yml` publishes:
+   - git tag / GitHub release
+   - standard GHCR image from the root `Dockerfile`
+   - Umbrel GHCR image from `packages/umbrel/igloo/Dockerfile`
+
+Important distinction: this section describes the **intended post-mission release path**, not necessarily the current pre-mission repo/store state.
+
+### Store repo (`igloo-server-store`)
+
+Target end state for this mission:
+
+1. The store repo consumes the released Umbrel artifact via `igloo-server/docker-compose.yml`.
+2. The user-visible store metadata lives in `igloo-server/umbrel-app.yml`.
+3. The store repo is updated only after the source release artifact exists and is verified.
+4. For this mission, rollout stops at **store repo push**. It does **not** include updating a live Umbrel node.
+
+## End-to-End Validation Shape
+
+This mission is primarily validated through API, RPC, release, and container surfaces rather than browser UI.
+
+Validation layers:
+
+- **Local readiness**: install, validators, startup smoke.
+- **HTTP contract tests**: `/api/nip44/*` interop and failure semantics.
+- **NIP-46 integration tests**: real session/request flow plus interop and policy behavior.
+- **Release verification**: tag/release/image publication and image boot smoke.
+- **Store rollout verification**: exact pinned Umbrel image, manifest/compose contract, local Umbrel-image boot smoke, and store repo push.
+
+## What Workers Should Optimize For
+
+- Prefer the narrowest change that restores standards-compliant NIP-44 behavior.
+- Reuse shared helpers so the HTTP and NIP-46 paths cannot drift.
+- Treat OpenAPI, release metadata, GHCR artifacts, and store manifests as part of the shipped contract for this mission.
+- Preserve DB-mode behavior and approval semantics while fixing crypto interoperability.

.factory/library/environment.md

@@ -0,0 +1,39 @@
+# Environment
+
+Environment variables, external dependencies, and setup notes.
+
+**What belongs here:** required env vars, external services, local repo relationships, and environment-specific constraints.
+**What does NOT belong here:** service ports/commands (use `.factory/services.yaml`).
+
+---
+
+## Working Repos
+
+- Source repo: `/Users/plebdev/Desktop/Work/code/frostr/igloo/igloo-server`
+- Store repo: `/Users/plebdev/Desktop/Work/code/frostr/igloo/igloo-server-store`
+- Mission branch in source repo: `mission/nip44-release` (tracks `origin/dev`)
+
+## Available Tooling
+
+- Bun is installed locally (`bun 1.3.11` observed during planning)
+- Docker and `docker buildx` are available locally
+- GitHub CLI is available and already authenticated on this machine
+
+## Environment Constraints
+
+- No local `.env` files were found in the source repo during planning
+- Do not rely on ambient shell or `.env` state for readiness or container smoke tests
+- For hermetic local smokes, pin env explicitly and use a temporary `DB_PATH`
+- DB mode is required for NIP-46 validation; headless mode is insufficient for the cross-surface contract
+
+## Ports and Shared Machine Boundaries
+
+- Mission app port: `8002`
+- Avoid already busy local ports/services observed during planning: `3000`, `8080`, `8081`, `8082`, `9090`, `9101`
+- Do not disturb unrelated local containers or background services already running on this machine
+
+## External / Sensitive Prerequisites
+
+- Real live-node NIP API smoke requires usable auth plus signing-node credentials and a peer pubkey fixture
+- If those real credentials are not available after readiness setup, workers should stop and return to orchestrator rather than faking end-to-end validation
+- Do not expose secrets, API keys, or persisted credentials in logs, commits, or handoffs

.factory/library/release.md

@@ -0,0 +1,60 @@
+# Release and Rollout Notes
+
+Release-specific facts and artifact relationships for this mission.
+
+**What belongs here:** source release flow, image lineage, store repo handoff, and rollout constraints.
+**What does NOT belong here:** implementation details for route fixes.
+
+---
+
+## Source Release Line
+
+- Mission work is based on `origin/dev` via local branch `mission/nip44-release`
+- Current source repo version on this line is `1.2.0`
+- The source release publishes from `master`, not directly from the mission branch head
+
+## Source Release Contracts
+
+The release worker must keep these files/facts aligned:
+- `package.json`
+- `CHANGELOG.md`
+- `docs/openapi/openapi.yaml`
+- git tag / GitHub release `v<version>`
+- GHCR images for standard and Umbrel variants
+
+Use `bun run version:check` as the first metadata consistency gate.
+
+## Published Artifacts
+
+Release workflow expectations:
+- Standard source release assets on GitHub releases
+- Standard image from the root `Dockerfile`
+- Umbrel image from `packages/umbrel/igloo/Dockerfile`
+- GHCR tags expected by the mission contract:
+  - `ghcr.io/frostr-org/igloo-server:<version>`
+  - `ghcr.io/frostr-org/igloo-server:latest`
+  - `ghcr.io/frostr-org/igloo-server:umbrel-<version>`
+  - `ghcr.io/frostr-org/igloo-server:umbrel-latest`
+
+The release workflow also sets OCI labels for version and revision; workers should use those labels to verify that a published image actually corresponds to the released source commit.
+
+## Store Repo Handoff
+
+Store repo path:
+- `/Users/plebdev/Desktop/Work/code/frostr/igloo/igloo-server-store`
+
+Files that matter for rollout:
+- `igloo-server/umbrel-app.yml`
+- `igloo-server/docker-compose.yml`
+
+Important current-state nuance discovered during planning:
+- the store repo currently advertises `version: 1.1.0`
+- the store compose currently points at `ghcr.io/frostr-org/igloo-server:umbrel-dev@sha256:...`
+
+Workers must treat those as **pre-mission state**, not the intended end state. The rollout feature must derive the correct released Umbrel artifact and then make the store repo match it.
+
+## Rollout Scope Boundary
+
+- This mission includes updating and pushing the local sibling store repo
+- This mission does **not** include installing/updating a live Umbrel node
+- Local container smokes are allowed and expected for the exact released/store-pinned Umbrel image

.factory/library/testing.md

@@ -0,0 +1,25 @@
+# Testing Conventions
+
+Patterns and helpers for unit and integration tests in this codebase.
+
+## runRouteScript helper
+
+The `runRouteScript` test helper is the canonical way to exercise internal service methods (including TypeScript `private` methods) without standing up a full HTTP server. It spawns a Bun process that imports the service/module and calls the target method directly. This is useful for unit-testing service internals that are not exposed through public APIs.
+
+Example usage:
+```typescript
+// tests/routes/nip46.spec.ts
+runRouteScript({
+  script: `import { Nip46Service } from './src/nip46/service.ts'; ...`,
+  // calls service.handleNip44Encrypt or service.handleNip44Decrypt directly
+});
+```
+
+## NIP-44 interop test fixtures
+
+When writing NIP-44 interoperability tests, use these fixture builders to simulate a standards-compliant peer without exposing real signing credentials:
+
+- `buildNip46PeerFixture` (in `tests/routes/nip46.spec.ts`) — creates an independent peer keypair and uses `@noble/curves/secp256k1` for ECDH plus `nostr-tools` as the NIP-44 oracle.
+- `buildCrossSurfaceFixture` (in `tests/routes/protected.api.spec.ts`) — same pattern but shared across HTTP and NIP-46 cross-surface tests.
+
+Both patterns derive the conversation key externally via `nostr-tools` `getConversationKey(...)` and use the resulting key to encrypt/decrypt ciphertext that the Igloo server must be able to decrypt/encrypt. This lets tests simulate threshold ECDH without needing real FROSTR credentials.

.factory/library/tooling-quirks.md

@@ -0,0 +1,19 @@
+# Tooling Quirks
+
+Known quirks and workarounds for the local tooling and CI environment.
+
+---
+
+## Secret Scanner Heuristics
+
+The Droid-Shield secret scanner flags variable assignments whose names end in `Key` (e.g., `conversationKey`) as potential secret leaks, even when the right-hand side is a harmless function call (e.g., `hkdf(...)`).
+
+### Workaround
+
+When writing crypto code that derives conversation keys or similar intermediate key material, name the variable something that does not end in `Key`. For example:
+
+- Use `convBytes` instead of `conversationKey`
+- Use `derivedBytes` instead of `derivedKey`
+- Use `sharedX` instead of `sharedSecretKey`
+
+This avoids false-positive secret scanner alerts without changing the actual logic.

.factory/library/user-testing.md

@@ -0,0 +1,81 @@
+# User Testing
+
+Testing surfaces, tools, and concurrency guidance for this mission.
+
+**What belongs here:** validation surfaces, testing tools, runtime constraints, and concurrency limits.
+**What does NOT belong here:** implementation details or feature-specific task steps.
+
+---
+
+## Validation Surface
+
+This mission is validated primarily through API/RPC, release, and container surfaces. Browser UI validation is not the primary surface here.
+
+### 1. Local command validators
+- Surface: source repo install/test/typecheck/build/docs validation
+- Tools: `bun`, `git`
+- Assertions: `VAL-READY-001`, `VAL-READY-002`, parts of release assertions
+- Notes: use repo-standard commands from `.factory/services.yaml`
+
+### 2. HTTP API surface
+- Surface: local DB-mode server on port `8002`
+- Tools: `curl`, Bun contract tests
+- Assertions: `VAL-READY-003`, `VAL-READY-004`, `VAL-NIP44-API-*`
+- Notes: prefer hermetic DB-mode smoke with explicit env; do not rely on ambient credentials
+
+### 3. NIP-46 RPC surface
+- Surface: DB-mode server plus relay-backed NIP-46 session/request flow
+- Tools: Bun integration tests, Nostr Connect-compatible test client, `curl` for policy/bootstrap endpoints
+- Assertions: `VAL-NIP46-*`, `VAL-CROSS-001`
+- Notes: use independent NIP-44 derivation via `nostr-tools`; do not use Igloo helpers as the oracle
+
+### 4. Source release surface
+- Surface: git tag / GitHub release / GHCR image publication
+- Tools: `git`, `gh`, `docker`
+- Assertions: `VAL-RELEASE-*`
+- Notes: release verification must target the released `master` commit, not only the mission branch head
+
+### 5. Umbrel store rollout surface
+- Surface: sibling store repo plus exact released Umbrel image
+- Tools: `git`, `gh`, `docker run`, `curl`
+- Assertions: `VAL-UMBREL-*`, `VAL-CROSS-002`
+- Notes: scope stops at store repo push; no live Umbrel device install/update in this mission
+
+### 6. Optional live API NIP smoke
+- Surface: running app with real auth + real signing-node credentials + test peer
+- Tools: `bun run api:test:nip`
+- Notes: only run if usable credentials exist after readiness; otherwise return to orchestrator
+
+## Validation Concurrency
+
+Machine profile gathered during planning:
+- 18 logical CPUs
+- 137,438,953,472 bytes RAM total
+- Baseline memory use during dry run was roughly 43 GiB, leaving ample headroom
+
+Even though raw CPU/RAM headroom is high, concurrency here is constrained more by isolation, fixed ports, shared DB/session state, and remote mutation than by memory.
+
+### Command/static validation
+- Surfaces: install, tests, typecheck, build, docs validation
+- Max concurrent validators: **5**
+- Rationale: lightweight relative to available CPU/RAM; capped conservatively to preserve headroom and reduce I/O contention
+
+### HTTP live smoke on port 8002
+- Surfaces: local readiness and API smoke against one running app instance
+- Max concurrent validators: **1**
+- Rationale: fixed port and shared DB-mode process
+
+### NIP-46 relay-backed integration
+- Surfaces: session/policy/request flow and RPC interop
+- Max concurrent validators: **2**
+- Rationale: stateful DB-mode session queue plus relay/request coupling make higher concurrency brittle even though hardware could handle more
+
+### Release / remote mutation checks
+- Surfaces: git tags, GitHub release objects, remote pushes, store repo pushes
+- Max concurrent validators: **1**
+- Rationale: remote mutation and shared git state must remain serialized
+
+### Docker image boot smokes
+- Surfaces: published standard image and exact store-pinned Umbrel image
+- Max concurrent validators: **1**
+- Rationale: fixed local port, image pulls, and container lifecycle should remain serialized for clean evidence