@inklok/api-spec 7.8.2 → 7.8.4

package/openapi.yaml

@@ -8,7 +8,7 @@ info:
     Authenticate using an API key or bearer token, then use the resources below to manage
     templates, agreements, documents, and signing. For your first integration, start with
     the Quick Start guide.
-  version: "7.8.2"
+  version: "7.8.4"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -239,6 +239,96 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /v1/crypto/identities/{publicKeyId}/recovery:
+    get:
+      operationId: getCryptoIdentityRecoveryBundleV1
+      summary: Get crypto identity recovery bundle
+      x-visibility: internal
+      description: |
+        Returns the encrypted client-side recovery bundle for an authorized account crypto identity. Recovery Keys are never accepted by this API.
+      x-required-roles: [workflow-editor, workflow-operator, agreement-auditor, organization-admin]
+      tags:
+        - Crypto Identities
+      parameters:
+        - name: publicKeyId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: X-Inklok-Org-Id
+          in: header
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Encrypted recovery bundle
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [bundle]
+                properties:
+                  bundle:
+                    $ref: '#/components/schemas/CryptoIdentityRecoveryBundle'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    put:
+      operationId: putCryptoIdentityRecoveryBundleV1
+      summary: Replace crypto identity recovery bundle
+      x-visibility: internal
+      description: |
+        Stores an encrypted client-side recovery bundle for an authorized account crypto identity. The plaintext private key and Recovery Key are never accepted.
+      x-required-roles: [workflow-editor, workflow-operator, agreement-auditor, organization-admin]
+      tags:
+        - Crypto Identities
+      parameters:
+        - name: publicKeyId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: X-Inklok-Org-Id
+          in: header
+          required: false
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CryptoIdentityRecoveryBundle'
+      responses:
+        '200':
+          description: Stored encrypted recovery bundle
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [bundle]
+                properties:
+                  bundle:
+                    $ref: '#/components/schemas/CryptoIdentityRecoveryBundle'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
         '500':
           $ref: '#/components/responses/InternalServerError'
 
@@ -5858,6 +5948,62 @@ components:
           type: string
           format: date-time
           readOnly: true
+        recoveryBundle:
+          allOf:
+            - $ref: '#/components/schemas/CryptoIdentityRecoveryBundle'
+          writeOnly: true
+          description: Optional encrypted recovery bundle used only when first registering an account identity.
+
+    CryptoIdentityRecoveryBundle:
+      type: object
+      description: Client-encrypted account private-key recovery payload. The Recovery Key is never included.
+      required: [identityId, encryptedPrivateKey, salt, iv, kdf, kdfVersion, kdfParams, encryptionAlg, encryptionVersion, aad]
+      properties:
+        identityId:
+          type: string
+        encryptedPrivateKey:
+          type: string
+          description: Base64 AES-GCM ciphertext of the account private key export.
+        salt:
+          type: string
+        iv:
+          type: string
+        kdf:
+          type: string
+          enum: [PBKDF2-SHA-256]
+        kdfVersion:
+          type: integer
+          enum: [1]
+        kdfParams:
+          type: object
+          required: [iterations, hash, saltBytes]
+          properties:
+            iterations:
+              type: integer
+              minimum: 310000
+            hash:
+              type: string
+              enum: [SHA-256]
+            saltBytes:
+              type: integer
+              enum: [16]
+        encryptionAlg:
+          type: string
+          enum: [AES-GCM-256]
+        encryptionVersion:
+          type: integer
+          enum: [1]
+        aad:
+          type: string
+          description: Identity-bound AES-GCM additional authenticated data.
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+        updatedAt:
+          type: string
+          format: date-time
+          readOnly: true
 
     AppendExecutionEventRequest:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inklok/api-spec",
-  "version": "7.8.2",
+  "version": "7.8.4",
   "description": "Canonical OpenAPI specification for the Inklok public API.",
   "main": "openapi.yaml",
   "license": "MIT",