dsh-env-manager-plugin 0.0.0-stage → 0.1.0

package/docs/01-architecture/security-model.md

@@ -0,0 +1,227 @@
+# Security Model (V1)
+
+Status: normative for V1.
+
+The plugin manages internal network topology and may describe production systems. This document defines the security boundaries and the controls required by V1.
+
+Related: [AGENTS.md](../../AGENTS.md) §3, [security-policy.md](../06-operations/security-policy.md), [design.md](./design.md) §12, [data-model.md](./data-model.md).
+
+---
+
+## 1. Assets
+
+| Asset | Sensitivity | Where it lives |
+|---|---|---|
+| Hostnames, IPs, internal URLs | medium | registry YAML |
+| Service Git URLs | low–medium | registry YAML |
+| Deployment topology | medium | registry YAML |
+| Credential references | low | registry YAML |
+| Credential values | high | DSH credential service / external vault — **never here** |
+| Operation history | medium | memory plugin (P1) |
+| Skill bindings and policies | high (execution routing) | registry YAML |
+
+---
+
+## 2. Trust boundaries
+
+```text
+Browser (Client half) ──HTTP──▶ Host transport ──▶ app ──files──▶ plugin data dir
+                                      │
+Agent/model ──tools──▶ Host tools ────┤
+                                      ├──describe──▶  DSH credential service
+                                      ├──request───▶  DSH approval service
+                                      └──lookup────▶  DSH Skill registry
+```
+
+Two untrusted input paths exist: the model through tools, and the browser page through
+the local HTTP route. Registry content is user-maintained and semi-trusted. The DSH
+credential service is the only component allowed to hold secret values.
+
+---
+
+## 3. Credential handling
+
+### 3.1 Rules
+
+1. Registry records store only `credentialRef` strings.
+2. The Host calls `ctx.credentials.describe(ref)` and keeps only `{ configured, source?, writable }`.
+3. The Host never calls `ctx.credentials.resolve(ref)` and never forwards a resolved value to a tool result, diagnostic or log.
+4. Tool and HTTP outputs contain `{ ref, configured, source }` only.
+5. `credentialRef` values are validated against the credential reference pattern if one exists; otherwise a conservative pattern (`^[A-Za-z0-9._:/-]{1,200}$`) is applied.
+6. Host accounts and login records follow the same rule: `Host.accounts[].credentialRef` is a
+   reference, and `LoginRecord` stores username, time, source and result only. A web login
+   `loginUrl` is configuration, not a secret; it must be an absolute `http(s)` URL. Password,
+   private-key, token and session-recording fields are not part of the schema.
+7. The guided environment form may collect a password transiently. It sends the value
+   once to `credential`; the Host calls `ctx.credentials.set(ref, value)` and returns only
+   `{ ref, configured }`. The value is never written to YAML, never logged and never
+   returned. The Host still never calls `resolve`.
+8. Credential writes are restricted to refs matching
+   `env-manager/<environmentId>/<accountId>` so the form cannot overwrite an ambient
+   credential such as `OPENAI_API_KEY`.
+
+### 3.2 Threat: exfiltration through tool output
+
+Mitigation: a single formatting layer for tool results strips any field named `value`, `secret`, `password`, `token`, `privateKey` and similar, even if a future module accidentally adds one. This is defense in depth, not a replacement for rule 3.
+
+### 3.3 Threat: credential reference confusion
+
+A user may point a production deployment at a test credential. V1 cannot detect this; the result reports `configured: true` without revealing which secret it is. Operational review is required; this is documented as a residual risk.
+
+### 3.4 Threat: password exposure while adding or editing a node or account
+
+The add/edit node form and the add/edit account form optionally hold a login password in the
+browser input and send it in the same-origin JSON request. Shell creation and batch import
+collect no password.
+Mitigations:
+
+- the route is localhost-only, requires the custom request header, validates origin and
+  sends `cache-control: no-store`;
+- the Host forwards the value directly to `ctx.credentials.set` and does not log the
+  request body or the value;
+- the response contains only the ref and `configured`, never the value;
+- the generated YAML is checked by tests to contain the ref only.
+
+A compromised same-origin page could still submit a credential write while the user is
+present; this is accepted for a local single-user tool and documented as a residual risk.
+Credential deletion is restricted to the same `env-manager/` namespace.
+
+### 3.5 Command access is metadata, not authorization
+
+`Host.access` records that `ssh`, `kubectl` or `docker` exists on a machine; it does not
+grant permission to run anything. V1 has no remote execution path, so a declared method
+cannot be used to open a shell, call Kubernetes or run `docker exec` through this plugin.
+A future execution adapter must still apply the operation binding's approval policy,
+production checks and credential resolution. `Host.kind` and `Cluster.topology` are also
+descriptive: they do not prove cluster membership or command availability. Do not treat a
+`pod-host` badge as permission to run `docker exec` on a Pod.
+
+---
+
+## 4. Approval and production policy
+
+### 4.1 Operation routing
+
+- `policy.requiresApproval` defaults to `true` for write operations.
+- `policy.allowProduction` defaults to `false`.
+- When `environmentCategory === 'production'` and `allowProduction !== true`, the router fails with `POLICY_DENIED`.
+- The router does not execute anything; it returns the policy for the executing Skill.
+
+### 4.2 Management writes
+
+Tool writes (`env_save` / `env_delete`) request approval through `ctx.approval` when the write affects a production environment:
+
+- creating/updating an environment with `category: production`;
+- creating/updating a deployment or operation binding whose environment is production;
+- deleting any environment, deployment or binding that resolves to production.
+
+Denied approval returns `POLICY_DENIED`; nothing is written. An approval outcome other
+than `allowed-once` (`rejected`, `cancelled`, `unavailable`) denies.
+
+UI writes (`record.save` / `record.remove`) run with actor `'ui'`:
+
+- production saves are denied unless `writePolicy.allowUiProductionWrites` is true;
+- delete requires `confirm: true` and a second, explicit confirmation in the panel;
+- the UI never sends an approval request (it has no agent); it is policy-gated instead.
+
+### 4.3 Local HTTP route
+
+`POST /env-manager/api` is reachable only with:
+
+- `x-env-manager-request: 1`;
+- `Content-Type: application/json`;
+- an `Origin` equal to `ctx.webServer.getOrigin()` when the header is present;
+- a body no larger than 2 MiB.
+
+No CORS headers are sent, so a cross-origin page cannot preflight the custom header.
+The route reads no cookie and no credential. It returns only registry data that a
+`env_get`/`env_list` call could also return, plus derived context.
+
+### 4.4 Threat: approval bypass
+
+A caller could edit YAML files directly, outside the tools. V1 cannot prevent this; file access is governed by the DSH sandbox and OS permissions. The design documents this as a deliberate boundary: the plugin is a context manager, not a policy enforcement point for the filesystem.
+
+---
+
+## 5. Rule template safety
+
+Controls:
+
+1. Interpolation only — no function calls, operators, conditionals or shell.
+2. No environment variable access unless a future ADR explicitly allows named variables.
+3. Undefined references are errors.
+4. Cyclic references are errors with the cycle path.
+5. Resolved paths are rejected if any segment is `..`.
+6. Resolved values are not executed, only returned.
+7. Template syntax is restricted to `${identifier(.identifier)*}` with a 2048-character
+   cap; anything else is `RULE_TEMPLATE_INVALID`.
+
+Threat: a malicious rule profile could point at sensitive directories to make the Agent read them later. Mitigation: the plugin never reads the resolved paths itself in V1; it only returns them. Future adapters that read paths must add their own path allowlist.
+
+---
+
+## 6. Data minimization and redaction
+
+Before emitting diagnostics, logs or P1 operation records:
+
+- Replace values matching common secret patterns: `password=`, `token=`, `Authorization:`, private key blocks, `kubeconfig` blocks.
+- Truncate command output and error text to a bounded length.
+- Keep only opaque evidence references, not raw evidence.
+
+The redaction function is shared and unit-tested.
+
+---
+
+## 7. Scope isolation
+
+- Registry data is profile-global and read-only for sessions.
+- Session default environment is per session; one session cannot change another's.
+- Tools accept explicit ids and do not implicitly broaden scope.
+- P1 memory queries always carry environment/service/deployment scope; a single-environment result must not be presented as a global rule.
+
+---
+
+## 8. Fail-safe behavior
+
+| Condition | Behavior |
+|---|---|
+| Two same-level bindings | `BINDING_CONFLICT`, no selection |
+| Skill missing or mismatched | `SKILL_UNAVAILABLE`, no fallback |
+| Skill registry unreachable | resolve with `available: 'unknown'` + warning |
+| Production without `allowProduction` | `POLICY_DENIED` |
+| Missing credential | `configured: false`, warning; operation still resolves |
+| Broken reference | error from `env_validate`, skipped on read |
+| Invalid record | skipped on read with diagnostic |
+| Approval denied | `POLICY_DENIED`, no write |
+| UI production write without `allowUiProductionWrites` | `POLICY_DENIED`, no write |
+| Missing transport header or foreign origin | `FORBIDDEN`, no routing |
+| Body over 2 MiB | 413, no parsing |
+| Record cap exceeded | `RECORD_LIMIT_EXCEEDED`, no write |
+
+---
+
+## 9. Audit
+
+V1 does not maintain an audit log of its own. P1 operation records become the audit trail through the memory bridge.
+
+Requirements for P1:
+
+- every write-class operation record includes `sessionId`, target ids, outcome and evidence refs;
+- summaries are redacted;
+- records are append-only from the plugin's perspective;
+- evidence retention is bounded.
+
+---
+
+## 10. Residual risks
+
+1. YAML editing outside the plugin bypasses approval.
+2. Credential reference swaps are undetectable without a vault policy.
+3. A correct Skill binding can still be used for an unsafe action; policy is necessary but not sufficient.
+4. Internal hostnames/IPs in registry files may leak if the repository or data directory is shared carelessly. Registry data must not be committed to Git.
+5. Operation history in P1 may capture sensitive command text if redaction is incomplete.
+6. The local HTTP route trusts the page origin and a custom header; a script running in
+   the DSH page (extension, devtools) can call it. It can read registry data the user
+   can already see, and write only as the `ui` actor under §4.2.
+7. `ctx.fs.watch` is not used in V1, so an external edit is picked up on the next
+   request rather than immediately; a stale resolve cannot outlive one request.

