feat: Phase AI credential proxy for coding agents, harness integrations and relay

.github/scripts/ai-enable-container.sh

@@ -0,0 +1,43 @@
+#!/bin/sh
+# Runs inside a stock Linux container as root: creates an unprivileged user and
+# checks `phase ai enable` both without NSS certutil (browser trust must be
+# skipped, not fatal) and with it installed (trust must land in the per-user
+# NSS database). Env: PHASE (binary path), INSTALL (command that installs certutil).
+set -eu
+PHASE="${PHASE:?}"; INSTALL="${INSTALL:?}"
+. /etc/os-release 2>/dev/null || true; echo "os: ${PRETTY_NAME:-unknown}"
+if command -v useradd >/dev/null 2>&1; then useradd -m -s /bin/sh tester; else adduser -D tester; fi
+as_user() {
+  if command -v runuser >/dev/null 2>&1; then runuser -u tester -- sh -c "export HOME=/home/tester; cd /home/tester; $1"
+  elif command -v su >/dev/null 2>&1; then su tester -c "export HOME=/home/tester; cd /home/tester; $1"
+  elif command -v setpriv >/dev/null 2>&1; then setpriv --reuid=tester --regid=tester --init-groups sh -c "export HOME=/home/tester; cd /home/tester; $1"
+  else chroot --userspec=tester:tester / sh -c "export HOME=/home/tester; cd /home/tester; $1"; fi
+}
+fail() { echo "FAIL: $*" >&2; exit 1; }
+if command -v certutil >/dev/null 2>&1; then fail "image already has certutil; the stock run needs it absent"; fi
+
+echo "--- stock image: browser trust must be skipped without failing"
+out="$(as_user "$PHASE ai enable --harness claude-code --mask" 2>&1)" || fail "enable failed without certutil: $out"
+echo "$out" | grep -q "Browser CA trust skipped" || fail "missing skip notice: $out"
+echo "$out" | grep -q "Phase AI enabled for Claude Code" || fail "harness not enabled: $out"
+if command -v script >/dev/null 2>&1; then
+  echo "--- stock image, interactive terminal: the trust prompt must not appear"
+  out="$(as_user "printf 'y\n' | script -qec '$PHASE ai enable --harness claude-code --mask' /dev/null" 2>&1 | tr -d '\r')" || fail "interactive enable failed: $out"
+  echo "$out" | grep -q "Trust the Phase AI CA" && fail "prompt shown although certutil is missing: $out"
+  echo "$out" | grep -q "Browser CA trust skipped" || fail "missing skip notice in interactive run: $out"
+fi
+echo "--- stock image: an explicit --trust-ca fails with the package hint"
+if out="$(as_user "$PHASE ai enable --harness claude-code --mask --trust-ca" 2>&1)"; then fail "explicit --trust-ca succeeded without certutil: $out"; fi
+echo "$out" | grep -q "NSS certutil is not installed (package" || fail "missing package hint: $out"
+
+echo "--- installing certutil: $INSTALL"
+sh -c "$INSTALL" >/dev/null 2>&1 || fail "could not install certutil"
+command -v certutil >/dev/null 2>&1 || fail "certutil still missing after install"
+out="$(as_user "$PHASE ai enable --harness claude-code --mask --trust-ca" 2>&1)" || fail "enable --trust-ca failed: $out"
+echo "$out" | grep -q "trusted in the Linux current-user NSS database" || fail "CA not trusted: $out"
+as_user "certutil -L -d sql:/home/tester/.pki/nssdb" | grep -q "Phase AI Proxy CA" || fail "NSS database does not list the Phase CA"
+second="$(as_user "$PHASE ai enable --harness claude-code --mask --trust-ca" 2>&1)" || fail "second enable --trust-ca failed: $second"
+echo "$second" | grep -q "already trusted" || fail "second trust run not idempotent: $second"
+status="$(as_user "$PHASE ai status" 2>&1)" || fail "status failed: $status"
+echo "$status" | grep -q "Phase AI:    enabled" || fail "status not enabled: $status"
+echo "OK: ${PRETTY_NAME:-unknown}"

