pi-credential-vault

Pi extension package that moves managed-provider credential storage out of plaintext ~/.pi/agent/auth.json and into a selectable backend.

Status

Implemented now:

• built-in age, keychain, and passthrough backends
• request-time credential injection through provider overrides
• OAuth login and refresh interception for supported providers
• /vault commands for setup, import, verify, show, providers, path, and help
• direct settings.json configuration plus a minimal /vault settings panel
• CI validation and npm publishing through GitHub Actions and semantic-release

Not implemented yet:

• runtime backend plugin registration
• shared storage integration with pi-multicodex
• dedicated migration and bootstrap workflows
• full settings UX for all config fields

Use PLAN.md for the detailed implementation plan and ROADMAP.md for milestone order.

Install

pi install npm:@victor-software-house/pi-credential-vault

Quick start

# Open pi
pi

# For the default age backend, generate a local identity
/vault setup

# Import existing credentials from auth.json into the active backend
/vault import

# Verify the backend and inspect managed providers
/vault verify
/vault show

# Export credentials to another backend or rewrite current backend
/vault export keychain
/vault export age        # same-backend rewrite: re-encrypts with current recipients

If you use pi-multicodex, exclude openai-codex from vault management until shared storage integration is implemented.

What the extension does

1. Loads pi-credential-vault settings from ~/.pi/agent/settings.json
2. Creates the configured built-in backend
3. Re-registers managed providers through pi.registerProvider()
4. Resolves credentials from the active backend before each request
5. Stores OAuth login and refresh results back into the backend
6. Exposes /vault commands for setup and inspection

Architecture

| Area | Files | Responsibility | |---|---|---| | Entrypoint | index.ts, src/extension.ts | Load controller, register commands, expose minimal event-bus API, update session status | | Types | src/types.ts | Credential entry types, backend interface, config types, extension API types | | Built-in backends | src/backends/*.ts | Encrypted file storage, OS keychain storage, passthrough compatibility storage | | Backend registry | src/backends/registry.ts | Create and cache built-in backend instances | | Configuration | src/config/*.ts | Defaults, settings file I/O, normalization, settings panel | | Provider integration | src/providers/*.ts | Provider mirroring, request-time API key resolution, OAuth wrapping | | Commands | src/commands/vault-command.ts, src/commands/parse-args.ts | /vault command family and argument parsing | | Services | src/services/credential-transfer.ts | Credential transfer between backends | | Tests | src/__tests__/*.test.ts | Backend, registry, command parsing, transfer, and stream helper validation |

Built-in backends

age (default)

Credentials are encrypted with the age-encryption JavaScript library and stored in ~/.pi/agent/vault.age.json by default.

• safe to commit as ciphertext
• supports additional recipients in config
• reads the local identity from ~/.config/pi-vault/age.txt or PI_VAULT_AGE_KEY

Recipient changes are applied by running /vault export age, which re-reads and re-writes every credential with the current recipient list.

keychain

Credentials are stored in the platform keychain through cross-keychain.

• macOS: Keychain
• Linux: Secret Service
• Windows: Credential Manager

This backend is suitable for single-machine local storage, not for syncing encrypted files between machines.

passthrough

Credentials are read from and written to Pi's native auth.json format.

Use this for backward compatibility or as a fallback when a secure backend is unavailable.

Configuration

Settings live under the pi-credential-vault key in ~/.pi/agent/settings.json.

{
  "pi-credential-vault": {
    "backend": "age",
    "managedProviders": "all",
    "excludeProviders": ["openai-codex"],
    "age": {
      "vaultPath": "~/.pi/agent/vault.age.json",
      "identityPath": "~/.config/pi-vault/age.txt",
      "recipients": ["age1abc..."]
    },
    "keychain": {
      "service": "pi-credential-vault"
    }
  }
}

| Setting | Type | Notes | |---|---|---| | backend | age \| keychain \| passthrough | Active built-in backend | | managedProviders | "all" \| string[] | Which provider IDs are managed by the extension | | excludeProviders | string[] | Providers intentionally left to other extensions or native Pi behavior | | age.vaultPath | string | Optional encrypted vault file path | | age.identityPath | string | Optional age identity path | | age.recipients | string[] | Additional age recipients | | keychain.service | string | Service name used in the OS keychain |

Commands

| Command | Current behavior | |---|---| | /vault | Open the settings panel | | /vault show | Show active backend status, credential count, and managed providers | | /vault verify | Check backend health and stored credential count | | /vault providers | Show managed and excluded provider IDs with scope | | /vault setup | Generate an age identity for the default backend | | /vault import | Import credentials from auth.json into the active backend | | /vault export [target] | Export credentials to a target backend. Same-backend export rewrites all entries (forces re-encryption for age). | | /vault path | Show backend-specific file or service locations | | /vault help | Show command summary |

Operator notes

pi-multicodex coexistence

Today, pi-credential-vault and pi-multicodex should not both manage openai-codex.

{
  "pi-credential-vault": {
    "excludeProviders": ["openai-codex"]
  }
}

Shared storage integration remains planned work.

Fallback behavior

If the configured backend is unavailable at startup, the extension currently leaves providers on native Pi behavior and reports the problem through session status and /vault verify.

Status indicator

The repository contains a placeholder status-line module, but current status reporting is performed directly from src/extension.ts during session events.

Development

Install dependencies and run the current validation commands:

pnpm install
pnpm typecheck
pnpm test
npm pack --dry-run

Notes:

• There is currently no repository source-lint script.
• CI runs commitlint, typecheck, test, and npm pack --dry-run.
• Releases are produced by semantic-release from .github/workflows/publish.yml.

Release and documentation rules

• README.md describes implemented behavior only.
• ROADMAP.md tracks milestone order, not pre-assigned semantic versions.
• PLAN.md contains detailed implementation sequencing and design constraints.
• AGENTS.md contains repository-specific contributor and automation rules.
• package.json is part of the operational contract for scripts, package metadata, publish shape, and extension entrypoints.
• When command surface, config shape, release flow, packaging, or architecture changes, update all relevant files together, including package.json when manifest-facing behavior changes.

Known limitations

• The backend registry only supports built-in backends.
• The settings panel currently edits only a subset of config.
• There is no multi-step migration workflow yet (/vault export copies but does not clean up source data).

Related documents

• PLAN.md — detailed implementation plan and phased delivery
• ROADMAP.md — ordered milestone view
• AGENTS.md — contributor and automation guidance