opencode-secrets-obfuscation 0.1.0 → 0.1.1

package/docs/history/6-p0-infrastructure-review.md

@@ -1,275 +0,0 @@
-# P0 infrastructure adversarial review
-
-Date: 2026-10-13
-Scope: `tests/support/run-directory.ts`, `child-process.ts`,
-`recording-endpoint.ts`; their unit tests; `tests/p0-native/*`; and the P0
-history documents. `qualification.ts` and runtime-pin work were intentionally
-excluded.
-
-## Verdict
-
-The support code is useful synthetic fixture infrastructure, but it is not yet
-a safe real-host harness. In particular, child-process teardown is not awaited,
-pre-cancellation still reaches `spawn`, Windows executable/source trust is not
-established, and cleanup is vulnerable to races. The native Windows fixture is
-correctly labelled partial in the history document, but one of its reparse
-tests does not exercise the advertised protection. No P0 native or real-host
-qualification claim is supported.
-
-## Must fix
-
-### 1. Child failures settle before the child exits (critical)
-
-`tests/support/child-process.ts:96-105` sets `settled = true`, calls
-`child.kill()`, and rejects immediately. The `close` handler at lines 132-138
-is consequently ignored. This applies to timeout, cancellation, startup
-timeout, output limit, and child error paths. The helper therefore does not
-provide the claimed “owned child has terminated” boundary; it also does not
-wait for stdout/stderr streams to close before discarding the private result.
-
-Reproduction: `node --test tests/unit/harness.test.ts` on the review Windows
-host failed the output-limit case during cleanup with:
-`EBUSY ... rmdir ...run-...`. The test had already received `OUTPUT_LIMIT`, but
-the direct Node child still held the run directory. This is a deterministic
-false pass opportunity: callers can proceed, remove the run directory, or
-launch another fixture while the failed child is still running. Fix by making
-failure enter a terminating state, perform bounded escalation, and reject only
-after the direct child's `close`/stream teardown (with a bounded cleanup
-failure code if it cannot be proven dead).
-
-### 2. “Pre-cancelled does not spawn” is not tested and is false
-
-`child-process.ts:66-75` calls `spawn` before `child-process.ts:106-110`
-checks `signal.aborted`. The test named
-`pre-cancelled child execution does not spawn` only checks the returned error
-(`tests/unit/harness.test.ts:89-107`); it has no spawn oracle. A pre-aborted
-signal therefore starts the executable and then kills it. A cancellation race
-after validation has the same issue. Check the signal before `spawn`, and test
-with a fixture that leaves an observable synthetic marker (or injected spawn
-adapter), not merely the error code.
-
-### 3. Direct-child kill is not a process-tree boundary
-
-The documented limitation in `docs/history/3-p0-harness-foundation.md:24-29`
-is honest, but it blocks the real-service P0 harness. `child-process.ts:102-104`
-only calls `child.kill()` on the returned PID. Descendants can survive,
-retain handles to the private directory, continue network activity, or outlive
-cleanup. There is no escalation if the direct child ignores the first signal,
-and no Windows Job Object / POSIX process-group ownership proof. The P0 exit
-gate requires owned-process cleanup; this helper cannot satisfy it until a
-platform-qualified tree boundary is added and tested, including descendants,
-timeouts, cancellation, and forced escalation.
-
-### 4. Executable trust is only an absolute-path check
-
-`child-process.ts:46-55` accepts any absolute executable. It does not resolve
-the final object, reject symlinks/reparse points, verify ownership/ACLs,
-validate the expected file identity/hash, or ensure the executable remains the
-same object through launch. An absolute path to a writable or replaced binary
-is not a trusted executable resolution. This is especially material because
-the child environment is otherwise deliberately minimal. The harness needs an
-explicit, pinned artifact identity and platform-appropriate opened-object or
-equivalent launch verification; otherwise a test can pass while running an
-unexpected executable.
-
-### 5. Run-directory privacy and cleanup have TOCTOU gaps
-
-On Windows, `run-directory.ts:48-64` removes inheritance and grants the
-current SID, but does not verify the complete ACL or remove pre-existing
-explicit broad/unknown ACEs. The check only requires one `(F)` line and no
-`(I)` line (`:59-60`). Thus an existing root with explicit broad access can be
-reported private. Children created later are not independently checked, and
-the unit suite does not inspect child ACLs (`harness.test.ts:10-22`).
-
-`run-directory.ts:124-127` validates the marker and then recursively walks by
-path. Between `assertOwned` and each `lstat/readdir/rmdir` (`:75-89`), an
-attacker or concurrent process can replace a directory with a junction,
-symlink, or mount/reparse object, or replace the marker/tree. `lstat` avoids
-following a link at the instant it runs but is not a race-free deletion
-boundary. Cleanup must use an owned directory handle / no-follow traversal (or
-an equivalent OS primitive), revalidate identity, and refuse unsafe races.
-
-The root itself is created or reused at `:91-95` and is not marker-owned;
-`mkdir(..., recursive: true)` plus chmod can operate on a caller-supplied
-existing path. The ownership contract is only for the run child, so this must
-be explicit in the API and documentation rather than treated as private-root
-proof.
-
-### 6. Native Windows reparse test disables its own protection
-
-In `tests/p0-native/windows-handle-loader.tests.ps1:30-35`, `OpenRelative`
-builds `options` with `0x00200000` (`FILE_OPEN_REPARSE_POINT`) and then passes
-`options & ~0x00200000` to `NtCreateFile`. `OBJECT_ATTRIBUTES.Attributes`
-contains only `OBJ_CASE_INSENSITIVE` at line 32; `OBJ_DONT_REPARSE` is declared
-but never used. Consequently the fixture does not prove that component opens
-reject reparse points. The history claim at
-`docs/history/4-p0-source-opening.md:23-27` overstates this specific evidence,
-even though the overall document correctly remains partial. Correct the native
-flags and add a setup-independent result that distinguishes unavailable link
-creation from a genuine rejection test.
-
-## Additional findings / false-pass risks
-
-- `child-process.ts:46-55` assumes typed options at runtime. `null`, missing
-  `args`/`allowedEnv`, non-string environment values, or non-array values can
-  throw `TypeError` or reach `spawn` instead of returning `INVALID_OPTIONS`.
-  Malformed-option tests are absent. Also, `Buffer.concat` at `:123`/`:130`
-  repeatedly copies all prior data; the byte check bounds retained data but not
-  transient allocation or chunk size.
-- The output-limit unit test (`harness.test.ts:52-69`) proves only an error
-  code. It does not prove process exit, descendant cleanup, no post-failure
-  output allocation, or that cleanup can safely run. Its current `EBUSY` is
-  evidence that the test itself exposes the lifecycle defect rather than a
-  qualification pass.
-- `recording-endpoint.ts:61-105` bounds request capture and clears pending
-  buffers on close, and the focused recording tests passed. However, the close
-  test (`recording-endpoint.test.ts:88-99`) asserts only zero public captures;
-  it does not independently prove that a request handler is no longer pending,
-  that all sockets are closed before `close()` resolves, or that a late
-  `data/end/close` event cannot repopulate capture state. Add a post-close
-  event/barrier assertion and a bounded close failure path. Invalid runtime
-  shapes such as `options = null`, `responses = null`, or non-string bodies
-  also produce incidental TypeErrors rather than the fixed diagnostic.
-- `recording-endpoint.ts:109` increments `rejected` for `clientError`, while
-  `attempted` is incremented only in the request handler (`:52`). Counts can
-  therefore describe different populations during malformed-client tests;
-  define the counter contract before using it as a zero-egress oracle.
-- The Windows native fixture uses `Remove-Item -Recurse -Force` in its finalizer
-  (`windows-handle-loader.tests.ps1:100`). This is acceptable for its exact
-  generated synthetic path only after the fixture has proved no handles remain,
-  but it is not a substitute for the production owned-tree cleanup boundary.
-
-## Tests and gate status
-
-- `node --test tests/unit/harness.test.ts tests/unit/recording-endpoint.test.ts`:
-  13 passed, 1 failed. The failed output-limit test ended in `EBUSY` during
-  run-directory cleanup, as described above.
-- `npm.cmd run check`: typecheck passed; the full test command had the two
-  known `qualification.ts` failures (malformed external evidence and accessor
-  handling), which are outside this review scope. The remaining suites include
-  26 TODO tests; TODO/scaffold passes are not security evidence.
-- The Windows native script was not rerun as part of this review. The prior
-  recorded result is deliberately partial with reparse and hard-link setup
-  gaps, and the flag defect above makes its reparse result non-qualifying.
-- No OpenCode host, user config, credential, shared service, or live endpoint
-  was accessed. Focused tests used only synthetic values and loopback/local
-  fixtures.
-
-## Remaining P0 blockers
-
-1. Pin and verify the runtime/artifacts (separate review work), then build a
-   real isolated host harness with private config/data/home and a qualified
-   process-tree boundary.
-2. Make cancellation, timeout, output overflow, and startup failure settle
-   only after owned process and stream teardown; test forced escalation and
-   descendants on each target OS.
-3. Establish trusted executable identity and race-safe private run-directory
-   creation/cleanup, including effective child ACL inheritance.
-4. Repair and rerun the Windows native spike, add the required Linux/ext4
-   spike, and test ACLs, ancestor replacement, swaps, links, filesystem
-   identity, and post-read identity/size consistency.
-5. Implement actual P0-BOOT/P0-HOOKS/P0-ABORT/quotas evidence. The inventory in
-   `tests/smoke/cases.json` is planned only; no real-host case is executable.
-6. Keep the release unqualified. A partial native fixture, unit harness pass,
-   or expected-gap/TODO result must not be converted into platform or security
-   qualification.
-
-## Re-review: P0-B/P0-C primitive repairs
-
-Date: 2026-10-13
-Scope: repaired run-directory/child-process helpers, their 8-test harness,
-the synthetic child fixture, and `tests/p0-native/*`. The host Job Object and
-environment-builder work was excluded, as were qualification and recording
-helpers.
-
-### Verification result
-
-- `node --test tests/unit/harness.test.ts`: **8 passed, 0 skipped**.
-- `npm.cmd exec -- tsc --noEmit --pretty false`: passed.
-- `pwsh -NoProfile -File tests/p0-native/windows-handle-loader.tests.ps1`:
-  returned the intentional partial result
-  `P0-C-WINDOWS: PARTIAL (NTFS/relative/identity/read/post-read/hardlink/junction-rejection=True; gaps=reparse-create-1314,junction-native-create-4392)`.
-  The nonzero exit is appropriate for the setup gaps. No user configuration,
-  credential, shared service, or non-generated path was accessed.
-
-### Prior findings verified repaired
-
-1. **Failure teardown:** `child-process.ts:166-181,220-230` now enters a
-   terminating state, stops accepting output, escalates after a grace period,
-   and rejects only after child/stdout/stderr close. The former Windows `EBUSY`
-   cleanup failure did not recur.
-2. **Pre-abort:** `child-process.ts:90-95,184-191` checks cancellation before
-   hashing/spawn. `harness.test.ts:102-114` uses the fixture marker and proves
-   no launch occurred.
-3. **Executable identity and malformed options:** runtime validation and a
-   caller-supplied SHA-256 are enforced at `child-process.ts:53-95`; the
-   mismatch and malformed-input cases are exercised at
-   `harness.test.ts:116-126`.
-4. **Output bounds:** output is counted before retention at
-   `child-process.ts:202-218`; the test now proves teardown completes before
-   cleanup (`harness.test.ts:80-89`). This bounds retained synthetic output,
-   not the stream chunk allocated by Node before the handler sees it.
-5. **Run-root safety:** existing roots are verified but not chmod/ACL-modified
-   (`run-directory.ts:118-128`). POSIX ancestor ownership/write checks and
-   Windows current-SID ACL inspection are present. Windows new-directory ACL
-   setup removes prior rules and adds the current SID with container/object
-   inheritance (`run-directory.ts:83-99`). Child verification is exposed and
-   tested (`harness.test.ts:27-36`).
-6. **Cleanup scope:** cleanup now refuses anything other than the exact
-   marker-only directory (`run-directory.ts:110-116`), including nested links;
-   it does not recursively delete arbitrary content. Marker replacement and
-   outside-file preservation are tested (`harness.test.ts:27-49,52-61`).
-7. **Native no-reparse/open checks:** `OpenRelative` now passes both
-   `OBJ_DONT_REPARSE` and `FILE_OPEN_REPARSE_POINT` and rejects a returned
-   reparse handle (`windows-handle-loader.tests.ps1:45-50`). The probe tests
-   handle identity, same-handle read, post-swap identity/read, hard-link count,
-   owner/DACL policy, broad inherited ACEs, and an actual junction rejection
-   when setup permits (`:121-185`).
-
-### Must-fix or gate blockers remaining
-
-- **P0-B is still direct-child only.** `child-process.ts:172-176` explicitly
-  signals only the PID returned by `spawn`; the comments correctly make no
-  tree claim. The excluded Job Object/process-group work must establish and
-  test descendant containment before this can launch a real service. The
-  `TEARDOWN_FAILED` timer proves only that this helper eventually refuses to
-  claim teardown, not that descendants are gone.
-- **Hash-before-spawn is not race-proof.** `child-process.ts:79-87` uses
-  `lstat`/`readFile` and then launches by pathname. It is an adequate
-  synthetic artifact identity check and the history now says so, but a hostile
-  replacement between hashing and spawn can run another file. A real-host gate
-  still needs an OS-qualified launch/open identity strategy or trusted artifact
-  boundary. The hash read itself is also not size-bounded before allocation;
-  production artifact validation should impose a size limit or streaming
-  policy.
-- **Cleanup is intentionally not race-free.** The marker-only check followed
-  by `rm(marker)`/`rmdir(path)` (`run-directory.ts:110-116`) narrows damage and
-  refuses unexpected content, but it is path-based. A hostile concurrent
-  replacement can race the checks. This is acceptable as a synthetic fixture
-  primitive with an explicit limitation, not as private real-host evidence;
-  real qualification still needs handle-relative/no-follow cleanup or an
-  equivalent owned OS boundary.
-- **Windows ACL evidence is shape-limited.** The helper requires exactly one
-  current-SID rule for its private run directories (`run-directory.ts:70-80`),
-  and the source probe’s native policy covers the tested current SID,
-  SYSTEM/Administrators, unknown/broad/deny ACE, owner, and replacement-mask
-  shapes. It does not establish all effective-token/group/ACE/reparse-tag
-  combinations. The source probe’s `OpenDirectory` remains path-based for the
-  fixture root and uses share-write/delete; this is not a production
-  race-free source loader.
-- **P0-C remains Windows partial.** The successful junction fallback is useful
-  evidence of actual ancestor rejection, but native symlink creation (1314)
-  and native junction creation (4392) were unavailable on this worker. Linux
-  ext4, concurrent ACL changes, final size consistency under mutation, and
-  alternate reparse tags remain untested. No platform qualification follows.
-
-### Scope conclusion
-
-The repaired code now provides credible bounded **synthetic test primitives**
-for the previously failing direct-child lifecycle, pre-cancellation,
-artifact-hash, private-directory setup, cleanup refusal, and Windows handle
-policy cases. It must not be described as hostile real-host isolation,
-process-tree cleanup, race-free executable launch, race-free cleanup, or
-Windows/Linux source-loader qualification. P0-B/P0-C release gates therefore
-remain open pending the excluded host process boundary plus the native/runtime
-and Linux evidence listed above.

