boxdown 1.0.0 → 1.2.1

package/docs/superpowers/plans/2026-07-17-node-ssh-agent-proxy-signing.md

@@ -0,0 +1,132 @@
+# Node SSH-Agent Proxy Signing Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Enable best-effort SSH commit signing for the non-root Boxdown user while preserving explicit user Git-signing preferences.
+
+**Architecture:** A root Node proxy forwards the raw mounted agent socket to a node-owned socket. The post-create hook starts and verifies that proxy before signing bootstrap. The bootstrap applies Boxdown's SSH default only when neither global nor local Git configuration expresses a signing preference.
+
+**Tech Stack:** TypeScript, Node `net` Unix sockets, Bash lifecycle hooks, Node test runner.
+
+## Global Constraints
+
+- Do not read, copy, mount, or log private keys.
+- Signing and proxy failures must never block lifecycle commands or commits.
+- Preserve explicit user `commit.gpgsign`, `gpg.format`, `user.signingkey`, and `gpg.program` settings.
+- Existing containers require `--recreate`.
+
+---
+
+### Task 1: Add the node-accessible SSH-agent proxy
+
+**Files:**
+
+- Create: `assets/devcontainer/utils/ssh-agent-proxy.mjs`
+- Modify: `assets/devcontainer/hooks/post-create.sh`
+- Test: `__tests__/app.test.ts`
+
+- [ ] **Step 1: Write a failing proxy forwarding test**
+
+Create a temporary raw Unix server, launch the proxy with a temporary target
+socket and the current test user's UID/GID, send bytes through the target, and
+assert the raw server receives and echoes them.
+
+- [ ] **Step 2: Run the focused test to verify it fails**
+
+Run: `fnm exec --using v24.15.0 -- node --import tsx --test --test-name-pattern='forwards node SSH-agent connections' __tests__/app.test.ts`
+
+Expected: FAIL because the proxy asset does not exist.
+
+- [ ] **Step 3: Implement the proxy and lifecycle startup helper**
+
+Implement a Node `net.createServer()` bridge that unlinks stale target sockets,
+listens with mode `0600`, changes ownership to the supplied UID/GID, and pipes
+each client to the raw socket. Start it with `sudo` in post-create, wait for
+the target socket, and run `ssh-add -L` through it before signing bootstrap.
+
+- [ ] **Step 4: Run the focused test to verify it passes**
+
+Run the Task 1 command. Expected: PASS.
+
+### Task 2: Route generated configuration and diagnostics through the proxy
+
+**Files:**
+
+- Modify: `src/config.ts`
+- Modify: `assets/devcontainer/utils/git-signing-bootstrap.sh`
+- Test: `__tests__/app.test.ts`
+
+- [ ] **Step 1: Write failing generated-config and hook tests**
+
+Assert enabled plans set `SSH_AUTH_SOCK` to `/run/boxdown/ssh-agent-node.sock`,
+retain the raw source only in `BOXDOWN_GIT_SIGNING_SOURCE_SOCKET`, and disable
+signing with `container-agent-proxy-unavailable` when proxy readiness fails.
+
+- [ ] **Step 2: Run the focused tests to verify they fail**
+
+Run: `fnm exec --using v24.15.0 -- node --import tsx --test --test-name-pattern='node SSH-agent proxy|proxy-unavailable' __tests__/app.test.ts`
+
+Expected: FAIL because generated configuration still exposes the raw socket.
+
+- [ ] **Step 3: Implement proxy socket configuration and failure reporting**
+
+Add constants or literal paths for raw and node-facing sockets, update generated
+container environment, and teach the bootstrap to report the proxy reason
+without replacing user configuration.
+
+- [ ] **Step 4: Run the focused tests to verify they pass**
+
+Run the Task 2 command. Expected: PASS.
+
+### Task 3: Preserve explicit user signing configuration
+
+**Files:**
+
+- Modify: `assets/devcontainer/utils/git-signing-bootstrap.sh`
+- Modify: `docs/features/commit-signing.md`
+- Modify: `docs/superpowers/specs/2026-07-11-default-commit-signing-design.md`
+- Test: `__tests__/app.test.ts`
+
+- [ ] **Step 1: Write failing bootstrap tests**
+
+Add separate tests for repository-local `commit.gpgsign=false`, global
+non-SSH `gpg.format`, and an explicit SSH signing key. Assert the first two
+remain unchanged; assert the SSH case maps only its public-key path to the
+mounted snapshot and signs successfully.
+
+- [ ] **Step 2: Run the focused tests to verify they fail**
+
+Run: `fnm exec --using v24.15.0 -- node --import tsx --test --test-name-pattern='preserves explicit.*signing' __tests__/app.test.ts`
+
+Expected: FAIL because the bootstrap currently overwrites global SSH settings.
+
+- [ ] **Step 3: Implement explicit-preference detection**
+
+Check local configuration first, then copied global configuration. Preserve an
+explicit opt-out or non-SSH configuration; use Boxdown defaults only with no
+explicit preference. For explicit SSH configuration, replace only an
+unavailable public-key path with the selected mounted key.
+
+- [ ] **Step 4: Run the focused tests to verify they pass**
+
+Run the Task 3 command. Expected: PASS.
+
+### Task 4: Document and verify
+
+**Files:**
+
+- Modify: `docs/features/commit-signing.md`
+- Modify: `docs/superpowers/specs/2026-07-11-default-commit-signing-design.md`
+- Create: `.changeset/<generated-name>.md`
+
+- [ ] **Step 1: Document the proxy, user-precedence policy, and `--recreate` requirement**
+
+- [ ] **Step 2: Add a patch changeset**
+
+- [ ] **Step 3: Run complete verification**
+
+Run: `pnpm test`, `pnpm lint`, `pnpm build`, `bash -n assets/devcontainer/utils/git-signing-bootstrap.sh`, `node --check assets/devcontainer/utils/ssh-agent-proxy.mjs`, and `git diff --check`.
+
+- [ ] **Step 4: Commit**
+
+Use: `git commit -m "fix: proxy SSH agent for commit signing"`