.github/scripts/ai-enable-smoke.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Runs `phase ai enable` end to end on a CI runner and checks the result.
+# usage: ai-enable-smoke.sh <phase-binary> <no-trust|trust-nss>
+set -euo pipefail
+PHASE="$1"; MODE="$2"
+HOME_DIR="${HOME:?}"
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+case "$MODE" in
+  no-trust)
+    output="$("$PHASE" ai enable --harness claude-code --mask --trust-ca=false </dev/null 2>&1)" || fail "enable exited non-zero: $output"
+    echo "$output"
+    echo "$output" | grep -q "Phase AI CA ready" || fail "CA was not created"
+    echo "$output" | grep -q "Phase AI enabled for Claude Code" || fail "harness was not enabled"
+    ;;
+  trust-nss)
+    command -v certutil >/dev/null || fail "certutil is required for trust-nss"
+    output="$("$PHASE" ai enable --harness claude-code --mask --trust-ca </dev/null 2>&1)" || fail "enable --trust-ca exited non-zero: $output"
+    echo "$output"
+    echo "$output" | grep -q "trusted in the Linux current-user NSS database" || fail "CA was not trusted in the NSS database"
+    certutil -L -d "sql:$HOME_DIR/.pki/nssdb" | grep -q "Phase AI Proxy CA" || fail "NSS database does not list the Phase CA"
+    # A second run must be idempotent.
+    second="$("$PHASE" ai enable --harness claude-code --mask --trust-ca </dev/null 2>&1)" || fail "second enable --trust-ca exited non-zero: $second"
+    echo "$second" | grep -q "already trusted" || fail "second trust run was not idempotent: $second"
+    ;;
+  *) fail "unknown mode $MODE" ;;
+esac
+
+status="$("$PHASE" ai status 2>&1)"
+echo "$status"
+echo "$status" | grep -q "Phase AI:    enabled" || fail "status does not report enabled"
+echo "$status" | grep -q "^CA:" || fail "status does not report the CA"
+[ -f "$HOME_DIR/.phase/ai/ca.pem" ] || fail "ca.pem missing"
+grep -q "PRIVATE KEY" "$HOME_DIR/.phase/ai/ca.pem" && fail "ca.pem contains private material"
+[ -f "$HOME_DIR/.claude/skills/phase-cli-ai-relay/SKILL.md" ] || fail "runtime skill missing"
+[ -f "$HOME_DIR/.claude/skills/phase-cli-app-secrets/SKILL.md" ] || fail "secrets skill missing"
+echo "OK: $MODE"

.github/workflows/test.yml

@@ -38,3 +38,79 @@ jobs:
       - name: Build (smoke test)
         working-directory: src
         run: go build ./...