package/docs/history/7-p0-job-containment.md

@@ -1,29 +0,0 @@
-# P0 job containment
-
-The Windows-only test harness now has a native Job Object supervisor in
-`tests/p0-host/windows-job.ps1`. It uses `CreateProcessW(CREATE_SUSPENDED)`, assigns
-the process before `ResumeThread`, sets `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` and
-`JOB_OBJECT_LIMIT_PROCESS_MEMORY`, and records bounded output privately. Assignment
-failure terminates the still-suspended process and never resumes it.
-
-`tests/integration/windows-job.test.ts` uses only explicit executables and an owned
-request root. It covers exact argv backslashes/spaces, descendant timeout cleanup,
-assignment failure before resume, output overflow termination, an empty native
-environment, and supervisor cancellation. Node's synthetic fixture creates a
-grandchild and runs only with private test directories plus essential OS variables;
-no user profile, application-data, PATH, or credential values are copied.
-
-This is a Windows infrastructure prerequisite, not an OpenCode smoke test or a
-qualification result; Linux/macOS have no equivalent qualification.
-
-The current Windows ARM64 worker rejects the mandatory atomic job-list launch
-with `ERROR_INVALID_PARAMETER` (87), so it is explicitly blocked rather than
-using the weaker assign-after-create fallback. Windows x64 qualification remains
-pending on a worker supporting `PROC_THREAD_ATTRIBUTE_JOB_LIST`.
-
-The ARM64 integration case executes the supervisor and records
-`platformBlocked: true` only when its stderr contains
-`ATOMIC_JOB_LIST_UNSUPPORTED` and the supervisor exits nonzero. It also asserts
-that no child PID was created. This is a passing infrastructure observation,
-not a skipped case or a qualification result; any other supervisor failure, or
-any child creation on the blocked path, still fails the suite.

