ZipPigeon technical whitepaper Updated Aug 2, 2026 3 min read

Keep agent identity separate

Create an AI agent principal with only agent_access:request and agent_access:consume. It cannot call ordinary upload and share routes, and an ordinary service principal cannot call agent routes. This separation makes the agent, sponsor, key generation, and delegated-access audit trail explicit.

  • One request names one case, 1–10 exact upload IDs, a purpose, and a 5–480 minute duration within deployment policy.
  • The agent cannot use wildcards or enumerate a case through delegated-access routes.
  • A pending request expires after 24 hours if the owner does not act.

Request the minimum artifact set

The agent signs a request containing the case, exact eligible uploads, purpose, and requested duration. The response snapshots the relevant policy, sponsor, agent fingerprint and key generation, artifact versions, manifest digests, and request digest so later approval refers to the same intent.

POST /api/agent-access/requests
GET  /api/agent-access/requests/:id
POST /api/agent-access/requests/:id/cancel

{
  "caseId": "case_id",
  "uploadIds": ["upload_id"],
  "purpose": "Investigate alert IR-42",
  "durationMinutes": 60
}

Require owner review and local key rewrapping

The case owner reviews the purpose, requesting agent, fingerprint, duration, and exact artifacts in the browser. Approval requires unlocked owner keys and recent password or passkey verification. The browser opens the owner envelopes, rewraps only the selected payload keys to the snapshotted agent key, signs the authorization, and commits the complete approval atomically.

  • The server does not substitute itself for the human approval or ask for plaintext payload keys.
  • If one artifact cannot be validated or rewrapped, the approval does not partially succeed.
  • Denial and revocation are owner actions protected by recent step-up verification.
GET  /api/agent-access/requests
POST /api/agent-access/requests/:id/opened
POST /api/agent-access/requests/:id/approve
POST /api/agent-access/requests/:id/deny
POST /api/agent-access/grants/:id/revoke

Retrieve once through a short capability

After approval, agent_access:consume can inspect the redacted grant and issue one live 15-minute encrypted retrieval capability for each authorized artifact. The CLI downloads ciphertext, validates the bound records, unwraps the payload key with the agent bundle, and decrypts locally.

GET  /api/agent-access/grants/:id
POST /api/agent-access/grants/:id/artifacts/:uploadId/retrieval
GET  /api/agent-access/grants/:id/receipt

zippigeon agent-access download --grant <grant_id> --upload <upload_id> --out ./downloads
zippigeon agent-access receipt --grant <grant_id> --out receipt.json

Use receipts with accurate claims

The receipt binds the request, owner authorization, grant, artifacts, and capability-issuance events with owner and server signatures. It can show that access was authorized and a capability was issued; it does not prove a successful download, what a model did with plaintext, or that every plaintext copy was later deleted.

  • Revocation blocks future capability issuance and clears retained encrypted agent envelopes.
  • A capability already issued can remain live for its short lifetime.
  • No access system can recall plaintext already decrypted inside the customer-run agent.

Benefits and use cases

The flow converts broad machine access into a reviewable, cryptographically bound transaction. It is useful when an incident assistant needs selected evidence, a compliance agent needs named records, a legal workflow needs a bounded document set, or a support agent needs an approved diagnostic bundle.

  • Incident response: authorize only the artifacts tied to one alert or ticket.
  • Compliance review: preserve purpose, sponsor, artifact digests, duration, and receipt evidence.
  • Support automation: let the customer approve a diagnostic package before local agent processing.