+
+  enable-smoke:
+    name: phase ai enable (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    env:
+      CGO_ENABLED: "0"
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Go
+        uses: actions/setup-go@v7
+        with:
+          go-version: "1.25.x"
+          cache-dependency-path: src/go.sum
+
+      - name: Build
+        working-directory: src
+        shell: bash
+        run: go build -o ../phase-cli${{ runner.os == 'Windows' && '.exe' || '' }} .
+
+      - name: Enable without touching the trust store
+        shell: bash
+        run: ./.github/scripts/ai-enable-smoke.sh ./phase-cli${{ runner.os == 'Windows' && '.exe' || '' }} no-trust
+
+      - name: Trust the CA in the per-user NSS database
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update -qq && sudo apt-get install -y -qq libnss3-tools
+          ./.github/scripts/ai-enable-smoke.sh ./phase-cli trust-nss
+
+      # The macOS keychain and the Windows user Root store need a consent
+      # dialog that a headless runner cannot show (the command blocks until
+      # the job times out), so those two trust paths are covered by the unit
+      # tests with a recorded command runner and by manual QA.
+
+  enable-containers:
+    name: phase ai enable (${{ matrix.image }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: fedora:41
+            install: dnf -y -q install nss-tools
+          - image: debian:12
+            install: apt-get -qq update && DEBIAN_FRONTEND=noninteractive apt-get -qq install -y libnss3-tools
+          - image: ubuntu:24.04
+            install: apt-get -qq update && DEBIAN_FRONTEND=noninteractive apt-get -qq install -y libnss3-tools
+          - image: alpine:3.20
+            install: apk add -q nss-tools
+          - image: archlinux:latest
+            install: pacman -Sy --noconfirm --disable-sandbox nss
+    env:
+      CGO_ENABLED: "0"
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Go
+        uses: actions/setup-go@v7
+        with:
+          go-version: "1.25.x"
+          cache-dependency-path: src/go.sum
+
+      - name: Build a static Linux binary
+        working-directory: src
+        run: GOOS=linux GOARCH=amd64 go build -o ../phase-cli .
+
+      - name: Enable inside a stock ${{ matrix.image }} container
+        run: |
+          docker run --rm -v "$PWD:/work:ro" -e PHASE=/work/phase-cli -e INSTALL='${{ matrix.install }}' \
+            ${{ matrix.image }} sh /work/.github/scripts/ai-enable-container.sh
+

.gitignore

@@ -1,6 +1,7 @@
 # Go build output
 bin/
 dist/
+/src/phase
 
 # Go module
 vendor/

.goreleaser.yaml

@@ -78,8 +78,15 @@ nfpms:
       - rpm
       - apk
     bindir: /usr/bin
-    replaces:
-      - "phase (<< 2.0.0)"
+    # Each packager spells version relations differently; nfpm now rejects
+    # the deb form for rpm.
+    overrides:
+      deb:
+        replaces:
+          - "phase (<< 2.0.0)"
+      rpm:
+        replaces:
+          - "phase < 2.0.0"
     ids:
       - phase-cli
 

README.md

@@ -37,9 +37,13 @@ Commands:
   users switch                      🪄 Switch between Phase users, orgs and hosts
   users logout                      🏃 Logout from phase-cli
   users keyring                     🔐 Display information about the Phase keyring
-  ai enable                         🪄 Enable AI integrations and configure secret visibility
-  ai disable                        🚫 Disable AI integrations and remove skill docs
+  ai enable                         🪄 Enable the local Phase AI credential proxy
+  ai disable                        🚫 Disable AI integrations
+  ai status                         📡 Show Phase AI setup and proxy health
   ai skill                          📄 Print the Phase AI skill document
+  ai run                            🚀 Launch an AI Agent behind the Phase AI credential proxy
+  ai exec                           ⚡ Execute one command behind a transient Phase AI credential proxy
+  relay start                       🛰️ Run a Phase AI relay for remote Agent sandboxes
   console                           🖥️ Open the Phase Console in your browser
   docs                              📖 Open the Phase CLI Docs in your browser
   completion                        ⌨️ Generate the autocompletion script for the specified shell
@@ -51,7 +55,7 @@ Flags:
 
 ## Features
 
-- **End-to-end encryption** — secrets are encrypted client-side before leaving your machine
+- **End-to-end encryption** — App secrets in E2E mode are encrypted client-side before leaving your machine
 - **Secret types** — `config` (non-sensitive), `secret` (sensitive), and `sealed` (write-only) with enforced visibility rules
 - **`phase run`** — inject secrets as environment variables into any command without code changes
 - **`phase shell`** — launch a sub-shell (bash, zsh, fish, etc.) with secrets preloaded
@@ -62,9 +66,9 @@ Flags:
 - **Path-based organisation** — organise secrets in hierarchical paths for monorepos and microservices
 - **Tagging** — tag secrets and filter operations by tag
 - **Random secret generation** — generate hex, alphanumeric, base64, base64url, 128-bit, or 256-bit keys on create or update
-- **AI agent integration** — skill-based integration with Claude Code, Cursor, VS Code Copilot, Codex, and OpenCode with automatic value redaction and safety guardrails
-- **Multiple auth methods** — web-based login, personal access tokens, service account tokens, and AWS IAM identity auth
-- **Multi-user & multi-org** — switch between Phase accounts, orgs, and self-hosted instances
+- **AI Agent proxy** — workflow-scoped third-party Integration credentials for HTTP, PostgreSQL, and AWS without exposing live material
+- **Multiple auth methods** — browser login, personal access tokens, service account tokens, Agent tokens, and AWS IAM identity auth
+- **Multi-user & multi-org** — switch between Phase accounts, orgs and self-hosted instances
 - **OS keyring integration** — credentials stored in macOS Keychain, GNOME Keyring, or Windows Credential Manager
 - **Multiple environments** — dev, staging, production, and custom environments with per-project defaults via `phase init`
 
@@ -125,15 +129,22 @@ phase run 'go run main.go'
 phase run --env production 'python manage.py runserver'
 ```
 
-### AI integration
+## AI Agent proxy
 
-Enable AI agent support (installs a skill doc for your AI coding tool):
+Phase AI gives coding agents (Claude Code, Cursor, Codex, OpenCode, Devin, VS Code Copilot) workflow-scoped access to third-party services (HTTP APIs, AWS, PostgreSQL) without ever handing them a live credential. The agent's process receives decoys; a local proxy on `127.0.0.1:9543` (PostgreSQL adapter on `9544`) swaps them for the real credential on the way out, enforces the Connections approved in the Phase Console, and blocks calls that would mint new credentials.
 
 ```bash
-phase ai enable
+phase ai enable --harness claude-code   # install the hook/plugin and skills for one harness; repeat for others
+phase ai status                          # setup, proxy health, Connections, CA expiry
+phase ai disable
 ```
 
-This installs the Phase skill to your chosen AI tool (Claude Code, Cursor, VS Code Copilot, Codex, or OpenCode) and configures secret visibility. Sealed secrets are never revealed to AI agents regardless of settings.
+- **Claude Code and OpenCode** get the Phase environment automatically: provider CLIs just work while the proxy runs, and fall back to failing on the decoy (never to ambient credentials) when it is down.
+- **Cursor, Codex and Devin** run Phase-managed commands explicitly with `phase ai exec -- <command>` (`--connection <id>` picks one of several identities for a service); `phase ai run -- <agent>` launches a harness inside the environment.
+- **Remote sandboxes** that cannot run the CLI use a relay: `phase relay start --advertise-host <host> --tls-cert <pem> --tls-key <pem>` on a machine logged in with an Agent token prints one line that bootstraps a sandbox over curl.
+- Two skills are installed per harness: `phase-cli-ai-relay` (the proxy, Connections and requests) and `phase-cli-app-secrets` (Phase app secrets). Agents reach the proxy's control API at `http://phase.invalid` and can request new Connections, which a human approves in the Console.
+
+`phase ai enable` creates a per-installation CA (valid 90 days, renewed automatically) and offers to trust it for the current user; it never changes system-wide trust or requires sudo. Command-line tools and SDKs trust the CA through the proxy environment either way; the user trust store matters for browsers and for Go programs on macOS and Windows. On Linux the offer needs NSS certutil (`libnss3-tools` on Debian/Ubuntu, `nss-tools` on Fedora/RHEL/Alpine, `nss` on Arch, `mozilla-nss-tools` on openSUSE) and is skipped with a hint when it is missing.
 
 ## Development
 
@@ -143,18 +154,16 @@ This installs the Phase skill to your chosen AI tool (Claude Code, Cursor, VS Co
 
 ### Project structure
 
-```
+```text
 src/
 ├── main.go          # Entrypoint
 ├── cmd/             # Cobra command definitions
+├── internal/        # Agent API, runtime, and proxy internals
 ├── pkg/
-│   ├── ai/          # AI agent detection, skill doc, redaction
-│   ├── config/      # Config file handling (~/.phase/, .phase.json)
-│   ├── display/     # Output formatting (tree view, tables)
-│   ├── errors/      # Error types
+│   ├── ai/          # Agent detection and embedded skill
+│   ├── config/      # Config file handling
 │   ├── keyring/     # OS keyring integration
-│   ├── phase/       # Phase client helpers (auth, init)
-│   ├── util/        # Misc utilities (color, spinner, browser)
+│   ├── proxy/       # CA, environment, routing, and injection helpers
 │   └── version/     # Version constant
 └── go.mod
 ```

src/cmd/ai.go

@@ -7,7 +7,7 @@ import (
 var aiCmd = &cobra.Command{
 	Use:   "ai",
 	Short: "🥷  Integrate Phase with AI Agents",
-	Long:  "Configure how AI coding agents interact with your Phase secrets.",
+	Long:  "Run AI coding agents through Phase's workflow-scoped local credential proxy.",
 }
 
 func init() {