package/docs/history/8-p0-evidence-support.md

@@ -1,52 +0,0 @@
-# P0 evidence-support implementation
-
-Date: 2026-10-13. Scope: **test infrastructure only**, not product code or a P0
-exit-gate pass.
-
-## Implemented
-
-- `tests/support/qualification.ts`: bounded plain-data validation and selected-case
-  evidence assessment. Rejects missing, duplicate, unexpected, TODO/skipped,
-  stale-build/run and mismatched-profile evidence. Expected gaps require an explicit
-  active-only expectation and never satisfy an enforced profile.
-- `tests/support/recording-endpoint.ts`: scripted loopback HTTP fixture with bounded
-  request captures, request/connection counters, deadlines and explicit socket/buffer
-  cleanup. Supports JSON/SSE response content types for later protocol fixtures but
-  is not itself a model protocol implementation.
-
-## Test-first and independent review evidence
-
-Initial behavior tests were written before either helper existed and failed with
-missing-module errors. After implementation, the qualification suite passed 13
-cases and the recording suite passed 6, later 8 cases.
-
-Fresh-eye reviews in [review 5](5-qualification-gate-review.md) and
-[review 6](6-p0-infrastructure-review.md) required runtime-shape validation,
-accessor rejection and stronger close/counter semantics. Added regression tests
-failed against the previous implementations before repairs. The repaired focused
-command passes **24 tests** (15 evidence assessor, 9 recording endpoint):
-
-```sh
-node --test tests/unit/qualification.test.ts tests/unit/recording-endpoint.test.ts
-```
-
-The reviewer independently reran those 24 tests and found no new must-fix bug in
-these two helpers. Earlier full-suite/typecheck failures in review reports include
-parallel in-progress files and are preserved as historical observations, not a
-claim that those files remain broken.
-
-## Boundaries still open
-
-- Evidence assessment does not establish actual execution, correct/complete case
-  selection, artifact provenance/checksums, capture ownership or independent oracle
-  truth. The real smoke runner must supply and validate those before qualification.
-- The recorder is synthetic, unauthenticated loopback HTTP. It neither validates
-  GitHub TLS/address policy nor blocks unrelated outbound network traffic.
-- `attempted` counts parsed HTTP requests; `connections` counts accepted sockets
-  and `malformed` is separate. Zero parsed requests is not zero network attempts.
-- Explicit per-instance recorder bounds allow up to 64 MiB of captured body data
-  at the maximum settings, plus copies/overhead. A future combined real-host
-  harness must reserve aggregate budgets; these local limits are not a process RSS
-  guarantee. Captures remain private in memory and are never printed by helpers.
-- No product module or OpenCode service was launched by these tests. Runtime,
-  source-opening and process-tree prerequisites remain independent P0 gates.