package/docs/superpowers/plans/2026-07-17-runtime-secret-environment.md

@@ -0,0 +1,174 @@
+# Runtime Secret Environment Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Keep Boxdown-provided secrets available in Bash sessions without writing their values to the repository, persistent Boxdown state, Docker environment configuration, or workspace logs.
+
+**Architecture:** A private per-workspace runtime directory holds three secret files and is mounted read-only at `/run/boxdown/secrets`. A Bash bootstrap exports values for interactive, non-interactive, SSH, and Boxdown coding-agent Bash sessions. Docker configuration carries only paths; metadata inspection requests only image fields; logging structurally redacts known assignments.
+
+**Tech Stack:** Node.js 24, TypeScript, Bash, `node:test`, Docker/Dev Containers configuration.
+
+## Global Constraints
+
+- Do not print, log, serialize, or place a secret value in generated configuration, command arguments, metadata, or diagnostics.
+- Fixed Boxdown secret names: `ANTHROPIC_API_KEY`, `SNYK_TOKEN`, and `OP_SERVICE_ACCOUNT_TOKEN`.
+- Missing values and unavailable 1Password access are non-blocking; the affected variable is absent.
+- `.env.development` is project-owned: Boxdown does not create, edit, delete, or migrate it.
+- Runtime secret directories/files use `0700`/`0600` and are outside `workspaceDataDir`.
+- Existing containers require `boxdown start --recreate`; do not add legacy cleanup or `doctor --fix-secrets`.
+
+---
+
+## File Structure
+
+| File | Responsibility |
+| --- | --- |
+| `src/constants.ts`, `src/paths.ts` | Runtime secret paths and fixed secret-name constants. |
+| `src/config.ts`, `assets/devcontainer/devcontainer.json` | Read-only mount and non-secret Bash bootstrap config. |
+| `assets/devcontainer/hooks/initialize.sh` | Atomically create/remove runtime secret files. |
+| `assets/devcontainer/utils/secret-env-bootstrap.sh` | Read fixed files and export present values without output. |
+| `assets/devcontainer/hooks/post-create.sh`, `src/shell.ts` | Source bootstrap for interactive and Boxdown-launched Bash sessions. |
+| `src/main.ts`, `src/purge.ts` | Remove workspace runtime state after down/purge. |
+| `src/devcontainer.ts`, `src/logging.ts` | Narrow Docker inspection and structural redaction. |
+| `src/doctor.ts`, docs, `__tests__/app.test.ts` | Safety checks, documentation, and regression tests. |
+
+### Task 1: Define runtime secret state and remove workspace injection
+
+**Files:**
+
+- Modify: `src/constants.ts`, `src/paths.ts`, `src/config.ts`, `assets/devcontainer/devcontainer.json`, `assets/devcontainer/hooks/initialize.sh`, `assets/devcontainer/hooks/post-start.sh`, `__tests__/app.test.ts`
+
+**Interfaces:**
+
+```ts
+export const BOXDOWN_SECRET_ENV_NAMES = ['ANTHROPIC_API_KEY', 'SNYK_TOKEN', 'OP_SERVICE_ACCOUNT_TOKEN'] as const
+export const BOXDOWN_CONTAINER_SECRET_ENV_DIR = '/run/boxdown/secrets'
+export const BOXDOWN_CONTAINER_SECRET_ENV_BOOTSTRAP = '/opt/boxdown/devcontainer/utils/secret-env-bootstrap.sh'
+export function defaultRuntimeRoot (env?: NodeJS.ProcessEnv): string
+// WorkspaceContext adds runtimeRoot, workspaceRuntimeDir, workspaceSecretEnvDir.
+```
+
+- [ ] **Step 1: Write failing tests**
+
+Create a context with `BOXDOWN_RUNTIME_HOME`. Assert that its secret directory starts below runtime root but not persistent workspace data. Assert generated config mounts that directory read-only at `/run/boxdown/secrets`, sets the non-secret bootstrap `BASH_ENV`, retains `NODE_ENV`, and serializes none of `--env-file`, `.env.development`, or the three secret names.
+
+- [ ] **Step 2: Verify red**
+
+Run `pnpm test -- --test-name-pattern "runtime secret|generated config"`. Expected: FAIL because the current config injects workspace-file and Docker-environment secrets.
+
+- [ ] **Step 3: Implement paths and config**
+
+Add the fixed constants. Resolve runtime root in this order: `BOXDOWN_RUNTIME_HOME`; then `join(XDG_RUNTIME_DIR, PACKAGE_NAME)`; then `join(tmpdir(), package-name plus UID)`. Add workspace-ID scoped runtime/secret paths. Append the read-only secret mount and `BASH_ENV`; remove the base `--env-file` pair and secret `containerEnv` values while preserving non-secret entries.
+
+- [ ] **Step 4: Implement host runtime-file refresh**
+
+Pass only `BOXDOWN_SECRET_ENV_DIR` to `initializeCommand`. Set `umask 077`; create the directory at `0700`; write each nonempty file through `mktemp` plus `chmod 0600` plus atomic rename; remove a file when its host value is absent. Read the existing 1Password reference into a local variable and never echo it. Remove all `.env.development` preparation/upsert logic and post-start deletion.
+
+- [ ] **Step 5: Verify green and commit**
+
+Run `pnpm test -- --test-name-pattern "runtime secret|generated config|devcontainer git config hooks"` and `bash -n assets/devcontainer/hooks/initialize.sh assets/devcontainer/hooks/post-start.sh`; expect both to pass. Commit the listed sources and tests as `feat: mount runtime secret environment`.
+
+### Task 2: Export secret files in supported Bash sessions and clean runtime state
+
+**Files:**
+
+- Create: `assets/devcontainer/utils/secret-env-bootstrap.sh`
+- Modify: `assets/devcontainer/hooks/post-create.sh`, `src/shell.ts`, `src/main.ts`, `src/purge.ts`, `__tests__/app.test.ts`
+
+**Interfaces:**
+
+```bash
+# Bootstrap reads /run/boxdown/secrets/<fixed-name> and exports only present values.
+```
+
+- [ ] **Step 1: Write failing tests**
+
+Run the bootstrap against a temporary secret directory with sentinel values. Assert each present value is exported, an absent file remains unset, and stdout/stderr do not contain a sentinel. Assert interactive shell/agent scripts source the bootstrap before `exec`. Assert down/purge remove only workspace runtime state.
+
+- [ ] **Step 2: Verify red**
+
+Run `pnpm test -- --test-name-pattern "secret bootstrap|runtime secret cleanup|interactive shell setup"`. Expected: FAIL because no bootstrap or runtime cleanup exists.
+
+- [ ] **Step 3: Implement bootstrap/session loading**
+
+Create a no-output script that reads the three fixed files with `IFS= read -r`, exports only nonempty values, and never sources secret file contents as code. Add an idempotent source line to the node user's `.bashrc` in post-create. Add the same bootstrap source before final `exec` in both shell script builders; never add a value to `interactiveShellEnvArgs`.
+
+- [ ] **Step 4: Implement safe runtime cleanup**
+
+Add a path-contained helper that removes only `context.workspaceRuntimeDir`, accepts absence, and never removes `runtimeRoot`. Invoke it after successful down and during purge before persistent state removal.
+
+- [ ] **Step 5: Verify green and commit**
+
+Run `pnpm test -- --test-name-pattern "secret bootstrap|runtime secret cleanup|interactive shell setup"` and `bash -n assets/devcontainer/utils/secret-env-bootstrap.sh assets/devcontainer/hooks/post-create.sh`; expect pass. Commit as `feat: export runtime secrets in Bash sessions`.
+
+### Task 3: Replace full Docker inspection and harden logging
+
+**Files:**
+
+- Modify: `src/devcontainer.ts`, `src/logging.ts`, `__tests__/app.test.ts`
+
+**Interfaces:**
+
+```ts
+export function parseDockerInspectImage (output: string, containerId: string): DockerImageInfo | undefined
+export function redactKnownSecretEnvironmentAssignments (value: string): string
+```
+
+- [ ] **Step 1: Write failing tests**
+
+Test parsing two JSON-string lines representing image ID/name. Add a fake Docker complete-inspect fixture containing an OP sentinel, assert the lifecycle log omits it and inspect uses a narrow format. Test plain and Docker-JSON assignment forms for each known secret variable.
+
+- [ ] **Step 2: Verify red**
+
+Run `pnpm test -- --test-name-pattern "docker inspect|known secret|workspace logger"`. Expected: FAIL because inspect uses `{{json .}}` and logging is value-only.
+
+- [ ] **Step 3: Implement projection/redaction**
+
+Use Docker format `{{json .Image}}` followed by `{{json .Config.Image}}`; parse exactly two scalar JSON lines and provide a container-ID-specific malformed-output error. Redact values after each fixed name before dynamic redactions and apply it through logger `#redact` for arguments, sections, errors, and child output while preserving the names.
+
+- [ ] **Step 4: Verify green and commit**
+
+Run `pnpm test -- --test-name-pattern "docker inspect|known secret|workspace logger"`; expect pass. Commit as `fix: keep container secrets out of workspace logs`.
+
+### Task 4: Doctor coverage and documentation
+
+**Files:**
+
+- Modify: `src/doctor.ts`, `__tests__/app.test.ts`, `assets/devcontainer/README.md`, `docs/features/generated-config-and-state.md`, `docs/features/start-and-shell.md`
+
+- [ ] **Step 1: Write failing tests**
+
+Extend doctor fake-command tests to require a disposable runtime-secret mount probe and a warning when generated config contains env-file, `.env.development`, or a fixed secret name in `containerEnv`. Add existing-style static documentation assertions for session exposure and `--recreate`.
+
+- [ ] **Step 2: Verify red**
+
+Run `pnpm test -- --test-name-pattern "doctor|generated config|runtime secret"`. Expected: FAIL because doctor does not inspect those conditions.
+
+- [ ] **Step 3: Implement non-blocking checks/docs**
+
+Add `workspaceSecretEnvDir` to disposable mount probes. Add a `secret-environment-config` doctor result: missing generated config is warning, unsafe config is warning, safe config is ok; never read secret file contents. Update docs: values are ordinary Bash-session variables but not Docker config; `.env.development` is ignored; missing values are non-blocking; existing containers need recreate; legacy leaked values/logs require manual removal and rotation.
+
+- [ ] **Step 4: Verify green and commit**
+
+Run `pnpm test -- --test-name-pattern "doctor|generated config|runtime secret"`; expect pass. Commit as `docs: describe runtime secret environment handling`.
+
+### Task 5: Full verification
+
+- [ ] **Step 1: Run the complete suite**
+
+Run `pnpm test`, `pnpm lint`, `pnpm build`, `bash -n` for all changed hooks/utilities, `git diff --check`, and `git diff main...HEAD --check`. Expected: every command exits 0.
+
+- [ ] **Step 2: Review secret-safety diff**
+
+Run `git diff main...HEAD -- assets/devcontainer/devcontainer.json src/config.ts src/devcontainer.ts src/logging.ts`. Confirm no implementation path writes `.env.development`, uses `--env-file`, or contains literal token-like values.
+
+- [ ] **Step 3: Commit a verification-only correction when required**
+
+If verification requires a source correction, commit only that correction as `test: cover runtime secret environment regression`.
+
+## Plan Self-Review
+
+- Tasks 1–2 implement runtime-only state and compatible Bash-session exports.
+- Task 3 removes the full-inspect log leak and adds a logging backstop.
+- Task 4 adds doctor/documentation coverage without legacy cleanup.
+- Task 5 runs full test, lint, build, Bash syntax, and diff checks.