Org

Add a source-access wrapper for the caller's own encryption key

vault-recovery-custody (consult round 1): the member's vault encryption private key is held only as encrypted wrappers — one per PRF-capable passkey (webauthn_prf, KEK derived from that credential's WebAuthn PRF output) plus at most one recovery_code wrapper (KEK derived from the source recovery code, a decrypt-only secret that never authenticates). Every wrapper is born PENDING and counts for nothing until the possession-proof activation (POST …/wrappers/{wrapper_id}/activate) — the response carries the ECDH challenge. The swrap2 blob is sealed client-side with a canonical context binding (principal, key id, wrapper id, kind, credential, FULL public-key hash, RP id) as both HKDF info and AAD; the server cannot open or validate the ciphertext. For webauthn_prf, the credential is SERVER-derived: pass elevation_id from a gitvault.wrapper.add step-up verify — the client is never authoritative for the credential id. Adding a device is adding a wrapper — the published key and ek_ fingerprint never change. For a NEW (random-key) enrollment, use the atomic form: pass wrappers[] on POST /agent/v1/whoami/encryption-key so the key row and its first wrapper commit in one transaction (both pending until activation).

post/agent/v1/source-access/wrappers

Request

  • Base URL: https://api.run402.com
  • URL: https://api.run402.com/agent/v1/source-access/wrappers
  • Auth: one of:
    • API key in header SIGN-IN-WITH-X
    • HTTP bearer

Headers

SIGN-IN-WITH-Xstring required

SIWX auth header — base64-encoded JSON payload containing a signed CAIP-122 (EIP-4361) message. See https://docs.x402.org/extensions/sign-in-with-x.

Request body

wrapper_idstring uuid required

Client-minted wrapper row UUID — bound inside the sealed context, so the caller mints it before sealing.

kind'webauthn_prf' | 'recovery_code' required
wrapper_ciphertextstring required

swrap2_ + base64url(kdf_salt32 ‖ nonce24 ‖ XChaCha20-Poly1305 ciphertext) sealing the 32-byte private scalar under the kind's KEK with the canonical context as AAD.

elevation_idstring uuid

Required for webauthn_prf: the single-use gitvault.wrapper.add elevation from step-up verify — the server takes the credential id from the VERIFIED assertion it records.

Response

Pending wrapper created — activate it with the returned possession challenge

wrapper_idstring uuid
encryption_key_idstring uuid
kind'webauthn_prf' | 'recovery_code'
state'pending'
format_versionstring
credential_subjectstring nullable
blob_sha256string
created_atstring date-time

Changes

No recorded changes to this operation across all 1 revision of this API.