package/docs/history/9-p0-launch-plan.md

@@ -1,88 +0,0 @@
-# P0-BOOT launch plan (not yet executable)
-
-Status: prepared; launch is intentionally blocked until the process-containment
-agent completes its review. This plan owns no host process and reads no user
-configuration.
-
-## Candidate identity
-
-Use the architecture-matching explicit unqualified candidate in
-`tests/smoke/runtime-candidate.json`: OpenCode `2.0.28`, official tag commit
-`026b106bc5d41b679ffc413264229c340871e4d3`. On this ARM64 runner the selected
-member is `@opencode/cli-windows-arm64@2.0.28`, PE machine `AA64`, executable
-member SHA-256
-`65F0E7ACCC7D5FD77CA7380FDE87E3289D0CF27687851E5240BBDE6CAA7BDB66`.
-The x64 candidate remains recorded for a matching worker. Each downloaded
-archive SHA-256 is distinct and must not be used as the executable hash.
-
-## Source-verified launch contract
-
-At tag `v2.0.28`, `packages/cli/src/server-process.ts` supports foreground
-`serve` with `--hostname` and `--port`; `packages/cli/src/services/standalone.ts`
-uses `serve --stdio --port 0` and emits one JSON readiness line
-`{"url":"..."}`. `serve` itself prints `server listening on ...` in foreground
-mode. The exact password variable is `OPENCODE_PASSWORD` (legacy
-`OPENCODE_SERVER_PASSWORD` is also accepted): `standalone.ts` creates a random
-password and passes it to the child as `OPENCODE_PASSWORD`. The client sends
-HTTP Basic authentication with username `opencode` and that password. The
-first probe must use the standalone stdio contract or an explicit foreground
-`serve` with a synthetic `OPENCODE_PASSWORD`, never shared-service discovery.
-
-The local API identity endpoint is authenticated `GET /api/info`, documented by
-the V2 API reference and defined by the tag's `packages/protocol/src/groups/server.ts`.
-Its `ServerInfo` schema requires `version: string`, `pid: nonnegative integer`,
-`urls: string[]`, and `paths.tmp: string`, with optional capabilities. The probe
-must decode this schema, assert version `2.0.28`, assert `pid >= 0`, require a
-run-owned URL and `paths.tmp` beneath the private root, and never print the
-password or raw response.
-
-## Environment construction
-
-`tests/support/opencode-environment.ts` is a pure builder. It accepts a private
-absolute run root and caller-supplied trusted OS values, and returns:
-
-* a fixture-owned cwd and data/cache/config/state/temp/database paths;
-* an explicit allowlist containing only OS runtime values and source-verified
-  OpenCode controls; and
-* synthetic JSON config with only supported fields: `snapshots: false`,
-  `warming: false`, and `update: "disable"`.
-
-After review 10, the builder requires an explicit `password` (64 lowercase hex
-characters). The future runner generates 32 CSPRNG bytes for each run and passes
-them only through the private environment/request channel, never user credentials
-or command-line arguments. `OPENCODE_PASSWORD` is in the fixed allowlist. The
-database choice is a run-owned file, not `:memory:`, so later sink evidence can be
-inspected. Candidate metadata now records the same database and auth controls.
-
-The builder never reads `process.env`. It omits provider keys, `NODE_OPTIONS`,
-proxy variables, plugin-path variables, credential-agent variables, and all
-other ambient values. The caller must supply any executable-required OS values
-explicitly. `OPENCODE_CONFIG_PROJECT_DISABLE=1` prevents the ancestor/project
-walk; `ProgramData` is redirected so system config discovery is also inside the
-fixture. `XDG_*`, `TEMP`/`TMP`, `OPENCODE_CONFIG_DIR`, `OPENCODE_CONFIG_CONTENT`,
-and `OPENCODE_DB` implement the tag-source isolation controls.
-
-## Next-agent execution sequence
-
-1. Wait for the containment decision and create an ACL-protected run root.
-2. Materialize only the exact candidate executable member, verify regular-file,
-   non-link, single-link identity and the corrected SHA-256 before spawn.
-3. Build the environment using the pure builder and pass it to the existing
-   child runner with `shell: false`, exact cwd, bounded stdout/stderr, startup
-   and overall deadlines, and owned-process containment.
-4. Start the exact foreground/stdio command selected by the containment agent.
-   Do not use `opencode`, `service`, `api`, or any installed executable by name.
-5. Parse only the bounded readiness line, call authenticated `GET /api/info`,
-   assert candidate identity, then stop the owned process through the approved
-   containment mechanism. Any mismatch, shared-service signal, unexpected
-   filesystem path, inherited variable, timeout, or unauthenticated endpoint
-   is a hard failure.
-6. Preserve raw evidence only under the private run root; publish case ID,
-   safe status, and validated identity fields.
-
-This document is a launch prerequisite, not P0 evidence. No host startup or
-real smoke pass is claimed until the sequence is implemented and executed.
-
-Parent added red/green malformed-input, accessor, cross-platform separator and
-mandatory-auth regressions after initial implementation. The six environment
-tests exercise only pure construction/validation, not filesystem or host isolation.

