Vault

codai Vault keeps your credentials encrypted on your own devices: clients seal every item (XChaCha20-Poly1305, keys wrapped with the X-Wing post-quantum hybrid) before upload, so /v1/vault/* stores and syncs ciphertext only. Agents never receive secret values. They see a catalogue of handles ({{vault:<slug>}}), ask for a policy decision (tiers t0-t4 or deny), wait for your approval when the tier requires it, and call brokered HTTPS endpoints whose responses are redacted.

The SDKs expose the whole surface as codai.vault (TypeScript and Python), with device keys under codai.vault.devices.

Device keys and step-upCopy Anchor Link

An approval proves who decided. Besides the v1 signature of your vault key, a decision can carry a v2 proof from a hardware-backed device key (Android Keystore on phone and watch, Windows Hello on desktop) or from a passkey. Device keys are public keys only; the private key never leaves the secure hardware of the device.

EnrolmentCopy Anchor Link

1. POST /v1/vault/devices/challenge returns a single-use nonce (32 random bytes, base64url) valid for 5 minutes.
2. The device creates its key and both your vault key and the device key sign the enrolment message: codai-vault/device-enroll/v1|<device_id>|<kind>|<spki_sha256>|<nonce>, where spki_sha256 is base64url(SHA-256(SubjectPublicKeyInfo DER)).
3. POST /v1/vault/devices sends device_id (android-…, wear-… or desktop-…), kind (android_keystore or windows_hello), name, surface (phone, wear or desktop), public_key, nonce, vault_signature, device_signature and, when available, an attestation. The answer is 201 { device }.

Re-enrolling the same device_id replaces its key. GET /v1/vault/devices lists your keys (revoked ones included), PATCH /v1/vault/devices/{id} renames one and DELETE /v1/vault/devices/{id} revokes it at once: its next proof answers 403 device_revoked.

All binary values are base64url without padding. Android signs with ECDSA P-256 SHA-256 (DER); Windows Hello signs with RSASSA-PKCS1-v1_5 SHA-256.

Attestation kindsCopy Anchor Link

Android keys must send attestation: { android_chain: [...] } (leaf first); the attestation challenge is the nonce bytes and the attested key must equal public_key. Windows Hello keys may send attestation: { tpm: { attestation, cert_chain } }; without it the key is hello-unattested, with an invalid one the enrolment fails. Errors: 400 invalid_nonce, possession_failed, attestation_required, attestation_invalid; 403 invalid_signature; 409 device_id_taken; 503 revocation_unavailable (Google's revocation list could not be checked, retry later).

Approval messagesCopy Anchor Link

• v1 (vault key): codai-vault/approve/v1|<approval_id>|<action_hash>|<decision>|<scope>, sent as signature.
• v2 (device key or passkey): codai-vault/approve/v2|<approval_id>|<action_hash>|<decision>|<scope>|<device_id>, sent as proof: { type: 'device', device_id, signature }.
• v3 (device key or passkey + number matching): codai-vault/approve/v3|<approval_id>|<action_hash>|<decision>|<scope>|<device_id>|<preview_digest>|<match_number>, sent with match_number next to proof. preview_digest is base64url(SHA-256) of the canonical text of request.preview (codai-vault/preview/v1, then title, agent, mode, host, action, purpose, task as key=value lines, with \, newline and CR escaped), so the signature covers exactly what the approver saw.
• passkey: the WebAuthn challenge is base64url(SHA-256(the v2 message with device id passkey)), sent as proof: { type: 'passkey', response }.

Send at most one of signature and proof. step_up_acr is still accepted but ignored: a client-claimed step-up proves nothing.

Rules by tierCopy Anchor Link

• Deny needs no proof (a notification Deny button is enough).
• T3 approve accepts a valid v1 signature, device proof or passkey proof.
• T4 approve requires a device or passkey proof; a v1 signature answers 403 step_up_required. Every attestation kind above qualifies today.
• Wear is T3-only: a watch key cannot be attested as biometric-bound, so a proof from a wear device on a T4 approval answers 403 wear_t3_only.
• Number matching: every T3/T4 request gets a 2-digit match_number, returned only to the agent (/vault/use, /vault/http, /vault/resolve). The approver sees request.preview and three request.match_choices, never the number. A T4 approve on such a request needs match_number with a v3 proof: none answers 403 match_required; a wrong number denies the request at once and answers 403 match_mismatch. T3 approvals and denies still accept v1/v2.

Other proof errors (403): invalid_signature, unknown_device, device_revoked, passkey_invalid.

curl -X POST 'https://ai.codai.ro/v1/vault/devices/challenge'

{  "nonce": "string",  "expires_at": "2019-08-24T14:15:22Z"}

curl -X POST 'https://ai.codai.ro/v1/vault/devices' \  -H 'Content-Type: application/json' \  -d '{  "device_id": "string",  "kind": "android_keystore",  "name": "string",  "surface": "phone",  "public_key": "string",  "nonce": "string",  "vault_signature": "string",  "device_signature": "string"}'

{  "device": {    "id": "string",    "kind": "android_keystore",    "name": "string",    "surface": "phone",    "public_key": "string",    "attestation": "android-strongbox",    "attestation_info": {},    "created_at": "2019-08-24T14:15:22Z",    "last_used_at": "2019-08-24T14:15:22Z",    "revoked_at": "2019-08-24T14:15:22Z"  }}

curl -X GET 'https://ai.codai.ro/v1/vault/devices'

{  "devices": [    {      "id": "string",      "kind": "android_keystore",      "name": "string",      "surface": "phone",      "public_key": "string",      "attestation": "android-strongbox",      "attestation_info": {},      "created_at": "2019-08-24T14:15:22Z",      "last_used_at": "2019-08-24T14:15:22Z",      "revoked_at": "2019-08-24T14:15:22Z"    }  ]}

curl -X PATCH 'https://ai.codai.ro/v1/vault/devices/string' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'

{  "device": {    "id": "string",    "kind": "android_keystore",    "name": "string",    "surface": "phone",    "public_key": "string",    "attestation": "android-strongbox",    "attestation_info": {},    "created_at": "2019-08-24T14:15:22Z",    "last_used_at": "2019-08-24T14:15:22Z",    "revoked_at": "2019-08-24T14:15:22Z"  }}

curl -X DELETE 'https://ai.codai.ro/v1/vault/devices/string'

{  "ok": true}

curl -X POST 'https://ai.codai.ro/v1/vault/approvals/497f6eca-6276-4993-bfeb-53cbbbba6f08/decide' \  -H 'Content-Type: application/json' \  -d '{  "decision": "approve",  "scope": "once"}'

{}