SDKs · Vault

Vault SDK

ArcGrid's data sovereignty layer. Vault controls where data lives (Custodied vs. Sovereign home), stamps objects with their posture, plants canary tokens to detect unauthorized access, and pauses the model fleet if a canary fires.

SDK Security Sovereignty API

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

GETSession auth

Returns the tenant's active home posture. If no posture has been set, defaults to custodied.

// Response { "home": "custodied" | "sovereign", "chosen_at": "2026-10-01T12:00:00Z" | null, "migrated_from": "custodied" | null // set when transitioning postures }

Object stamps

POST /api/vault/stamp

POSTSession auth

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
// Request body { "object_type": "workflow", // up to 64 chars "object_id": "wf_abc123", // up to 128 chars "source_refs": ["workflow:wf_xyz", "document:doc_abc"] // optional } // Response { "object_type": "workflow", "object_id": "wf_abc123", "home": "sovereign", "stamped_at": "2026-10-06T09:30:00Z" }

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

GETSession auth

Returns the current fleet pause state.

// Response { "paused": false, "paused_at": null, "pause_reason": null, "fire_id": null, // set when paused by a canary fire "resumed_at": null, "dry_run": false }

POST /api/vault/fleet

POSTSession auth
actionEffect
pauseSets paused: true — ArcRouter stops routing model requests
resumeSets paused: false — clears all pause fields, records resumed_by
dry-runRecords a pause event in history without actually halting the fleet. Useful for testing the canary pipeline end-to-end.
// Request { "action": "pause" | "resume" | "dry-run", "reason": "Incident response" } // Response { "ok": true, "action": "paused", "dry_run": false }

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

GETSession auth

Lists active canary tokens for the tenant. Values are never returned.

// Response { "tokens": [ { "token_id": "tok_abc", "token_type": "credential" | "document" | "dns", "label": "Stripe prod key (decoy)", "planted_at": "2026-09-15T10:00:00Z", "rotated_at": null, "active": true, "notes": "Planted in the dev secrets doc" } ] }

POST /api/vault/canary/tokens

POSTSession auth

Plants a new canary token. The value is hashed immediately and discarded — it is never stored in plaintext.

// Request { "token_type": "credential" | "document" | "dns", "label": "Stripe prod key (decoy)", "value": "sk_live_DECOY_NOT_REAL_abc123", "notes": "Planted in the dev secrets doc" // optional } // Response (201) { "token_id": "tok_abc", "token_type": "credential", "label": "Stripe prod key (decoy)", "planted_at": "2026-10-06T10:30:00Z", "active": true }

POST /api/vault/canary/fire

POSTWebhook secret (Bearer)

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.

// Request { "source": "arcgate" | "arcrouter" | "manual", "probe_value": "sk_live_DECOY_NOT_REAL_abc123", // raw value seen; hashed to find the token "token_id": "tok_abc", // alternative: direct ID if already known "source_detail": { "deny_log_entry": "..." }, // optional raw context "dry_run": false // true = record fire, skip fleet pause } // Response { "ok": true, "fire_id": "fire_xyz", "token_id": "tok_abc", "tenant_id": "tenant-zero", "fired_at": "2026-10-06T10:31:00Z", "mttd_seconds": 3600, // mean time to detect, computed by DB trigger "fleet_paused": true, "dry_run": false }

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

TablePurpose
vault_tenant_homeOne row per tenant; active posture (custodied / sovereign) and transition history
vault_object_stampsPer-object home stamps; unique on (object_type, object_id); source_refs stored for audit
vault_fleet_pauseCurrent fleet pause state per tenant; upserted on conflict
vault_canary_tokensPlanted tokens; stores token_type, label, value_hash, planted_by, active
vault_canary_firesEvery detected use of a canary; mttd_seconds computed by DB trigger from planted_at