Hypervault

1. Purpose

Hypervault is the platform implementation of a Hyperapp's connection facet — the store a connection's grant lives in. It is Hypernet's credential vault: the AuthZ layer beside Hyperauth's AuthN, a platform layer beside Hyperfile.

A Hyperapp records the grant a connection produces here and reads it back to act on the provider. The vault stores; it does not act.

2. Model

• A grant is provider-agnostic. (provider, agent) → { kind, account, external_id, secret } — an installation reference, OAuth tokens, an API key. The secret is opaque to the vault and encrypted at rest.
• Store, not act. Hypervault holds no provider logic and mints no provider tokens. A Hyperapp reads its grant and calls the provider itself, so provider credentials and code never centralize in a shared service.
• Credentials, not identity. Hyperauth asserts who the agent is; Hypervault holds what it may reach — identity, not secrets.

3. Interface

GET    /:provider/:agentId          → the grant (?secret=1 includes it)
GET    /:provider/by-external/:id   → find a grant by external id (webhook time)
PUT    /:provider/:agentId          → upsert { kind, account, externalId, secret, meta }
DELETE /:provider/:agentId          → revoke

Grants are stored in a provider-agnostic table, secrets encrypted with a KEK, gated by a service token; a Hyperapp reaches it over a service binding through the @agx-computer/hypervault client — createHypervault({ binding, token, provider }) — rather than the raw endpoints. The GitHub Hyperapp, for example, holds its own App key, reads its grant (the installation) from Hypervault, and mints installation tokens itself.

4. Principles

• Provider-agnostic. A grant is opaque; all provider logic lives in the Hyperapp.
• Optional. A Hyperapp may keep its own store and answer for its own status; Hypervault is the shared default.
• Secrets stay in. A grant's secret is returned only to gated first-party consumers, never on the agent surface.