Repository Public
1openapi: 3.1.02info:3 title: SP Vault API4 version: 1.0.05 description: >6 The server stores ciphertext and public keys only (docs/crypto-spec/SPV1.md). Every resource is authorized7 server-side from the session's account; client-supplied membership is never trusted. Typed clients:8 apps/web/src/core/engine.ts (TypeScript) and apple/SharedVaultKit (Swift).9 Authentication: browsers use the HttpOnly cookie `__Host-spv` and must send `X-SPV: 1` and a same-origin `Origin`10 on writes; native clients send `X-SPV-Client: native` at sign-in and then `Authorization: Bearer <token>`.11 Errors: `{ "error": "<code>", "message": "<text>" }`. `401 reauth_required` means a step-up is needed.12servers: [{ url: https://vault.spboucher.ai }]13components:14 securitySchemes:15 session: { type: apiKey, in: cookie, name: __Host-spv }16 bearer: { type: http, scheme: bearer }17 workload: { type: apiKey, in: header, name: X-SPV-Sig, description: "ECDSA P-256 request signature with X-SPV-Agent, X-SPV-Ts, X-SPV-Nonce (SPV1 §11)" }18 schemas:19 Uuid: { type: string, format: uuid }20 B64u: { type: string, pattern: "^[A-Za-z0-9_-]+$" }21 PublicKey: { allOf: [{ $ref: "#/components/schemas/B64u" }], description: "65-byte X9.63 P-256 point (87 chars)" }22 Signature: { allOf: [{ $ref: "#/components/schemas/B64u" }], description: "64-byte raw r||s (86 chars)" }23 Envelope:24 type: object25 additionalProperties: false26 required: [v, alg, kid, salt, nonce, ct]27 properties: { v: { const: 1 }, alg: { const: 1 }, kid: { type: integer, minimum: 1 }, salt: { $ref: "#/components/schemas/B64u" }, nonce: { $ref: "#/components/schemas/B64u" }, ct: { $ref: "#/components/schemas/B64u" } }28 Keyset: { type: object, required: [nonce, ct], properties: { nonce: { $ref: "#/components/schemas/B64u" }, ct: { $ref: "#/components/schemas/B64u" } } }29 Recovery: { type: object, required: [epoch, envelope, authHash], properties: { epoch: { type: integer }, envelope: { $ref: "#/components/schemas/B64u" }, authHash: { $ref: "#/components/schemas/B64u" } } }30 DeviceNew:31 type: object32 required: [deviceId, encPub, sigPub, createdAt, cert, arkEnvelope, platform, hardware]33 properties: { deviceId: { $ref: "#/components/schemas/Uuid" }, encPub: { $ref: "#/components/schemas/PublicKey" }, sigPub: { $ref: "#/components/schemas/PublicKey" }, createdAt: { type: string, format: date-time }, cert: { $ref: "#/components/schemas/Signature" }, arkEnvelope: { $ref: "#/components/schemas/B64u" }, platform: { type: string, maxLength: 48 }, hardware: { type: boolean } }34 Grant:35 type: object36 required: [vaultId, epoch, memberAccountId, role, envelope, granterAccountId, sig]37 properties: { vaultId: { $ref: "#/components/schemas/Uuid" }, epoch: { type: integer }, memberAccountId: { $ref: "#/components/schemas/Uuid" }, role: { enum: [owner, editor, reader] }, envelope: { $ref: "#/components/schemas/B64u" }, granterAccountId: { $ref: "#/components/schemas/Uuid" }, sig: { $ref: "#/components/schemas/Signature" } }38 Account:39 type: object40 properties: { accountId: { $ref: "#/components/schemas/Uuid" }, handle: { type: string }, sigPub: { $ref: "#/components/schemas/PublicKey" }, encPub: { $ref: "#/components/schemas/PublicKey" }, keyset: { $ref: "#/components/schemas/Keyset" }, recoveryEpoch: { type: integer }, keyEpoch: { type: integer } }41 Change:42 type: object43 properties: { id: { $ref: "#/components/schemas/Uuid" }, type: { enum: [item, vault-meta, collection] }, rev: { type: integer }, envelope: { $ref: "#/components/schemas/Envelope" }, deleted: { type: boolean }, seq: { type: integer }, updatedAt: { type: string, format: date-time }, deviceId: { type: [string, "null"] }, attachments: { type: array, items: { $ref: "#/components/schemas/Uuid" } } }44 Error: { type: object, required: [error], properties: { error: { type: string }, message: { type: string } } }45security: [{ session: [] }, { bearer: [] }]46paths:47 /api/health/ready: { get: { security: [], summary: Liveness and database check, responses: { "200": { description: ok } } } }48 /.well-known/apple-app-site-association: { get: { security: [], summary: Associated domains (webcredentials) for the native apps, responses: { "200": { description: ok } } } }4950 /api/v1/auth/register/options:51 post: { security: [], summary: "Start account creation (single-use invitation). Body {invite, handle, accountId}. Returns {challengeId, options} (WebAuthn creation options).", responses: { "200": { description: ok }, "403": { description: invalid_invite }, "409": { description: handle_taken } } }52 /api/v1/auth/register/verify:53 post: { security: [], summary: "Create the account, first passkey, first device and personal vault atomically. Body {challengeId, response, sigPub, encPub, keyset, recovery, device: DeviceNew, vault: {vaultId, grant, meta: {recordId, envelope}}}.", responses: { "200": { description: "{account}; sets the session (cookie) or returns {token} to native clients" } } }54 /api/v1/auth/login/options:55 post: { security: [], summary: "WebAuthn request options for a discoverable credential (no handle: no enumeration).", responses: { "200": { description: "{challengeId, options}" } } }56 /api/v1/auth/login/verify:57 post: { security: [], summary: "Body {challengeId, response, device?: {deviceId, proof}}. With a valid device proof → device session + arkEnvelope; otherwise a *pending* session that can only pair or recover.", responses: { "200": { description: "{kind: device|pending, account, arkEnvelope?}" }, "401": { description: "authentication_failed | device_unknown" } } }58 /api/v1/auth/logout: { post: { summary: End the current session, responses: { "200": { description: ok } } } }59 /api/v1/auth/session: { get: { summary: "Current session {kind, deviceId, account, strong}", responses: { "200": { description: ok } } } }60 /api/v1/auth/stepup/options: { post: { summary: "Challenge for a fresh authentication", responses: { "200": { description: "{challengeId, options}" } } } }61 /api/v1/auth/stepup/verify: { post: { summary: "Body {challengeId, response} (passkey) or {challengeId, deviceProof} (native, biometric-gated device key). Marks the session strong for 5 minutes; returns {arkEnvelope}.", responses: { "200": { description: ok } } } }62 /api/v1/auth/passkeys:63 get: { summary: List passkeys (ids, labels, dates), responses: { "200": { description: ok } } }64 /api/v1/auth/passkeys/options: { post: { summary: "Add a passkey (device session + step-up, or recovery session)", responses: { "200": { description: ok } } } }65 /api/v1/auth/passkeys/verify: { post: { summary: "Body {challengeId, response, label?}", responses: { "200": { description: ok } } } }66 /api/v1/auth/passkeys/{id}: { delete: { summary: Remove a passkey (step-up; not the last one), parameters: [{ name: id, in: path, required: true, schema: { type: string } }], responses: { "200": { description: ok } } } }6768 /api/v1/devices: { get: { summary: "Certified devices of the account {current, account, devices[]} — clients verify every certificate", responses: { "200": { description: ok } } } }69 /api/v1/devices/{id}: { delete: { summary: "Revoke a device: envelope erased, sessions ended (step-up)", parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }70 /api/v1/pairings: { post: { summary: "New device (pending session) publishes {pairingId, deviceId, encPub, sigPub, createdAt, tag, platform, hardware}; expires in 5 minutes", responses: { "200": { description: ok } } } }71 /api/v1/pairings/{id}:72 parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }]73 get: { summary: "Trusted device: the request to verify. New device: status and, once approved, {cert, arkEnvelope, account}", responses: { "200": { description: ok } } }74 /api/v1/pairings/{id}/approve: { post: { summary: "Trusted device uploads {cert, arkEnvelope} (step-up)", parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }75 /api/v1/pairings/{id}/reject: { post: { summary: Reject, parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }76 /api/v1/pairings/{id}/complete: { post: { summary: "New device proves its signing key {proof}; pending session becomes a device session", parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }7778 /api/v1/recovery/start: { post: { security: [], summary: "Body {handle} → {accountId, epoch}; unknown handles get a stable decoy", responses: { "200": { description: ok } } } }79 /api/v1/recovery/verify: { post: { security: [], summary: "Body {accountId, auth} → recovery session + {envelope, epoch, account}. Heavily rate limited.", responses: { "200": { description: ok }, "401": { description: authentication_failed }, "429": { description: rate_limited } } } }80 /api/v1/recovery/enroll: { post: { summary: "Recovery session: enrol the fresh device {device: DeviceNew}", responses: { "200": { description: ok } } } }81 /api/v1/recovery:82 get: { summary: "Recovery envelope + epoch for encrypted backups (step-up)", responses: { "200": { description: ok } } }83 /api/v1/recovery/rotate: { post: { summary: "Replace recovery material {epoch, envelope, authHash} (step-up)", responses: { "200": { description: ok }, "409": { description: conflict } } } }84 /api/v1/account/rekey: { post: { summary: "New ARK: {keyEpoch, keyset, recovery, devices: [{deviceId, arkEnvelope}]} applied atomically for every active device (step-up)", responses: { "200": { description: ok }, "409": { description: conflict } } } }85 /api/v1/accounts/lookup: { get: { summary: "Public keys of an account by handle (for sharing)", parameters: [{ name: handle, in: query, required: true, schema: { type: string } }], responses: { "200": { description: "{accountId, handle, sigPub, encPub}" }, "404": { description: not_found } } } }8687 /api/v1/vaults: { post: { summary: "Create a vault {vaultId, grant, meta: {recordId, envelope}}", responses: { "200": { description: ok } } } }88 /api/v1/vaults/{vid}: { delete: { summary: Delete a vault (owner; step-up); purged after 30 days, parameters: [{ name: vid, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }89 /api/v1/sync:90 post:91 summary: "Deltas after per-vault cursors: body {cursors: {vaultId: seq}} → {serverTime, vaults: [{vaultId, epoch, seq, ownerId, role, more, grants[], members[], changes: Change[]}]} (500 changes per vault per call)"92 responses: { "200": { description: ok } }93 /api/v1/vaults/{vid}/records/{rid}:94 parameters: [{ name: vid, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }, { name: rid, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }]95 put:96 summary: "Write a record revision. Body {type, baseRev, envelope, deleted, attachments[]}; header Idempotency-Key. baseRev must equal the current revision."97 responses: { "200": { description: "{rev, seq}" }, "409": { description: "conflict {current: Change|null} or stale_key {epoch}" }, "403": { description: read_only } }98 /api/v1/vaults/{vid}/records/{rid}/history: { get: { summary: Up to 20 previous encrypted revisions, parameters: [{ name: vid, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }, { name: rid, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }99 /api/v1/vaults/{vid}/members: { post: { summary: "Add or change a member: {grants: Grant[]} covering the current epoch (owner; step-up)", parameters: [{ name: vid, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }100 /api/v1/vaults/{vid}/rotate: { post: { summary: "New key epoch: {epoch, grants: one per remaining member, remove: accountId[]} (owner; step-up)", parameters: [{ name: vid, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok }, "409": { description: conflict } } } }101102 /api/v1/vaults/{vid}/attachments: { post: { summary: "Declare an upload {id, chunks, size} → {uploaded: number[]} (resumable; 100 MiB per file, 5 GiB per account)", parameters: [{ name: vid, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok }, "413": { description: quota } } } }103 /api/v1/attachments/{aid}/chunks/{i}:104 parameters: [{ name: aid, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }, { name: i, in: path, required: true, schema: { type: integer } }]105 put: { summary: "Upload one encrypted chunk (application/octet-stream, exactly 1 MiB + 16 bytes except the last)", responses: { "200": { description: ok } } }106 get: { summary: Download one encrypted chunk, responses: { "200": { description: bytes } } }107 /api/v1/attachments/{aid}/complete: { post: { summary: Mark an upload complete (all chunks present), parameters: [{ name: aid, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok }, "409": { description: incomplete } } } }108109 /api/v1/shares:110 post: { summary: "Relay: {id, kind: account|link, recipientAccountId?, box, sig?, authHash?, expiresInSec, maxViews?} (step-up)", responses: { "200": { description: ok } } }111 get: { summary: "Sent and received shares (metadata only)", responses: { "200": { description: ok } } }112 /api/v1/shares/{id}/open: { post: { summary: "Recipient retrieves the box (counts a view)", parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: "{box: {ct, sig}, senderId, senderHandle, senderSigPub}" }, "404": { description: not_found } } } }113 /api/v1/shares/{id}: { delete: { summary: Revoke and erase the ciphertext (sender), parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }114 /api/v1/public/shares/{id}: { post: { security: [], summary: "Public link: body {auth} derived from the URL-fragment secret → {box}", parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok }, "404": { description: not_found }, "410": { description: gone } } } }115116 /api/v1/audit: { get: { summary: "Hash-chained events, newest first (100 per page, ?before=id)", responses: { "200": { description: ok } } } }117 /api/v1/audit/client: { post: { summary: "Record a client-side sensitive action {kind} (step-up)", responses: { "200": { description: ok } } } }118 /api/v1/events: { get: { summary: "Server-sent events: content-free pokes {type: sync|devices|pairing|shares|approval|activity}", responses: { "200": { description: text/event-stream } } } }119 /api/v1/breach/range/{prefix}: { get: { summary: "k-anonymity range relay (5 hex chars of SHA-1)", parameters: [{ name: prefix, in: path, required: true, schema: { type: string, pattern: "^[0-9A-F]{5}$" } }], responses: { "200": { description: text/plain } } } }120121 /api/v1/connect: { get: { summary: "Connect state: {enabled, killed, identities, secrets (no values), grants, approvals}", responses: { "200": { description: ok } } } }122 /api/v1/connect/identities: { post: { summary: "Create a workload identity {id, name, kind: service|agent, pub} (step-up)", responses: { "200": { description: ok } } } }123 /api/v1/connect/identities/{id}: { delete: { summary: Revoke an identity with its grants and leases, parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }124 /api/v1/connect/secrets: { post: { summary: "Create a managed secret {id, name, kind, config, value, rotateEveryDays?, expiresAt?} (step-up). NOT zero-knowledge.", responses: { "200": { description: ok } } } }125 /api/v1/connect/secrets/{id}/value: { put: { summary: "Rotate the value (ends leases) (step-up)", parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }126 /api/v1/connect/secrets/{id}: { delete: { summary: Delete a managed secret (step-up), parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }127 /api/v1/connect/grants: { post: { summary: "Grant {id, identityId, secretId, mode: operate|read, approval: never|lease|each, leaseTtlSec, maxUses?, expiresInSec, constraints: {methods?, pathPrefix?}} (step-up). Agents cannot have approval=never.", responses: { "200": { description: ok } } } }128 /api/v1/connect/grants/{id}: { delete: { summary: Revoke a grant, parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }129 /api/v1/connect/approvals/{id}: { post: { summary: "Human decision {approve} (step-up)", parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }130 /api/v1/connect/kill: { post: { summary: "Kill switch {engaged}. Engaging needs no step-up; releasing does.", responses: { "200": { description: ok } } } }131132 /api/v1/agent/grants: { get: { security: [{ workload: [] }], summary: Grants usable by the calling identity, responses: { "200": { description: ok } } } }133 /api/v1/agent/approvals/{id}: { get: { security: [{ workload: [] }], summary: Status of an approval request, parameters: [{ name: id, in: path, required: true, schema: { $ref: "#/components/schemas/Uuid" } }], responses: { "200": { description: ok } } } }134 /api/v1/agent/use:135 post:136 security: [{ workload: [] }]137 summary: "Use a secret: {grantId, reason?, approvalId?, http: {method, url, headers, body?} | sign: {payload} | read: true}. The policy engine answers 200 (result), 202 {status: approval_required, approvalId} or 403 {error: denied, message}."138 responses: { "200": { description: result }, "202": { description: approval required }, "403": { description: denied } }139