99 lines
5.2 KiB
Markdown
99 lines
5.2 KiB
Markdown
# PLAN
|
||
|
||
## Context
|
||
- Target implementation is confirmed as `m3ta.pi-agent` (no container mode).
|
||
- You want a **fresh-from-scratch rewrite** of `modules/nixos/pi-agent.nix` and to ignore prior behavior as design baseline.
|
||
- Required behavior:
|
||
- dedicated isolated Unix user/group for Pi (`pi-agent` defaults)
|
||
- host UX stays `pi`
|
||
- bypass prevention (wrapper should be the canonical executable path)
|
||
- per-host-user project root policy (different roots per user)
|
||
- no writable/access scope beyond isolated Pi home/state + explicitly allowed project roots
|
||
- isolated environment must include user Pi config from HM (`modules/home-manager/coding/agents/pi.nix`) and support Nix-managed settings/env merging.
|
||
- Repo findings:
|
||
- `modules/nixos/default.nix` + `flake.nix` already import/export `pi-agent` module.
|
||
- `modules/home-manager/coding/agents/pi.nix` already renders Pi config files under a configurable relative path (`coding.agents.pi.path`, default `.pi/agent`).
|
||
|
||
## Approach
|
||
- Fully replace `modules/nixos/pi-agent.nix` with a new design centered on:
|
||
1. **Dedicated runtime identity** (`user/group/createUser/stateDir`).
|
||
2. **Policy-driven wrapper flow** (`pi` -> privileged runner -> isolated execution).
|
||
3. **Per-user project allowlists** (cwd must be under roots assigned to invoking host user).
|
||
4. **Config + env convergence**:
|
||
- sync user HM Pi config directory (e.g. `~/.pi/agent`) into isolated state,
|
||
- merge Nix-managed Pi settings into isolated `settings.json`,
|
||
- merge Nix-managed env vars + env files into isolated runtime env source,
|
||
- make merged results visible to the isolated runtime every invocation (without container recreation semantics).
|
||
5. **Hard isolation defaults** with `systemd-run` sandboxing and explicit bind/read-write paths only for state + allowed projects.
|
||
- Keep wrapper command as `pi`, and avoid exposing direct package binary on PATH when wrapper mode is enabled.
|
||
|
||
## Files to modify
|
||
- `modules/nixos/pi-agent.nix` (full rewrite)
|
||
- `modules/nixos/default.nix` (only if import list changes)
|
||
- `flake.nix` (only if output export attrs change)
|
||
- `docs/guides/pi-agent-isolation.md` (update option model + merge behavior)
|
||
- `docs/guides/using-modules.md` (update examples/options)
|
||
|
||
## Reuse
|
||
- Module/user/service patterns:
|
||
- `modules/nixos/mem0.nix`
|
||
- `templates/nixos-module/default.nix`
|
||
- Pi config rendering contract to consume/sync:
|
||
- `modules/home-manager/coding/agents/pi.nix` (`coding.agents.pi.path`, `settings.json`, `mcp.json`, agent docs)
|
||
|
||
## Steps
|
||
- [ ] Define the new `m3ta.pi-agent` option schema for fresh module behavior, including:
|
||
- base runtime options (`package`, `binaryName`, `user`, `group`, `createUser`, `stateDir`),
|
||
- wrapper controls (`enable`, `commandName`, runner name, hide-direct-binary behavior),
|
||
- per-user policy map (allowed users and each user’s allowed project roots),
|
||
- host-config sync knobs (source path relative/absolute),
|
||
- Nix-managed settings/env options for merge.
|
||
- [ ] Implement new wrapper script:
|
||
- identify invoking user,
|
||
- validate user exists in policy map,
|
||
- expand/resolve that user’s roots,
|
||
- deny out-of-policy cwd,
|
||
- escalate only to the dedicated runner.
|
||
- [ ] Implement new privileged runner script:
|
||
- enforce root-only execution,
|
||
- resync host Pi config into isolated config dir,
|
||
- merge managed settings into isolated settings file,
|
||
- merge managed env + env files into isolated env file/export source,
|
||
- prepare deterministic project mount aliases under isolated home,
|
||
- launch Pi through hardened transient `systemd-run` unit as isolated user.
|
||
- [ ] Apply hardening policy in execution profile:
|
||
- `ProtectSystem=strict`, `ProtectHome=yes`, `NoNewPrivileges=yes`,
|
||
- explicit `ReadWritePaths` limited to state + mounted allowed projects,
|
||
- bounded runtime PATH and writable tool/cache locations under `stateDir`.
|
||
- [ ] Add assertions for misconfiguration (e.g., empty per-user roots, wrapper enabled without authorized users).
|
||
- [ ] Add tightly scoped sudoers rule for runner command only.
|
||
- [ ] Ensure bypass prevention in packaging/PATH behavior when wrapper mode is enabled.
|
||
- [ ] Update docs with new option examples (per-user roots + settings/env merge + HM sync expectations).
|
||
|
||
## Verification
|
||
- Static/eval:
|
||
- `nix flake check`
|
||
- host config eval/build with new module options.
|
||
- Policy checks:
|
||
- authorized user in authorized root: succeeds
|
||
- authorized user outside authorized root: denied
|
||
- unauthorized user: denied
|
||
- Isolation checks:
|
||
- runtime identity is isolated service user (`pi-agent`)
|
||
- no unintended write access outside `stateDir` + allowed project binds
|
||
- direct binary bypass unavailable when wrapper mode is enabled
|
||
- Merge checks:
|
||
- HM-rendered Pi files are present in isolated config dir
|
||
- Nix-managed settings are merged into effective isolated `settings.json`
|
||
- env values from declarative attrs + env files are present in isolated runtime environment.
|
||
|
||
## Open questions
|
||
- None.
|
||
|
||
## Resolved decisions
|
||
- Merge precedence is confirmed as:
|
||
1) synced host Pi config/env,
|
||
2) Nix-managed settings/env override synced values,
|
||
3) wrapper/runtime shell env does not implicitly override managed values.
|
||
- Per-user host config source defaults to `.pi/agent` for all users, with optional per-user override support in the policy map.
|