Skip to content

notes.md

Latest commit

 

History

History
110 lines (92 loc) · 9.09 KB

notes.md

File metadata and controls

110 lines (92 loc) · 9.09 KB
Raw

Notes: Phantom North Star Stabilization

Session Context

  • Branch: main
  • Entire: entire resume main returned no checkpoint.
  • Recent commits focus on v0.6.0 release and registry metadata.

Research Findings

Proxy Authentication

  • Authenticated proxy URLs were generated by ServiceRegistry::base_url_overrides_with_token in crates/phantom-proxy/src/services.rs.
  • phantom exec and phantom start both consumed that helper and printed/injected URLs containing ?phantom_token=....
  • Proxy authentication happens in crates/phantom-proxy/src/server.rs::handle_request.
  • The proxy already strips phantom_token from forwarded upstream queries and drops x-phantom-proxy-token from forwarded headers.

Implementation

  • Added ProxyConfig::allow_query_token_auth, defaulting to false.
  • Header token auth remains x-phantom-proxy-token.
  • Query token auth now works only when the proxy is started with allow_query_token_auth: true.
  • CLI compatibility switch: PHANTOM_PROXY_ALLOW_QUERY_TOKEN=1.
  • Default phantom exec and phantom start base URLs are now token-free.
  • phantom exec passes PHANTOM_PROXY_TOKEN into the child environment.
  • phantom start continues printing PHANTOM_PROXY_TOKEN as a separate export.

Verification

  • ~/.cargo/bin/cargo test -p phantom-secrets-proxy: passed, 59 tests.
  • ~/.cargo/bin/cargo check -p phantom-secrets: passed.
  • ~/.cargo/bin/cargo fmt --all -- --check: passed after formatting.

Audit Integrity Wave

  • Added signed monotonic seq values to new audit events.
  • phantom audit verify now treats malformed JSON lines and sequence gaps as verification failures.
  • Added audit-head.json, a signed atomic head checkpoint with last_seq and last_hmac.
  • verify_log() compares the walked log tail against the head checkpoint, catching tail truncation of new sequenced logs.
  • Remaining known limitation: deleting both audit.log and audit-head.json still requires external backup/checkpoint evidence.
  • Explorer findings confirmed next audit gaps after this slice: file locking for concurrent writers, explicit fail-closed mode, and wider audit coverage for cloud/team/sync/proxy/MCP/config events.

Parallel Discovery Findings

  • MCP mutating tools still use confirm: true; next hardening slice should add out-of-band nonce approvals bound to tool name, canonical args hash, project, TTL, and audit events.
  • .phantom.toml service mappings accept free-form domains; next config slice should add advisory risk analysis in core and surface warnings in doctor/check.
  • Web blockers include device auth normalization mismatch, browser billing auth mismatch, team API/client contract mismatches, recursive RLS policies, and non-atomic team vault CAS.
  • Docs/action drift: GitHub Action docs reference unsupported flags (login --ci, cloud pull --env, list --count), source install package names are inconsistent, and proxy-auth docs need updating after header-only defaults.

Device Auth Wave

  • Fixed initiate/approve mismatch by storing device_tokens.user_code as canonical uppercase alphanumeric without hyphens.
  • API still returns readable XXXX-XXXX codes using shared formatting helper.
  • Browser device page and approve route now use shared normalization/validation helpers.
  • Initiate rate limit now matches its comment: reject once 10 device codes have been created in the last minute.
  • Added migration 20260523000016_canonical_device_user_codes.sql to canonicalize existing user codes and enforce a unique user_code index.
  • Verification: npx tsc --noEmit passed, npm run build passed.

Config Route Risk Wave

  • Added PhantomConfig::service_risks() to flag suspicious API service mappings without rejecting custom providers.
  • Warnings cover built-in service reroutes, known secret keys routed to unexpected domains, URL/path/userinfo/wildcard patterns, localhost/private IPs, and header_format values missing {secret}.
  • phantom doctor surfaces route risks as issues with a review fix hint.
  • phantom check --staged parses staged .phantom.toml blobs and prints route-risk warnings without incrementing blocking issues.
  • Verification: cargo test -p phantom-secrets-core service_risks, cargo test -p phantom-secrets --test check_test, and cargo test -p phantom-secrets --test doctor_test passed.

