Overview
Vault is built around one question: does each object in the tenant's environment live under Custodied or Sovereign posture? Custodied means data may reside on external infrastructure. Sovereign means everything must live within the tenant's controlled environment.
The Vault surface in Surface's Settings exposes four capabilities:
- Home posture — the tenant's active declaration (custodied or sovereign)
- Stamp — stamp any object with the current posture, with inheritance logic for derived objects
- Fleet control — pause or resume all ArcRouter model calls for the tenant
- Canary tokens — decoy credentials that fire an alert and fleet pause the moment they are used
All endpoints require an authenticated session (getCurrentMember()). The canary fire endpoint is the exception — it uses a shared webhook secret so ArcGate can call it directly from a deny log.
Home posture
GET /api/vault/home
Returns the tenant's active home posture. If no posture has been set, defaults to custodied.
Object stamps
POST /api/vault/stamp
Stamps an object with a data home. Two modes:
- Direct stamp — use the tenant's active home posture
- Inheritance stamp — derive home from upstream source objects using most-protective-wins: sovereign beats custodied
If source_refs are provided but none have existing stamps, the stamp falls back to the tenant's active home. Pass "type:id" format for each ref — e.g. "workflow:wf_abc".
Fleet control
Fleet pause halts all ArcRouter model calls for the tenant. It fires automatically when a canary token is triggered. It can also be set manually for security audits or incident response.
GET /api/vault/fleet
Returns the current fleet pause state.
POST /api/vault/fleet
| action | Effect |
|---|---|
| pause | Sets paused: true — ArcRouter stops routing model requests |
| resume | Sets paused: false — clears all pause fields, records resumed_by |
| dry-run | Records a pause event in history without actually halting the fleet. Useful for testing the canary pipeline end-to-end. |
Canary tokens
A canary token is a decoy credential or document reference planted in the tenant's environment. If it shows up anywhere in use (in an LLM prompt, in an HTTP request, in a DNS lookup), that signals unauthorized data access. The raw token value is never stored — only its SHA-256 hash. Detection is hash-comparison, not plaintext matching, so the actual value stays server-only.
GET /api/vault/canary/tokens
Lists active canary tokens for the tenant. Values are never returned.
POST /api/vault/canary/tokens
Plants a new canary token. The value is hashed immediately and discarded — it is never stored in plaintext.
POST /api/vault/canary/fire
Called when a canary token is observed in use. Authentication uses a shared secret — Authorization: Bearer <VAULT_CANARY_WEBHOOK_SECRET> — rather than session auth, because ArcGate is a network appliance, not a logged-in user. Per design principle AT-V5, this endpoint fires the fleet pause even when all outbound traffic is blocked.
Provide either probe_value or token_id. If probe_value is given, the endpoint hashes it and looks up the matching active token. If no match is found, a 404 is returned — the fire is not recorded.
Database tables
| Table | Purpose |
|---|---|
| vault_tenant_home | One row per tenant; active posture (custodied / sovereign) and transition history |
| vault_object_stamps | Per-object home stamps; unique on (object_type, object_id); source_refs stored for audit |
| vault_fleet_pause | Current fleet pause state per tenant; upserted on conflict |
| vault_canary_tokens | Planted tokens; stores token_type, label, value_hash, planted_by, active |
| vault_canary_fires | Every detected use of a canary; mttd_seconds computed by DB trigger from planted_at |