SPB Git

Repository Public

openapi.yaml 18.2 KB 139 lines yaml

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
Files main
Menu

Theme