Skip to content

feat: phantom-credential brokering for tool execution (credential never enters the child) - #16

Merged
tcconnally merged 1 commit into
mainfrom
feat/issue-11-phantom-broker
Aug 4, 2026
Merged

feat: phantom-credential brokering for tool execution (credential never enters the child)#16
tcconnally merged 1 commit into
mainfrom
feat/issue-11-phantom-broker

Conversation

@tcconnally

Copy link
Copy Markdown
Collaborator

Summary

Implements the phantom-credential brokering pattern (agent-core #11): the real credential never enters the child process.

New perseus_agent_core/credentials.py:

  • CredentialBroker (Protocol interface) + PhantomCredentialBroker — supervisor-side vault, phantom-token injection, boundary swap, zeroise-on-exit.
  • CredentialVault — holds real secrets; zeroise() overwrites the secret in memory on exit.
  • broker() — creates a phantom-token lease; policy deny or timeout raises BrokerDenied with zero credential material (null effect on deny).
  • execute() — runs the tool child with only the phantom token in its environment (PERSENS_PHANTOM_TOKEN); lease revoked/zeroised on exit (including timeout).
  • swap_at_boundary() — the proxy: validates the phantom and injects the real credential only inside the context (the network boundary); real secret zeroised when the context exits.
  • git_style_tool() — reference git/gh-style invocation wired through the broker.
  • Receipts (BrokerLease.as_receipt) — credential id, tool, outcome, caller-supplied canonicalized argv fields; never the secret value.

Tests (actual output)

python -m pytest tests/test_credentials.py -q7 passed in 0.11s:

  • child env/file/argv contain only the phantom token — the real credential never enters the child (probe process asserts PERSENS_CREDENTIAL is None)
  • boundary swap injects the real credential and zeroises on exit (vault no longer holds it)
  • denied path (policy) and timeout both raise BrokerDenied with no material
  • aborted path leaves no credential material; phantom zeroised
  • receipts never contain the secret value or the phantom token

Full suite: 10 passed; the 3 test_vault_backend.py failures are pre-existing (reproduced on clean main at ac05a11). git diff --check → clean.

Acceptance criteria

  • Child process never holds the real credential (test asserts env/file/argv contain only phantom token)
  • Proxy swap happens at the boundary and the real credential is zeroised after use
  • Denied/aborted path leaves no credential material in memory or disk
  • Ledger receipt records the broker event without the secret value

Closes #11

…er enters the child)

New perseus_agent_core/credentials.py implementing the CredentialBroker
interface (#11):

- CredentialVault: supervisor-side vault; real secrets live here and nowhere
  else; zeroise overwrites the secret on exit.
- PhantomCredentialBroker: broker() creates a phantom-token lease (policy
  deny or timeout => BrokerDenied with zero credential material, null effect
  on deny); execute() runs the child with only the phantom token in its
  environment and revokes/zeroises the lease on exit; swap_at_boundary() is
  the proxy that injects the real credential only inside the boundary and
  zeroises it on exit.
- git_style_tool(): reference git/gh-style invocation path through the
  broker.
- Receipts (BrokerLease.as_receipt) record credential id, tool, outcome, and
  caller-supplied canonicalized argv fields - never the secret value, never
  raw argv bodies.

Tests (7, all passing): child env/file/argv hold only the phantom token; the
real credential never enters the child; boundary swap + zeroise on exit;
aborted path leaves no credential material; policy deny and timeout are
null-effect; receipts never contain the secret or phantom token.

Full suite: 10 passed (3 pre-existing test_vault_backend failures reproduced
on clean main at ac05a11 - unrelated to this change).

Closes #11
@tcconnally
tcconnally merged commit 6538d9a into main Aug 4, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: phantom-credential brokering for tool execution (credential never enters the child)

1 participant