{ "openapi": "3.1.0", "info": { "title": "Domotronik Secure Vault API", "version": "0.1.0", "description": "Almacenamiento de ciphertext cifrado en cliente. Recovery/Web3Auth pendientes. Sin endpoints administrativos públicos. DELETE crea tombstone; cuotas cuentan revisiones retenidas. Integración debe custodiar independientemente U y T." }, "servers": [ { "url": "https://securevault.dmtk-corp.com" } ], "security": [ { "bearer": [] } ], "paths": { "/health/live": { "get": { "operationId": "health_live", "summary": "health_live", "description": "", "parameters": [], "responses": { "200": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/health/ready": { "get": { "operationId": "health_ready", "summary": "health_ready", "description": "", "parameters": [], "responses": { "200": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/demo-api/sessions": { "post": { "operationId": "createDemoSession", "summary": "createDemoSession", "description": "Sandbox anónimo, solo si SV_DEMO_ENABLED. Origin propio y X-SV-Demo:1 obligatorios. Tenant aislado temporal, 64KiB/registro, 8 revisiones. No da acceso a tenants normales.", "parameters": [ { "in": "header", "name": "X-SV-Demo", "required": true, "schema": { "const": "1" } } ], "responses": { "200": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoSession" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/grants": { "post": { "operationId": "issueGrant", "summary": "issueGrant", "description": "Solo credencial server del tenant; el backend tenant autentica y determina el sujeto.", "parameters": [], "responses": { "200": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grant" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRequest" } } } } } }, "/v1/grants/revoke": { "post": { "operationId": "revokeGrant", "summary": "revokeGrant", "description": "Solo server tenant. Revoca jti inmediatamente para nuevas peticiones.", "parameters": [], "responses": { "204": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeRequest" } } } } } }, "/v1/vaults": { "post": { "operationId": "createVault", "summary": "createVault", "description": "vault:create; subject del grant salvo credencial server.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$" }, "description": "24h. Repetir exactamente body e If-Match; cambiar body devuelve 409." } ], "responses": { "201": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vault" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVault" } } } } }, "get": { "operationId": "listVaults", "summary": "listVaults", "description": "vault:read; tenant/sujeto y vaultIds autorizados.", "parameters": [ { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultPage" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/vaults/{vaultId}": { "get": { "operationId": "getVault", "summary": "getVault", "description": "vault:read; ownership.", "parameters": [ { "in": "path", "name": "vaultId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vault" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/vaults/{vaultId}/records": { "post": { "operationId": "createRecord", "summary": "createRecord", "description": "record:create; revision=1, IDs conocidos antes de cifrar.", "parameters": [ { "in": "path", "name": "vaultId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$" }, "description": "24h. Repetir exactamente body e If-Match; cambiar body devuelve 409." } ], "responses": { "201": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "get": { "operationId": "listRecords", "summary": "listRecords", "description": "record:read; incluye tombstones, nunca payload en listado.", "parameters": [ { "in": "path", "name": "vaultId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordPage" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/vaults/{vaultId}/records/{recordId}": { "get": { "operationId": "getRecord", "summary": "getRecord", "description": "record:read; solo ciphertext interior. Tombstone impide lectura histórica.", "parameters": [ { "in": "path", "name": "vaultId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "in": "path", "name": "recordId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "in": "query", "name": "revision", "schema": { "type": "integer", "minimum": 1 }, "description": "Opcional. Metadata record actual, envelope de revisión solicitada; ETag representa estado actual." } ], "responses": { "200": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResult" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "updateRecord", "summary": "updateRecord", "description": "record:update; nueva revisión, nueva DEK y nuevos factores cliente.", "parameters": [ { "in": "path", "name": "vaultId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "in": "path", "name": "recordId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$" }, "description": "24h. Repetir exactamente body e If-Match; cambiar body devuelve 409." }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" }, "description": "ETag fuerte actual; omitir 428, distinto 412." } ], "responses": { "200": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "delete": { "operationId": "deleteRecord", "summary": "deleteRecord", "description": "record:delete; tombstone, no borrado físico inmediato.", "parameters": [ { "in": "path", "name": "vaultId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "in": "path", "name": "recordId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" }, "description": "ETag fuerte actual; omitir 428, distinto 412." } ], "responses": { "204": { "description": "Éxito", "headers": { "Cache-Control": { "schema": { "const": "no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } } }, "400": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error uniforme; 404 también para recurso no autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Grant JWT breve para navegador; credencial svt.* únicamente server-to-server. /v1/grants requiere credencial server." } }, "schemas": { "Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "correlationId" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "Context": { "type": "object", "additionalProperties": false, "required": [ "protocolVersion", "tenantId", "subjectId", "vaultId", "recordId", "revision" ], "properties": { "protocolVersion": { "const": "SVP-1" }, "tenantId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "subjectId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "vaultId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "recordId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483647 } } }, "Envelope": { "type": "object", "additionalProperties": false, "required": [ "context", "suite", "nonce", "ciphertextAndTag" ], "properties": { "context": { "$ref": "#/components/schemas/Context" }, "suite": { "const": "AES-256-GCM-OPTION-A-PRIMITIVE" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" }, "ciphertextAndTag": { "type": "string", "minLength": 22, "maxLength": 11184832, "pattern": "^[A-Za-z0-9_-]+$" } } }, "CreateVault": { "type": "object", "additionalProperties": false, "required": [ "subjectId" ], "properties": { "subjectId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } }, "Vault": { "type": "object", "additionalProperties": false, "required": [ "vaultId", "tenantId", "subjectId", "status", "createdAt" ], "properties": { "vaultId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "tenantId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "subjectId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "status": { "const": "active" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "Record": { "type": "object", "additionalProperties": false, "required": [ "recordId", "tenantId", "subjectId", "vaultId", "revision", "etag", "status", "size", "updatedAt" ], "properties": { "recordId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "tenantId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "subjectId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "vaultId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "revision": { "type": "integer", "minimum": 1 }, "etag": { "type": "string" }, "status": { "enum": [ "active", "deleted" ] }, "size": { "type": "integer", "minimum": 16 }, "updatedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "RecordResult": { "type": "object", "additionalProperties": false, "required": [ "record", "envelope" ], "properties": { "record": { "$ref": "#/components/schemas/Record" }, "envelope": { "$ref": "#/components/schemas/Envelope" } } }, "GrantRequest": { "type": "object", "additionalProperties": false, "required": [ "subjectId", "scopes", "vaultIds" ], "properties": { "subjectId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "scopes": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "enum": [ "vault:create", "vault:read", "record:create", "record:read", "record:update", "record:delete" ] } }, "vaultIds": { "type": "array", "maxItems": 100, "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, "lifetimeSeconds": { "type": "integer", "minimum": 30, "maximum": 900, "default": 300 } } }, "Grant": { "type": "object", "additionalProperties": false, "required": [ "accessToken", "tokenType", "expiresAt", "jti" ], "properties": { "accessToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresAt": { "type": "string", "format": "date-time" }, "jti": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } }, "RevokeRequest": { "type": "object", "additionalProperties": false, "required": [ "jti" ], "properties": { "jti": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } }, "Health": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "enum": [ "live", "ready" ] }, "mode": { "enum": [ "local-fixture", "cloud" ] } } }, "VaultPage": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Vault" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "RecordPage": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "DemoSession": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "subjectId", "vaultId", "accessToken", "expiresAt", "maxBytes", "mode" ], "properties": { "tenantId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "subjectId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "vaultId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "accessToken": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "maxBytes": { "const": 65536 }, "mode": { "enum": [ "cloud", "local-fixture" ] } } } } } }