Team API Contract Finding

  • Rust team client expects raw arrays/objects for list/create/members while web routes return { teams }, { team }, and { members }.
  • Fixed Rust response envelope parsing in crates/phantom-core/src/teams.rs for list_teams, create_team, and list_members.
  • Added serde contract tests for { teams }, { team }, and { members }.
  • Remaining team contract issue: Rust sends github_login for invites while web currently requires user_id.
  • Verification: cargo test -p phantom-secrets-core teams passed.

Proxy Auth Docs Finding

  • Public docs still need header-auth wording after the proxy auth change.
  • Update README/getting-started/LLM docs/blog snippets to state local proxy requests must send x-phantom-proxy-token: $PHANTOM_PROXY_TOKEN.
  • Query-string proxy auth should be described only as legacy compatibility via PHANTOM_PROXY_ALLOW_QUERY_TOKEN=1.

Proxy Auth Docs Wave

  • Updated README quick start, Windows notes, how-it-works, command reference, and feature list to describe PHANTOM_PROXY_TOKEN and x-phantom-proxy-token.
  • Updated docs/getting-started.md, docs/llms-full.txt, and apps/web/public/llms-full.txt to remove stale claims that phantom placeholders are regenerated per phantom exec session.
  • Updated static docs/pricing copy from "session-scoped tokens" to header-authenticated proxy sessions.
  • Verification: rg confirmed no remaining "Session-scoped tokens" or "session generates fresh phantom" claims in README/docs/public LLM copy.

GitHub Action Drift Wave

  • Disabled integrations/github-actions/action.yml as a fail-fast placeholder because the current CLI does not support non-interactive Phantom Cloud auth for GitHub Actions.
  • Replaced GitHub Action README and example workflow with supported CI patterns: phantom check --staged in CI and platform sync to Vercel/Railway for deployment secrets.
  • Rewrote docs/ci-cd.md to remove unsupported phantom login --ci, phantom reveal --passphrase, phantom cloud pull --env, phantom list --count, phantom status --quiet, PHANTOM_CLOUD_TOKEN, and Fly.io sync claims.
  • Verification: rg confirms remaining unsupported commands appear only in the GitHub Action README's explicit "Not Supported Yet" list.

Team Invite Contract Wave

  • Fixed the web POST /api/v1/teams/:team_id/members route to accept either legacy user_id or the intended CLI/MCP github_login contract.
  • GitHub login values are trimmed, optional leading @ is stripped, and lookup is case-insensitive via ilike.
  • Missing invitee returns a product-specific 404 telling the user the invitee must sign in to Phantom first; duplicate login matches return 409.
  • Owner role remains disallowed through invitations because owner transfer is a separate future flow.
  • Verification: npm run build and npx tsc --noEmit passed after this route change.

Integration Review Findings

  • Integration review found three production blockers: header-only proxy auth could break generic SDKs, audit HMAC/head writes were not concurrency-safe, and device-code migration could fail on historical canonical duplicates.
  • All three were addressed in follow-up slices below.
  • Remaining candidate slices: MCP nonce approval hardening, wider audit event coverage for cloud/team/sync/proxy/config, Supabase RLS recursion review, and team vault CAS.

SDK-Compatible Proxy Auth Wave

  • Kept proxy server header auth and query compatibility support, but changed CLI-generated SDK URLs to use a path-scoped local auth segment: /<service>/_phantom/<proxy-token>/.
  • The proxy strips /_phantom/<token> before route matching and before forwarding upstream.
  • phantom exec and phantom start default to SDK-compatible path-auth URLs; PHANTOM_PROXY_HEADER_AUTH_ONLY=1 emits token-free base URLs and requires x-phantom-proxy-token.
  • Updated README, threat model, docs, static site, and LLM reference copy to distinguish default SDK compatibility from strict header-only mode.

Device Code Collision Wave

  • initiate now retries unique constraint collisions up to five times before returning 503.
  • approve now selects the newest pending, unexpired canonical user code with maybeSingle() instead of failing on old duplicate rows.
  • Migration now canonicalizes user codes, expires stale pending rows, expires older duplicate pending rows, and creates a partial unique index on pending user_code only.

Audit Concurrency/Fail-Closed Wave

  • Added AuditMode::{Disabled, BestEffort, Required} with PHANTOM_AUDIT=required / fail-closed.
  • Added log_result() so future high-risk command paths can propagate audit failures while legacy log() remains best-effort.
  • Added an audit.lock file with exclusive writer locking and shared verify locking to serialize HMAC-chain/head checkpoint transactions.
  • Added concurrency and required-mode unit tests in crates/phantom-core/src/audit.rs.