@inklok/api-spec 7.8.1 → 7.8.2

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.1"
+  version: "7.8.2"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -2833,6 +2833,7 @@ paths:
                         value_encrypted:
                           type: string
                           nullable: true
+                          description: JSON-serialized ScopedEncryptedFieldValue (v2). The server stores this string verbatim only after structural and authoritative binding validation.
                         required:
                           type: boolean
         '401':
@@ -2924,6 +2925,8 @@ paths:
                         type: string
                       value_encrypted:
                         type: string
+                        minLength: 1
+                        description: JSON-serialized ScopedEncryptedFieldValue. The server validates its exact v2 envelope, authoritative keyScopeId, and canonical AAD before persistence.
                 metadata:
                   type: object
                   additionalProperties: true
@@ -5628,6 +5631,7 @@ components:
         type:
           type: string
           enum: [PARTY_PRIVATE, SHARED, ORG_AUTHORIZED, WORKSPACE_AUTHORIZED]
+          description: Current managed signing creation accepts PARTY_PRIVATE and SHARED. Other enum values are reserved for future modes and are rejected at creation time.
         partyId:
           type: string
         members:
@@ -5647,6 +5651,7 @@ components:
         protectionMode:
           type: string
           enum: [MANAGED, STRICT_ZK]
+          description: Current signing creation accepts MANAGED only. STRICT_ZK is reserved and not enabled.
         createdAt:
           type: string
           format: date-time
@@ -5727,6 +5732,37 @@ components:
         kmsWrappedScopeDek:
           type: string
 
+    ScopedEncryptedFieldValue:
+      type: object
+      additionalProperties: false
+      description: |
+        Parsed form of the JSON string carried by signing field value_encrypted.
+        v2 binds AES-GCM authentication to the agreement, authoritative scope,
+        field, and encryption version. The server validates structure and AAD
+        metadata but does not decrypt managed values.
+      required: [alg, keyScopeId, encryptionVersion, ciphertext, iv, authTag, aad]
+      properties:
+        alg:
+          type: string
+          enum: [AES-256-GCM]
+        keyScopeId:
+          type: string
+        encryptionVersion:
+          type: integer
+          enum: [2]
+        ciphertext:
+          type: string
+          description: Canonical base64 ciphertext bytes, without the GCM tag.
+        iv:
+          type: string
+          description: Canonical base64 12-byte AES-GCM IV.
+        authTag:
+          type: string
+          description: Canonical base64 16-byte AES-GCM authentication tag.
+        aad:
+          type: string
+          description: 'Exact UTF-8 AAD string: inklok:field-value:v2:{"agreementId":"…","keyScopeId":"…","fieldId":"…","encryptionVersion":2}'
+
     CryptoPrincipal:
       type: object
       required: [principalId, type, subjectId]

package/package.json

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