package/docs/01-architecture/storage-contract.md

@@ -0,0 +1,224 @@
+# Storage Contract
+
+Status: normative for V1.
+
+Durable registry data is a directory of YAML files. Nothing else is authoritative.
+
+Related: [data-model.md](./data-model.md), [design.md](./design.md) §5.
+
+---
+
+## 1. Location
+
+```text
+<dataDir>/
+├── environments/{environmentId}.yaml
+├── services/{serviceId}.yaml
+├── deployments/{deploymentId}.yaml
+├── rules/{ruleProfileId}.yaml
+├── operations/{bindingId}.yaml
+├── sessions/{sessionId}.json
+└── .backups/
+```
+
+### 1.1 Resolving `dataDir`
+
+Precedence:
+
+1. Plugin config `dataDir`, when set (absolute path or path relative to the profile directory).
+2. `profileContext.dir` → `<dir>/data/dsh-env-manager`.
+3. `$DSH_PROFILE_DIR/data/dsh-env-manager`.
+4. `<working directory>/data/dsh-env-manager` as a last resort for development only.
+
+The chosen path is memoized, reported once at startup, and shown in the UI overview. It
+is never derived from model input. Resolution order and fallbacks are implemented in
+`src/storage/paths.ts` (detailed-design §4.1).
+
+### 1.2 Creation
+
+- The directory tree is created on first use.
+- A missing directory is not an error; an unwritable directory is an error with `STORAGE_UNWRITABLE`.
+
+---
+
+## 2. File rules
+
+| Rule | Value |
+|---|---|
+| Encoding | UTF-8, no BOM |
+| Line endings | LF on write; CRLF tolerated on read |
+| Format | YAML 1.2 |
+| Extension | `.yaml` for records, `.json` for session state |
+| Name | `{id}.yaml`, where `id` matches `^[a-z0-9][a-z0-9-]{0,62}$` |
+| Extra files | Ignored unless they match the extension; ignored files are not deleted |
+
+A record file whose `id` differs from its filename is reported by `env_validate` and treated as invalid on load.
+
+---
+
+## 3. Record envelope
+
+Every record carries:
+
+```yaml
+id: string
+schemaVersion: 1
+createdAt: 2026-11-01T03:00:00.000Z
+updatedAt: 2026-11-01T03:00:00.000Z
+```
+
+- `createdAt` is set by storage on create.
+- `updatedAt` is set by storage on every successful write.
+- A write input may include both fields; storage overrides them. `createdAt` is
+  preserved from the existing file on update, so a caller cannot rewrite history.
+- The stored record always contains both fields.
+
+---
+
+## 4. Atomic write protocol
+
+```text
+1. Serialize the record to YAML.
+2. Validate the serialized document by parsing it back and running schema validation.
+3. Open `.${id}.${pid}.${randomUUID()}.tmp` in the target directory.
+4. Write UTF-8, fsync, close.
+5. Copy the previous file into `.backups/<kind>/<id>/<timestamp>.yaml`, prune to 5.
+6. Rename over the target (atomic on the same volume).
+7. On a caught failure before rename, delete the temp file and leave the target intact.
+```
+
+Constraints:
+
+- Never write directly to the target file.
+- Never leave a temp file behind on success or on a caught failure. A crash can leave
+  one; startup removes `*.tmp` older than one hour.
+- A backup failure does not fail the write; it is reported as a warning.
+- Never delete a record file that failed to parse; surface a diagnostic instead.
+- Storage does not reload the registry; the application layer does after a successful
+  write.
+
+---
+
+## 5. Read behavior
+
+```text
+1. Enumerate `*.yaml` in the directory.
+2. Parse each file.
+3. Schema-validate.
+4. On parse error: record `RECORD_INVALID` diagnostic, skip the file.
+5. On unknown schemaVersion: record `SCHEMA_UNSUPPORTED` warning, skip the file.
+6. Build an in-memory map keyed by id.
+```
+
+Reads never modify files. A failed file stays on disk for the user to fix.
+
+If a directory is unreadable, the loader returns an empty map plus an error diagnostic; tools still serve whatever other directories loaded.
+
+---
+
+## 6. Registry lifecycle
+
+- V1 loads the registry at the start of every application request.
+- Concurrent requests share one in-flight load.
+- A successful write triggers a reload before the request returns.
+- The registry is an in-memory snapshot; it is never persisted.
+- V1 has no index files and no watcher. A scan of a few hundred small YAML files is
+  fast enough; an mtime-keyed cache is added only with measured need.
+
+---
+
+## 7. Session state
+
+```text
+sessions/{sessionId}.json
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "sessionId": "session-abc",
+  "defaultEnvironmentId": "test-a",
+  "updatedAt": "2026-11-01T03:00:00.000Z"
+}
+```
+
+Rules:
+
+- Written atomically with the same protocol as records.
+- A missing file means "no default".
+- A corrupt file is treated as "no default" and reported as `persisted: false`; it is
+  not deleted, so the user can inspect it.
+- A process-local cache mirrors the last value so a failed write still works until
+  restart (detailed-design §9).
+- Session files are not registry records and are never scanned into the registry.
+- V1 uses this file store; a projection over the durable session log is a later
+  refinement (detailed-design §9).
+
+---
+
+## 8. Referential integrity
+
+Storage itself does not enforce cross-record references; the registry does, on load and on write:
+
+- Broken references are reported by `env_validate`.
+- On load, an invalid reference produces a warning; the record stays usable for name lookups.
+- On write, an invalid reference is rejected (`RECORD_INVALID` with details).
+
+This split keeps a single bad file from making the whole registry unusable.
+
+---
+
+## 9. Backups
+
+V1 keeps one rolling backup per write:
+
+```text
+.backups/{kind}/{id}/{timestamp}.yaml
+```
+
+- At most 5 backups per record; older ones are pruned.
+- Backups are best-effort: a backup failure does not fail the write, but emits a warning.
+- Backups are not a history feature. They exist to recover from an accidental overwrite.
+
+---
+
+## 10. Migration
+
+- `schemaVersion` gates compatibility.
+- V1 accepts only `1`.
+- A future migration must:
+  1. read old files,
+  2. write new files atomically,
+  3. keep a backup,
+  4. report counts,
+  5. never delete the old file until the new one is verified.
+
+V1 implements no migration.
+
+---
+
+## 11. What must never be stored
+
+- Passwords, tokens, private keys, kubeconfigs.
+- Raw command output or logs.
+- Copy of credential values.
+- Session conversation content.
+
+A violation found in validation is reported as `RECORD_INVALID` with the field path but without echoing the value.
+
+---
+
+## 12. Concurrency
+
+- Writers are serialized in-process; the plugin is one Host process per profile.
+- Multi-process writers are last-write-wins; no file locks in V1.
+- Readers never block writers.
+- A write that fails validation leaves the previous file untouched.
+
+---
+
+## 13. Repository hygiene
+
+- `data/` is git-ignored.
+- The repository ships no registry data, only schemas, examples in docs, and tests fixtures.
+- Test fixtures live under `tests/fixtures/` and contain no real hostnames, IPs or URLs.