package/docs/spec/design.md

@@ -1,111 +0,0 @@
-# Design: transparent OpenCode V2 substitution MVP
-
-Status: authoritative implementation design, revised 2026-10-16.
-
-## Architecture
-
-```text
-configured dotenv source
-        |
-        v
-private activation map: raw value -> secret-UUID handle
-        |
-        +--> session/model/http/tool hooks --> sanitized existing host objects
-```
-
-There is no tool transform, capability registry, credential executor, private
-HTTP transport, or network request owned by this plugin.
-
-## Activation lifecycle
-
-The Effect activation loads sources and admits a complete snapshot before hooks
-can publish substitutions. The map and matcher state belong to that activation
-closure. Activation close disposes the map and matcher state. No raw values are
-stored in OpenCode storage, project metadata, logs, environment variables or
-spills created by the plugin.
-
-The current implementation uses a bounded in-memory map and a CSPRNG-generated
-UUIDv4-shaped handle. Handles are obfuscation identities only; there is no
-reverse-resolution API exposed to the host or model.
-
-## Source contract
-
-MVP sources are explicit Location-relative dotenv files with an allowlisted key
-set. No shell sourcing, interpolation, environment indirection or arbitrary
-path is allowed. A required source failure, unsafe value, admission collision,
-or budget failure disables substitution rather than publishing a partial map.
-
-The path-opening implementation and filesystem security claims remain a
-qualification gate. Until each platform is tested, the release must name only
-the supported platform/filesystem.
-
-## Substitution algorithm
-
-For each admitted raw value, construct the finite supported representation set
-(semantic text, dotenv spellings, JSON escaping, percent encoding and base64
-forms). Scan host values with bounded interval collection, replace matches with
-the corresponding opaque handle, and rescan the complete output. Overlaps are
-unioned before replacement. If the result cannot be bounded or validated,
-withhold the affected sink instead of returning raw input.
-
-The replacement is applied to exact host objects before publication. For
-serialized provider payloads, the implementation must preserve valid protocol
-shape and validate the final encoded bytes; leaf-only scans are insufficient.
-
-## Hook boundary
-
-The MVP wires these existing V2 surfaces:
-
-- `session.prompt`
-- `session.context`
-- `session.compaction`
-- `session.generate`
-- `session.title`
-- `session.model.request`
-- `session.http.request`
-- `session.http.response`
-- `tool.execute.before`
-- `tool.execute.after`
-
-A hook only proves the boundary it actually observes. It cannot retroactively
-protect values emitted before the hook, internal writes by ordinary tools,
-provider-hosted tools, WebSocket/SDK routes, or host behavior after unload.
-Those are recorded as uncovered or deferred, never silently considered safe.
-
-## Configuration
-
-```json
-{
-  "version": 1,
-  "sources": [
-    {
-      "id": "project",
-      "type": "file",
-      "format": "dotenv",
-      "path": ".env",
-      "required": true,
-      "keys": ["EXAMPLE_TOKEN"]
-    }
-  ],
-  "limits": { "...": "all bounded limit keys are required" }
-}
-```
-
-No authorization, capabilities, operation IDs, resource URLs, tool names or
-transport endpoints belong in the MVP options.
-
-## Explicit non-goals
-
-- no model-visible credential tools;
-- no plugin-owned requests;
-- no GitHub-specific behavior;
-- no DNS/proxy/egress policy for requests the plugin does not make;
-- no universal protection claim against an untrusted or compromised host.
-
-## E2E proof
-
-`P5-TRANSPARENT-ROUNDTRIP` runs a real OpenCode 2.0.28 subprocess with a
-synthetic dotenv source and a loopback provider. It verifies existing provider
-traffic contains an opaque `secret-<uuid>` replacement and not the raw canary,
-while the plugin makes no independent request. Additional sink cases are
-required before release qualification.

