@bjorntech/key-ferry 0.0.0-stage → 0.1.0

package/dist/varlock/protocol.js

@@ -0,0 +1,248 @@
+/** Pure validation for the Varlock proxy CLI protocol.
+ *
+ * This module deliberately does not know about process.env, subprocesses, or
+ * Effect.  Treat every value passed to it as hostile CLI output.  In
+ * particular, a session record is not a proof of ownership until the caller
+ * supplies the PID, UUID, and project directory it created.
+ */
+export const PROTOCOL_LIMITS = {
+    jsonBytes: 2 * 1024 * 1024,
+    sessions: 128,
+    mapEntries: 512,
+    stringBytes: 16 * 1024,
+    envKeyLength: 256,
+};
+const SAFE_ENV_KEYS = new Set([
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "all_proxy",
+    "NO_PROXY",
+    "no_proxy",
+    "NODE_EXTRA_CA_CERTS",
+    "SSL_CERT_FILE",
+    "REQUESTS_CA_BUNDLE",
+    "CURL_CA_BUNDLE",
+    "GIT_SSL_CAINFO",
+    "CARGO_HTTP_CAINFO",
+    "DENO_CERT",
+    "NODE_USE_ENV_PROXY",
+]);
+const PROXY_KEYS = [
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "all_proxy",
+];
+export class VarlockProtocolError extends Error {
+    code = "protocol_error";
+    constructor(message = "invalid Varlock protocol response") {
+        // Never interpolate CLI output into this message.  Callers can safely
+        // expose it in diagnostics and model-visible errors.
+        super(message);
+        this.name = "VarlockProtocolError";
+    }
+}
+function fail(message) {
+    throw new VarlockProtocolError(message);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function boundedString(value, field, max = PROTOCOL_LIMITS.stringBytes) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > max ||
+        value.includes("\0")) {
+        fail(`invalid Varlock ${field}`);
+    }
+    return value;
+}
+function boundedMap(value, field) {
+    if (!isRecord(value) || Object.keys(value).length > PROTOCOL_LIMITS.mapEntries)
+        fail(`invalid Varlock ${field}`);
+    const result = Object.create(null);
+    for (const key of Object.keys(value)) {
+        if (key === "__proto__" ||
+            key === "prototype" ||
+            key === "constructor" ||
+            key.length === 0 ||
+            key.length > PROTOCOL_LIMITS.envKeyLength ||
+            !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            fail(`invalid Varlock ${field}`);
+        }
+        result[key] = boundedString(value[key], `${field} value`);
+    }
+    return result;
+}
+function parseJson(input) {
+    if (typeof input !== "string" ||
+        new TextEncoder().encode(input).byteLength > PROTOCOL_LIMITS.jsonBytes) {
+        fail("invalid Varlock JSON payload");
+    }
+    try {
+        return JSON.parse(input);
+    }
+    catch {
+        fail("invalid Varlock JSON payload");
+    }
+}
+function decodeSession(value) {
+    if (!isRecord(value))
+        fail("invalid Varlock session record");
+    const egressMode = value.egressMode;
+    if (egressMode !== "permissive" && egressMode !== "strict")
+        fail("invalid Varlock egress mode");
+    if (!Number.isSafeInteger(value.ownerPid) || value.ownerPid <= 0)
+        fail("invalid Varlock owner PID");
+    const session = {
+        id: boundedString(value.id, "session id", 128),
+        uuid: boundedString(value.uuid, "session UUID", 128),
+        ownerPid: value.ownerPid,
+        cwd: boundedString(value.cwd, "session cwd"),
+        startedAt: boundedString(value.startedAt, "session start time", 128),
+        updatedAt: boundedString(value.updatedAt, "session update time", 128),
+        ...(value.endedAt !== undefined
+            ? { endedAt: boundedString(value.endedAt, "session end time", 128) }
+            : {}),
+        egressMode,
+        env: boundedMap(value.env, "session environment"),
+    };
+    if (value.placeholderOverrides !== undefined) {
+        session.placeholderOverrides =
+            boundedMap(value.placeholderOverrides, "placeholder overrides");
+    }
+    return session;
+}
+/** Decode only the JSON array emitted by `varlock proxy status --format json`. */
+export function decodeSessionList(input) {
+    const value = parseJson(input);
+    if (!Array.isArray(value) || value.length > PROTOCOL_LIMITS.sessions)
+        fail("invalid Varlock session list");
+    return value.map(decodeSession);
+}
+/** Exact ownership match. No cwd-prefix or PID-only matching is accepted. */
+export function findOwnedSession(sessions, identity) {
+    const directory = boundedString(identity.projectDirectory, "project directory");
+    if (!Number.isSafeInteger(identity.ownerPid) || identity.ownerPid <= 0)
+        fail("invalid owner PID");
+    const uuid = boundedString(identity.sessionUuid, "session UUID", 128);
+    return sessions.find((session) => session.ownerPid === identity.ownerPid &&
+        session.uuid === uuid &&
+        session.cwd === directory &&
+        session.endedAt === undefined);
+}
+function validateProxyUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        fail("invalid Varlock proxy URL");
+    }
+    if (url.protocol !== "http:" ||
+        (url.hostname !== "127.0.0.1" &&
+            url.hostname !== "localhost" &&
+            url.hostname !== "[::1]" &&
+            url.hostname !== "::1")) {
+        fail("Varlock proxy must use a loopback HTTP URL");
+    }
+    if (url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        (url.pathname !== "/" && url.pathname !== "")) {
+        fail("invalid Varlock proxy URL");
+    }
+    const port = Number(url.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        fail("invalid Varlock proxy port");
+    return url;
+}
+/** Validate wiring without returning credentials or writing ambient env state. */
+export function validateProxyWiring(env) {
+    const keys = Object.keys(env);
+    if (keys.length > PROTOCOL_LIMITS.mapEntries ||
+        keys.some((key) => key === "__proto__" ||
+            key === "prototype" ||
+            key === "constructor" ||
+            key.length > PROTOCOL_LIMITS.envKeyLength ||
+            !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)))
+        fail("invalid Varlock proxy environment");
+    const https = env.HTTPS_PROXY ?? env.https_proxy;
+    const http = env.HTTP_PROXY ?? env.http_proxy;
+    if (!https || !http)
+        fail("Varlock proxy environment is incomplete");
+    const proxyUrl = validateProxyUrl(https);
+    if (validateProxyUrl(http).origin !== proxyUrl.origin)
+        fail("Varlock proxy URLs do not match");
+    for (const key of PROXY_KEYS) {
+        if (env[key] !== undefined && validateProxyUrl(env[key]).origin !== proxyUrl.origin)
+            fail("Varlock proxy URLs do not match");
+    }
+    const caPath = env.NODE_EXTRA_CA_CERTS;
+    if (!caPath ||
+        !caPath.startsWith("/") ||
+        caPath.length > PROTOCOL_LIMITS.stringBytes ||
+        caPath.endsWith("/")) {
+        fail("invalid Varlock CA certificate path");
+    }
+    if (caPath.split("/").includes("..") || caPath.split("/").includes("."))
+        fail("invalid Varlock CA certificate path");
+    if (!caPath.endsWith("/ca-cert.pem"))
+        fail("invalid Varlock CA certificate path");
+    // Session env contains the child view as well as wiring.  Return only the
+    // documented wiring allowlist, never arbitrary child keys or credentials.
+    const wiringEnv = Object.create(null);
+    for (const key of keys)
+        if (SAFE_ENV_KEYS.has(key))
+            wiringEnv[key] = env[key];
+    return { proxyUrl: proxyUrl.origin, caPath, env: wiringEnv };
+}
+/**
+ * Select explicitly requested child keys. A key is safe only when the session
+ * record has an exact placeholder assignment and the full env contains that
+ * exact placeholder. Prefixes are intentionally not trusted. Keys absent from
+ * placeholderOverrides (including @proxy=passthrough values) are rejected.
+ */
+export function selectPlaceholderEnvironment(fullEnv, session, requestedKeys) {
+    if (!Array.isArray(requestedKeys) || requestedKeys.length > PROTOCOL_LIMITS.mapEntries)
+        fail("invalid requested Varlock keys");
+    const overrides = session.placeholderOverrides;
+    if (!overrides)
+        fail("Varlock session has no placeholder assignments");
+    const selected = Object.create(null);
+    const seen = new Set();
+    for (const key of requestedKeys) {
+        if (seen.has(key))
+            fail("duplicate requested Varlock key");
+        seen.add(key);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || key.length > PROTOCOL_LIMITS.envKeyLength)
+            fail("invalid requested Varlock key");
+        const placeholder = overrides[key];
+        if (placeholder === undefined || fullEnv[key] !== placeholder)
+            fail("requested key is not proven to be placeholder-backed");
+        selected[key] = placeholder;
+    }
+    return selected;
+}
+/** Safe status allowlist; deliberately drops tokens, env maps, and placeholders. */
+export function sanitizeSessionStatus(session, running) {
+    const wiring = validateProxyWiring(session.env);
+    return {
+        id: session.id,
+        uuid: session.uuid,
+        ownerPid: session.ownerPid,
+        cwd: session.cwd,
+        startedAt: session.startedAt,
+        updatedAt: session.updatedAt,
+        egressMode: session.egressMode,
+        proxyUrl: wiring.proxyUrl,
+        running,
+    };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/varlock/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/varlock/protocol.ts"],"names":[],"mappings":"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"}

package/docs/architecture.md

@@ -0,0 +1,179 @@
+# OpenCode V2 and Varlock architecture
+
+## Runtime design
+
+The runtime is Effect-native. The installed OpenCode V2 plugin package
+exposes a separate native entrypoint, `@opencode/plugin/effect`, and its
+dependencies pin `effect` to **4.0.1**. The Promise API is not the foundation
+for this project and will not be wrapped superficially.
+
+Verified package facts from `@opencode/plugin@2.0.30`:
+
+```ts
+import { Plugin } from "@opencode/plugin/effect"
+
+export default Plugin.define({
+  id: "key-ferry",
+  effect: (ctx) => Effect.gen(function* () {
+    // Native Effect plugin setup.
+  }),
+})
+```
+
+The native plugin type is `effect(context): Effect.Effect<void, never, R>`.
+Native registrations and transforms return Effects, and registration disposal
+is also an Effect. `ctx.mcp.transform(...)` and `ctx.mcp.reload()` are native
+Effect APIs. See the V2 [plugin](https://opencode.ai/v2/docs/build/plugins),
+[RPC](https://opencode.ai/v2/docs/build/plugins/rpc), and
+[MCP](https://opencode.ai/v2/docs/mcp-servers) documentation.
+
+## Manager boundary
+
+`src/contracts.ts` defines the boundary for the sidecar manager and OpenCode
+adapter:
+
+- `ProjectKeyFerryManager` is an Effect `Context.Service` tag.
+- `ProjectKeyFerryManagerFactory.layer()` returns a typed `Layer`.
+- Sidecar acquisition belongs in a scoped layer using
+  `Effect.acquireRelease`.
+- The process must be owned by exact PID plus generated ownership/session ID.
+- No ambiguous daemon adoption and no global `stop --all` operation.
+- `ensureStarted`, `refresh`, and teardown must cooperate with interruption.
+- Lifecycle and refresh operations must be serialized internally, represented
+  by `withExclusive`.
+- `dispose` is idempotent and only stops resources owned by this manager.
+- Varlock's public CA material is handled as trust material with the required
+  public-readable `0644` permissions; it is not treated as a credential.
+
+The process service is injectable through the `VarlockProcess` Effect service,
+so sidecar behavior can be tested without spawning a real process.
+
+## Varlock constraints encoded by the contract
+
+- Never call the Varlock loader from the service if it mutates global
+  `process.env`.
+- The foreground proxy must be owned and started with project cwd, explicit
+  session, and reload support.
+- `--allow-reload` is mandatory for the owned proxy process.
+- Raw status data may contain endpoint tokens, data-plane tokens, environment
+  values, and placeholder overrides. It must remain inside the protocol
+  adapter.
+- Public `SafeStatus` contains only phase, project path, generation, optional
+  PID/endpoint metadata, timestamps, sanitized tagged errors, and safe
+  remote-configuration diagnostics.
+- `ResolvedEnvironment` is an internal capability only. It must not cross RPC,
+  CLI, logging, or model-context boundaries.
+- Never forward Varlock's complete `--full` environment map. It may contain
+  placeholders and raw `@proxy=passthrough` secrets. The protocol adapter must
+  enforce the later-approved placeholder-only allowlist.
+- Refresh must have a bounded timeout, account for the CLI's fifteen-minute
+  maximum, and fail closed when refresh fails.
+- Strict egress is required by default. The manager validates the schema's
+  exact `# @proxyConfig={egress="strict"}` header and does not invent an
+  unsupported `--allow-domain` flag.
+- Local MCP integration uses the supported environment proxy/CA path. It does
+  not pretend that a sandbox provides this isolation.
+
+## MCP integration
+
+The adapter has two explicit protection modes under `options.servers`.
+
+```ts
+type ServerProtection =
+  | { readonly env: readonly string[] | Readonly<Record<string, string>> }
+  | {
+      readonly remote: {
+        readonly headers: Readonly<Record<string, string | {
+          readonly env: string
+          readonly prefix?: string
+          readonly suffix?: string
+        }>>
+      }
+    }
+```
+
+Local mappings are injected into the selected local MCP process environment.
+Remote mappings are only accepted for a configured `type: "remote"` server
+with explicit `oauth: false`. A selected remote server with OAuth omitted or
+configured is disabled with a safe diagnostic. An unselected remote server is
+left to native OpenCode transport and OAuth handling.
+
+OpenCode V2 exposes `ctx.mcp.transform`, `ctx.mcp.reload`, and the mutable
+`Mcp.ServerConfig`, but no public per-server fetch, dispatcher, transport, or
+registry extension. Remote protection therefore uses a plugin-owned relay:
+
+```text
+OpenCode Streamable HTTP/SSE client
+        -> authenticated 127.0.0.1 relay
+        -> Varlock HTTP CONNECT proxy
+        -> fixed HTTPS MCP origin/path
+```
+
+The transformed MCP registry contains only the relay URL, the scoped relay
+capability, and safe non-credential headers. Mapped credential headers are
+constructed inside the relay from placeholder values. The persisted OpenCode
+configuration is never rewritten.
+
+The relay binds to loopback and uses a per-instance token. It forwards
+Streamable HTTP POST/GET/DELETE semantics, streams SSE, preserves MCP session
+headers, aborts upstream work on downstream cancellation, and rejects
+downstream paths that were not registered from the fixed upstream origin. Its
+legacy SSE endpoint rewrite is implemented. Registered session routes are
+capped at 256; duplicate routes do
+not consume capacity and new routes are rejected after the cap. The remote
+Varlock integration is covered by an opt-in synthetic HTTPS fixture.
+
+Relay TLS uses CONNECT followed by one verified `tls.connect` call with the
+manager CA, target `servername`, and `rejectUnauthorized: true`. The custom
+HTTP agent returns that verified TLS socket for HTTP framing. No global TLS
+flags are changed and no certificate verification is weakened. Compressed or
+oversized response framing is bounded and fails closed.
+
+Remote target validation requires HTTPS, rejects URL credentials and fragments,
+and rejects literal local/private IP targets by default. An explicit
+`allowPrivateNetwork` policy can opt into such targets. Corporate DNS names
+are not rejected merely because they may resolve to internal addresses. The
+relay never accepts an arbitrary downstream URL.
+
+Manager generation is part of relay ownership. On refresh, sidecar loss, or
+relay health failure, old relays are stopped, old local capabilities become
+invalid, MCP sessions are reset through `ctx.mcp.reload()`, and protected
+servers remain disabled until replacement succeeds.
+
+Doctor runs the normal Varlock readiness/environment reconciliation and then
+reconciles or recreates unhealthy selected `oauth:false` remote relays. It does
+not provide a credential prompt, replace native OAuth, or silently restore a
+direct remote connection.
+
+Verification uses native V2 types, mocks, package imports, and synthetic HTTPS
+remote transport. The normal suite and gated Varlock fixtures are separate
+verification layers; neither is a production certification or a fully live
+OpenCode host/TUI run.
+
+## Module ownership
+
+1. `src/contracts.ts`: Effect service tags, layers, scoped lifecycle,
+   sanitized errors, process seams, and safe/public versus internal types.
+2. `src/varlock/protocol.ts`: pure protocol parsing and placeholder allowlist
+   validation. Owned by the protocol track.
+3. `src/varlock/manager.ts`: project-scoped service implementation, serialized
+   state transitions, fail-closed readiness, refresh, and acquire/release.
+4. `src/plugin.ts`: native V2 plugin layer, local/remote MCP transforms, RPC,
+   relay lifecycle, and cleanup.
+5. `src/rpc.ts`: secret-free status and refresh RPC definitions.
+6. `src/options.ts`: validation of explicit project-scoped configuration.
+7. `src/tui.ts`: optional status/refresh UX over the RPC shape.
+8. `src/remote.ts`: adapter-side remote relay contract, target/header
+   validation, placeholder wiring, generation coordination, and safe
+   diagnostics.
+9. `src/relay/**`: standalone authenticated HTTP relay implementation.
+10. Process execution remains behind the injectable process service.
+
+The manager must be acquired before MCP/provider integrations are enabled and
+must be released after their registrations are disposed. A failed start or
+refresh leaves protected connections disabled rather than falling back to
+ambient environment variables.
+
+Cleanup is scope-owned and project-owned: it stops only the sidecar and relay
+resources acquired by this plugin instance. It does not perform a global
+Varlock shutdown and does not claim full sandbox isolation.

package/docs/quality.md

@@ -0,0 +1,102 @@
+# Quality checks
+
+This document describes the checks maintained in this repository. It is a
+maintainer reference, not a claim of production certification.
+
+## Typecheck, tests, and build
+
+Run the ordinary checks from the repository root:
+
+```sh
+bun typecheck
+bun test
+bun run build
+bun pm pack --dry-run
+```
+
+The normal test suite uses mocks and synthetic fixtures. The optional Varlock
+live fixtures are a separate integration layer: use the globally installed CLI
+(for example, Homebrew's `varlock`) or override it with an absolute
+`VARLOCK_LIVE_BINARY` path. They use synthetic strict-HTTPS credentials and do
+not require provider authentication, production network access, or committed
+secrets. See the live-fixture commands in the README.
+
+## Runtime-source coverage
+
+`bun run test:coverage` runs Bun's coverage output and then the repository's
+LCOV checker. The checker keeps only runtime sources under `src/`, including
+contracts and plugin code, and excludes generated code and test files. It
+computes global weighted totals from executable LCOV line records and function
+records; Bun's per-file thresholds are not used.
+
+The gate is:
+
+- lines: at least 90%
+- functions: at least 75%
+
+The check is a runtime-source gate, not a branch-coverage claim. Bun 1.4.2
+does not emit branch coverage in the coverage output used here. CI captures
+the LCOV and text report and uploads both on Ubuntu and macOS. The thresholds
+and source-selection rules are implemented in
+`scripts/check-coverage.ts`, so changes to the gate should update this
+document and that checker together.
+
+## Formatting
+
+Use:
+
+```sh
+bun run format
+bun run format:check
+```
+
+Both commands use Oxfmt 0.72.0 and the repository settings aligned with the
+Alchemy formatter configuration referenced by `oxfmt.config.ts`. The settings
+use double quotes, semicolons, 100-column lines, LF endings, trailing commas,
+and import sorting. Markdown and MDX are intentionally ignored by Oxfmt, as
+are generated and coverage directories. This document is therefore reviewed
+as Markdown rather than treated as Oxfmt-formatted source.
+
+## CRAP policy
+
+CRAP is a per-function quality gate alongside the aggregate runtime-source
+coverage gate; it is not a security guarantee. The standard per-function score
+is:
+
+```text
+CRAP = CC² × (1 − statement coverage)³ + CC
+```
+
+where `CC` is cyclomatic complexity and own statement coverage is bounded to
+0–1. Coverage is the ratio of covered executable statements owned by that
+function, not Istanbul's function-hit percentage. A function with `CC > 6`
+cannot pass the threshold of `6`, even at full coverage.
+
+Run the gate with:
+
+```sh
+bun run test:crap
+```
+
+The runner instruments a temporary mirror of the TypeScript runtime sources
+with Istanbul, executes that mirror with Bun, and writes the JSON report to
+`coverage/crap.json` in CI (`CRAP_JSON=1 bun run test:crap 2>&1 | tee
+coverage/crap.json`). Instrumentation is temporary and is not production
+instrumentation. Bun does not provide aggregate branch coverage here; this
+policy uses own-statement coverage only.
+
+`quality/crap-baseline.json` is a committed historical baseline generated from
+committed `HEAD`, separately from the working-tree metrics. Do not blindly
+regenerate it when the gate fails. A semantic AST fingerprint and qualified
+scope function identity are used, so formatting changes and source-line shifts
+do not reset identity.
+
+Unchanged legacy violations warn. New or modified functions with a score above
+6 fail. An unchanged function also fails if its score worsens from the
+baseline, even when its resulting score remains below 6. A quality run can
+therefore fail while changed functions are being refactored; existing legacy
+warnings do not mean that the whole repository has CRAP ≤ 6.
+
+The metric detects complexity and test-coverage regressions; it is not a
+security guarantee. Live fixtures and production integration remain separate
+verification work and are not established by this gate.