@bjorntech/key-ferry 0.0.0-stage → 0.1.0

package/docs/releasing.md

@@ -0,0 +1,149 @@
+# Release checklist
+
+This is a maintainer runbook. Nothing in this document performs a release,
+changes repository settings, creates a tag, pushes code, or publishes to npm.
+Do not put npm credentials or long-lived publish tokens in the repository or in
+chat.
+
+## One-time account and repository setup
+
+Complete these steps interactively, using an account that owns the
+`@bjorntech` scope and has publish permission. Verify the scope ownership,
+account/org access, and 2FA before continuing.
+
+1. Decide whether the repository should be public. npm provenance for this
+   package requires the public repository/package policy used by this project;
+   in GitHub, use **Settings → General → Danger Zone → Change visibility** and
+   make the repository public if that is the approved decision. This is a
+   manual decision, not an automated release step.
+2. Create the GitHub environment named exactly `production`. Configure its
+   required reviewers (do not enable self-review if that would defeat the
+   approval policy), and restrict deployments to the approved stable version
+   tag pattern (`v*`). Protect tag creation and `main` with the repository's
+   normal branch/ruleset policy.
+3. Push the release workflow and its supporting release scripts to `main`
+   before configuring npm Trusted Publishing. The fixed workflow filename is
+   `.github/workflows/publish.yml`.
+4. Bootstrap the package if it does not yet exist on npm. For the initial
+   `0.1.0` release, run the normal quality/build gates below, then use one
+   interactive browser/2FA login and publish from the repository:
+
+   ```sh
+   npm login
+   npm publish --access public
+   ```
+
+   Do not add `--provenance` to this local bootstrap publish. This initial
+   publication does not validate OIDC, and `0.1.0` must not be tagged and
+   published again after it already exists.
+5. Shortly before the next genuine release, configure npm Trusted Publishing
+   for the package at **Package settings → Trusted Publisher** with:
+   - provider: **GitHub Actions**
+   - organization/owner: `bjorntech`
+   - repository: `key-ferry`
+   - workflow filename: `publish.yml`
+   - environment: `production`
+
+   Use npm's current UI field names if they differ. A newly created,
+   unvalidated configuration expires after 48 hours without a successful
+   publish, so do not create a fake release merely to test it. Configure it
+   for the next real version (for example, `0.1.1`) after the bootstrap
+   package exists. See [npm Trusted Publishers](https://docs.npmjs.com/trusted-publishers/)
+   and the [npm trust command reference](https://docs.npmjs.com/cli/v12/commands/npm-trust).
+6. After the first successful OIDC release, consider enabling npm's **Require
+   two-factor authentication** and **Disallow tokens** package controls, and
+   lock down classic publishing as allowed by the account policy. Trusted
+   publishing uses the GitHub OIDC exchange; it does not require an
+   `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or another repository secret.
+
+## Quality gates
+
+From the repository root, run the normal gates before committing a release:
+
+```sh
+bun install --frozen-lockfile
+bun run format:check
+bun typecheck
+bun test
+bun run test:coverage
+bun run test:crap
+bun run build
+bun pm pack --dry-run
+```
+
+The coverage gate requires aggregate runtime-source coverage of at least 90%
+for lines and 75% for functions. The CRAP gate requires new or changed
+functions to score at most 6; unchanged legacy violations warn, while
+regressions against the committed baseline fail. Review the reports rather
+than hard-coding their current counts.
+
+Run the two opt-in Varlock fixtures separately with a configured CLI path and
+synthetic isolated fixtures:
+
+```sh
+VARLOCK_LIVE_BINARY=/absolute/path/to/varlock bun test tests/varlock-live.test.ts
+VARLOCK_LIVE_BINARY=/absolute/path/to/varlock bun test tests/remote-varlock-live.test.ts
+```
+
+These fixtures do not substitute for production deployment or compatibility
+testing with every external MCP service.
+
+## Release and tag flow
+
+1. Review the package version, changelog, exports, generated package contents,
+   public-scope permissions, repository visibility, and the complete release
+   diff. Set a new, genuine semver version; never retry a version that npm has
+   already accepted. Update the lockfile consistently and rerun all gates.
+2. Commit the reviewed source and workflow changes, push the selected branch,
+   and wait for the commit to be available on `main`.
+3. Create and push the matching stable tag only after explicit approval:
+
+   ```sh
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   ```
+
+   The tag must point at the reviewed release commit and its version must
+   match `package.json` exactly. Stable tags are the only automatic publish
+   trigger; the workflow does not publish from `main`.
+4. `.github/workflows/publish.yml` runs on GitHub-hosted Ubuntu with the
+   pinned Node 24.22/npm 12.2/Bun 1.4.2 toolchain and verified action SHA
+   pins. Its unprivileged `verify` job has contents-read permission, runs the
+   quality/build checks, and creates the tarball artifact. The privileged
+   `publish` job has contents-read and `id-token: write`, waits for the
+   `production` environment approval, and publishes **exactly the verified
+   tarball** with `--access public --provenance --ignore-scripts`.
+
+   The quality/build job is the gate: the publish job must not re-execute
+   source or dependency installation in a privileged context. The
+   `--ignore-scripts` flag is intentional for the final artifact publication,
+   not a way to bypass the quality gates.
+5. For a manually started run, select an existing stable tag as the workflow
+   ref. For example:
+
+   ```sh
+   gh workflow run publish.yml --ref vX.Y.Z
+   ```
+
+   Do not dispatch from `main` or use an arbitrary branch. At the environment
+   approval, inspect the tag, commit, tarball, and checksum before approving.
+   After publication, verify the exact registry version, provenance, public
+   access, clean installation, and the documented OpenCode V2 plugin/TUI
+   discovery path.
+
+## Troubleshooting
+
+- **Package not found (404):** complete the one-time interactive bootstrap;
+  Trusted Publishing cannot create the first package.
+- **OIDC token missing:** check that the publish job has exactly the runtime
+  `id-token: write` permission and that the environment name is exactly
+  `production`.
+- **Provenance or repository failure:** verify the package is public, the
+  Trusted Publisher fields match `bjorntech/key-ferry` and `publish.yml`, and
+  the run is from a stable tag.
+- **Configuration expired:** recreate it shortly before the next genuine
+  release; do not manufacture an empty or fake release.
+- **Version already exists:** check the registry first, then increment to a
+  new genuine version. Do not blindly retry or attempt to overwrite it.
+- **Quality failure:** fix the source and rerun the gates. Do not use
+  `--ignore-scripts` indiscriminately or bypass the verification job.

package/docs/troubleshooting.md

@@ -0,0 +1,214 @@
+# Troubleshooting
+
+This integration is a native OpenCode V2 Effect plugin. It manages an owned,
+project-scoped Varlock CLI proxy process. Start OpenCode normally from the
+project directory. Do not wrap OpenCode with `varlock proxy`.
+
+## Before starting
+
+Install Varlock CLI **1.23.0** separately and make sure `varlock` is on `PATH`:
+
+```sh
+varlock --version
+varlock proxy --help
+```
+
+The plugin does not install Varlock, unlock secret stores, or read credentials
+for diagnostics. It expects a valid `.env.schema` in the configured project.
+Configure the Varlock environment, secret source, authentication, and proxy
+rules before starting OpenCode, following the [Varlock documentation](https://varlock.dev/).
+
+The integration protects explicitly mapped local MCP servers and selected
+remote API-key MCP servers. Direct provider transports are not isolated.
+Remote servers not selected by this plugin, including OAuth-only servers, keep
+native OpenCode OAuth and transport behavior.
+
+## Plugin does not load
+
+Add `@bjorntech/key-ferry@0.1.0` to the OpenCode V2 `plugins` list and preserve
+unrelated configuration. OpenCode installs configured npm plugins
+automatically. Install Varlock separately, preferably with
+`brew install dmno-dev/tap/varlock`.
+
+Configure the server plugin from `opencode.json(c)`. OpenCode V2 discovers the
+package's sibling `./tui` export automatically, so a duplicate global
+`cli.json` entry is not needed. A global `cli.json` entry is optional only when
+the CLI connects to a remote OpenCode server that already loaded the server
+plugin, or for a genuinely CLI-only deployment. There is no project-local
+`cli.json` setup.
+
+The plugin requires OpenCode V2's native Effect entrypoint, compatible with
+`@opencode/plugin` 2.0.30 and Effect 4.0.1. Do not load it through the Promise
+entrypoint. The package declares Node >=22; Bun 1.4.2 is used by this project
+for development and CI.
+
+If OpenCode reports a plugin import or entrypoint error, check the built
+package exports and restart the OpenCode service after rebuilding.
+
+Relative `projectDirectory` values are resolved against OpenCode's project
+directory and canonicalized before the sidecar starts. The resulting canonical
+directory is used for Varlock ownership matching and safe status output.
+
+## MCP server is disabled
+
+The plugin changes only names listed in `options.servers`. Each mapping is
+output environment name to an exact Varlock placeholder name. An array is a
+same-name mapping:
+
+```jsonc
+"servers": {
+  "example-local-mcp": {
+    "env": ["FAKE_API_KEY"]
+  }
+}
+```
+
+An object supports an explicit mapping:
+
+```jsonc
+"servers": {
+  "example-local-mcp": {
+    "env": { "UPSTREAM_KEY": "FAKE_API_KEY" }
+  }
+}
+```
+
+The MCP server must already exist in `mcp.servers` and must be `type: "local"`.
+Remote or missing servers are not silently routed. Replace the illustrative
+command in `examples/opencode.jsonc` with a real local MCP command before
+launching it; the example command is not an installed fixture.
+
+The server remains disabled when the sidecar is not ready, startup or refresh
+fails, a mapped placeholder is absent, or the project explicitly disabled the
+server. This is fail-closed behavior. A later successful refresh can restore a
+server that the plugin disabled, but never one explicitly disabled in project
+configuration.
+
+## Remote MCP server is disabled
+
+Select a remote server with a `remote.headers` mapping only when the native
+MCP configuration explicitly uses `oauth: false`:
+
+```jsonc
+{
+  "type": "remote",
+  "url": "https://mcp.example.test/mcp",
+  "oauth": false
+}
+```
+
+The plugin then creates an authenticated loopback relay. Header mappings refer
+to exact Varlock environment names, not raw values:
+
+```jsonc
+"remote-tools": {
+  "remote": {
+    "headers": {
+      "Authorization": { "env": "REMOTE_API_KEY", "prefix": "Bearer " },
+      "X-Tenant": "REMOTE_TENANT"
+    }
+  }
+}
+```
+
+If `oauth` is omitted or is an OAuth object, the selected server is disabled
+with a safe diagnostic. Remove the mapping to preserve native OAuth, or
+explicitly choose API-key mode with `oauth: false`. The plugin never silently
+disables OAuth or falls back to the direct remote URL.
+
+The remote URL must be HTTPS without URL credentials or a fragment. Literal
+loopback, private, link-local, and metadata IP targets are rejected unless
+`allowPrivateNetwork: true` is explicitly configured. Corporate DNS names are
+allowed. The relay target is fixed from the configured server and cannot be
+chosen by a downstream MCP request.
+
+The relay supports Streamable HTTP and legacy SSE, including streaming,
+session headers, DELETE termination, cancellation, and same-origin legacy SSE
+endpoint rewriting. It caps registered session routes at 256, rejects new
+routes after the cap, and does not count duplicate registrations. A Varlock
+refresh or relay replacement resets native MCP sessions. Existing sessions
+must reconnect.
+
+Verification status: the synthetic HTTPS remote Varlock test passes. This
+does not claim compatibility with every external MCP provider or a live
+OpenCode TUI session.
+
+## Strict egress or schema errors
+
+With `requireStrictEgress: true`, the manager requires the Varlock schema to
+use strict egress. The schema header syntax is:
+
+```env-spec
+# @proxyConfig={egress="strict"}
+# ---
+```
+
+Route a protected item with an item decorator, for example:
+
+```env-spec
+# @proxy(domain="api.example.test")
+FAKE_API_KEY=sk-test-000000000000000000000000
+```
+
+`@proxy(domain=...)` on an item creates the injection rule. A header-level
+proxy rule alone does not inject an item. Do not use a real key in examples or
+diagnostics.
+
+The plugin's protocol accepts only exact placeholder matches. `@proxy=passthrough`
+values are allowed by Varlock for child environments, but they are not a
+wildcard source for this integration and cannot satisfy an unrelated mapping.
+
+## Proxy-aware SDK behavior
+
+An explicitly mapped local MCP process receives proxy-related environment
+wiring only when the proxy is ready. A local client that ignores or overwrites
+those variables can bypass the intended route.
+
+An explicitly mapped remote MCP server uses the authenticated relay instead of
+native direct transport. The relay sends placeholder-bearing headers through
+Varlock's HTTP CONNECT proxy to the fixed HTTPS target, so remote routing does
+not depend on the MCP client honoring environment proxy variables. CA MITM
+support and response scrubbing still have limitations. This integration is not
+a sandbox and cannot isolate a same-user process from stores, files, or daemons.
+
+## Refresh, status, and doctor
+
+The server plugin exposes the `key-ferry` RPC with `status`, `refresh`,
+and `doctor` methods. These return sanitized phase, project, generation, PID,
+endpoint metadata, safe configuration diagnostics, and safe error codes. They
+do not return environment maps, relay capabilities or tokens, CA material, or
+secret values.
+
+If refresh fails, protected servers are disabled and the failure is reported
+as a sanitized `unavailable` RPC error. Doctor first ensures Varlock state and
+then reconciles or recreates unhealthy selected `oauth:false` remote relays;
+it does not silently authenticate or replace native OAuth. Check the Varlock
+schema and configured authentication context, then use `/key-ferry-refresh` or
+`/key-ferry-doctor`, or the matching Varlock palette commands, when the TUI is
+available. Do not manually stop unrelated Varlock processes: only the process
+owned by this project manager is eligible for cleanup.
+
+## Verify the installation
+
+These commands do not contact a real service or require credentials:
+
+```sh
+bun typecheck
+bun test
+bun run build
+```
+
+An opt-in live test is available with `VARLOCK_LIVE_BINARY` set to an absolute
+Varlock CLI path. It uses a synthetic fixture and isolated XDG configuration.
+Do not enable real secret-manager, OAuth, or network tests in CI.
+
+The remote live fixture is gated and skipped by default:
+
+```sh
+VARLOCK_LIVE_BINARY=/absolute/path/to/varlock bun test tests/remote-varlock-live.test.ts
+```
+
+That command is a gated synthetic compatibility check. The normal suite and
+live fixtures are separate verification layers; these commands do not certify
+production deployments, every external MCP provider, or a fully live OpenCode
+host/TUI session.

package/examples/.env.schema

@@ -0,0 +1,17 @@
+# Synthetic example only. Do not put a real credential in this file.
+# Strict egress blocks requests that do not match an explicit proxy rule.
+# @proxyConfig={egress="strict"}
+# ---
+# @proxy(domain="api.example.test")
+# @placeholder=sk-test-000000000000000000000000
+FAKE_API_KEY=sk-test-000000000000000000000000
+
+# Synthetic remote MCP API-key example. The value is deliberately fake.
+# @proxy(domain="mcp.example.test")
+# @placeholder=sk-remote-test-000000000000000000000
+REMOTE_API_KEY=sk-remote-test-000000000000000000000
+
+# This is also synthetic and is mapped as a header placeholder in the example.
+# @proxy(domain="mcp.example.test")
+# @placeholder=tenant-test-placeholder
+REMOTE_TENANT=tenant-test-placeholder

package/examples/opencode.jsonc

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      // Merge this entry into your existing config; preserve unrelated
+      // plugins and MCP servers.
+      "package": "@bjorntech/key-ferry@0.1.0",
+      "options": {
+        "enabled": true,
+        "projectDirectory": ".",
+        "command": ["varlock"],
+        "startupTimeoutMs": 30000,
+        "reloadTimeoutMs": 30000,
+        "requireStrictEgress": true,
+        "servers": {
+          "example-local-mcp": {
+            "env": ["FAKE_API_KEY"],
+          },
+          "example-remote-mcp": {
+            "remote": {
+              "headers": {
+                "Authorization": { "env": "REMOTE_API_KEY", "prefix": "Bearer " },
+                "X-Tenant": "REMOTE_TENANT",
+              },
+            },
+          },
+        },
+      },
+    },
+  ],
+  "mcp": {
+    "servers": {
+      "example-local-mcp": {
+        "type": "local",
+        "command": ["node", "./path/to/your-mcp-server.mjs"],
+      },
+      "example-remote-mcp": {
+        "type": "remote",
+        "url": "https://mcp.example.test/mcp",
+        "oauth": false,
+      },
+    },
+  },
+}

package/package.json

@@ -1,6 +1,98 @@
 {
+  "$schema": "https://json.schemastore.org/package.json",
   "name": "@bjorntech/key-ferry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Project-scoped Key Ferry integration for OpenCode V2",
+  "keywords": [],
+  "homepage": "https://github.com/bjorntech/key-ferry#readme",
+  "bugs": {
+    "url": "https://github.com/bjorntech/key-ferry/issues"
+  },
+  "license": "MIT",
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bjorntech/key-ferry.git"
+  },
+  "directories": {
+    "doc": "docs",
+    "example": "examples",
+    "test": "tests"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "docs",
+    "examples"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "import": "./dist/contracts.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
+    },
+    "./options": {
+      "types": "./dist/options.d.ts",
+      "import": "./dist/options.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc.d.ts",
+      "import": "./dist/rpc.js"
+    },
+    "./tui": {
+      "types": "./dist/tui.d.ts",
+      "import": "./dist/tui.js"
+    },
+    "./relay": {
+      "types": "./dist/relay/index.d.ts",
+      "import": "./dist/relay/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage && bun scripts/check-coverage.ts",
+    "test:crap": "bun scripts/crap/run.ts",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "quality": "npm run format:check && npm run typecheck && npm run test:coverage && npm run test:crap",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run quality && npm run build"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "2.0.30",
+    "@types/istanbul-lib-coverage": "2.0.6",
+    "@types/istanbul-lib-instrument": "1.7.8",
+    "@types/node": "^24.0.0",
+    "effect": "4.0.1",
+    "istanbul-lib-coverage": "3.2.2",
+    "istanbul-lib-instrument": "6.0.3",
+    "oxfmt": "0.72.0",
+    "solid-js": "1.9.17",
+    "typescript": "^5.8.2"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": "2.0.30",
+    "effect": "4.0.1",
+    "solid-js": ">=1.9.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}