package/docs/spec/intent.md

@@ -1,81 +0,0 @@
-# Intent: transparent OpenCode V2 secret substitution
-
-Status: authoritative product intent, revised 2026-10-16.
-
-## Problem
-
-Project-local configuration may contain credentials that must not appear in
-OpenCode prompts, model requests, tool-visible values, errors, logs, or durable
-host payloads. The plugin should protect those values **behind the scenes**;
-the model and ordinary OpenCode tools should continue using their existing
-interfaces.
-
-## MVP product boundary
-
-The plugin is a native OpenCode V2 Effect plugin that:
-
-1. Loads explicitly configured dotenv values into private activation memory.
-2. Assigns each admitted value an opaque `secret-<UUIDv4>` replacement.
-3. Applies the replacement through existing OpenCode session/model/http/tool
-   hooks before public or provider-facing publication.
-4. Withholds or fails closed when a bounded sink cannot be safely transformed.
-5. Disposes the private map when the plugin activation closes.
-
-The plugin **does not**:
-
-- register tools or change tool schemas;
-- expose a credential catalog to the model;
-- resolve handles for a private operation;
-- perform credential, GitHub, or other plugin-owned network requests;
-- implement authorization for an operation it owns;
-- claim protection for host routes that its hooks do not observe.
-
-## What the model sees
-
-Where a configured value would otherwise appear, the public value is an opaque
-handle such as `secret-550e8400-e29b-41d4-a716-446655440000`. The raw value
-never enters model-visible arguments or provider request bodies through a
-qualified path. Handles are references for obfuscation only; this MVP does not
-resolve them.
-
-## MVP configuration
-
-Options contain only:
-
-- `version: 1`;
-- relative, explicitly keyed dotenv `sources`;
-- bounded `limits` for source size, traversal, output and working memory.
-
-Paths must remain inside the OpenCode Location. `${env:...}` and `${file:...}`
-indirections are rejected. Values are synthetic in tests and never persisted by
-the plugin.
-
-## Supported boundary
-
-The first qualified boundary is the existing provider request path plus the
-session hooks for prompt, context, compaction, generate and title, and tool
-before/after results. Each sink requires its own evidence. Ordinary shell,
-MCP, provider-hosted tools, WebSocket/SDK routes, screenshots, transformed or
-covert values, and host behavior after plugin unload are not automatically
-protected.
-
-## Security posture
-
-This is an **active-plugin-only** MVP. It trusts the OpenCode host, process,
-OS account and plugin ordering. It does not claim protection against a
-compromised host, a malicious same-process plugin, or an unobserved route.
-Broad production enforcement is a later profile requiring host-owned readiness
-and route mediation; it is not part of this plugin's MVP.
-
-## E2E acceptance
-
-`P5-TRANSPARENT-ROUNDTRIP` launches pinned OpenCode V2 in a private sandbox,
-loads a synthetic `.env`, sends one normal `opencode run` prompt through a
-loopback provider, and proves:
-
-- the existing provider path completes normally;
-- provider bytes contain an opaque handle instead of the raw canary;
-- public output and sandbox host data contain no raw canary;
-- no plugin-owned tool or network request occurs.
-
-This is a first E2E boundary, not exhaustive qualification.