@inklok/api-spec 7.7.2 → 7.8.1

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.7.2"
+  version: "7.8.1"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -129,7 +129,7 @@ paths:
       summary: List crypto identities
       x-visibility: internal
       description: |
-        Returns RSA-OAEP session public keys visible to the authenticated caller.
+        Returns registered public keys for authenticated crypto principals visible to the caller.
       x-required-roles: [signer, workflow-editor, workflow-operator, agreement-auditor, organization-admin]
       tags:
         - Crypto Identities
@@ -144,7 +144,7 @@ paths:
           required: false
           schema:
             type: string
-            enum: [signer, org-session]
+            enum: [USER, PARTY, ORG_ROLE, WORKSPACE_ROLE]
         - name: subjectId
           in: query
           required: false
@@ -205,7 +205,7 @@ paths:
       summary: Upsert crypto identity
       x-visibility: internal
       description: |
-        Stores a session public key. Private keys are never accepted by this API.
+        Stores a registered public key for a versioned crypto principal. Private keys are never accepted by this API.
       x-required-roles: [signer, workflow-editor, workflow-operator, agreement-auditor, organization-admin]
       tags:
         - Crypto Identities
@@ -1816,6 +1816,12 @@ paths:
           description: Document identifier
           schema:
             type: string
+        - name: executionId
+          in: query
+          required: false
+          description: Required for signer-token access; binds document access to the verified signing execution.
+          schema:
+            type: string
       responses:
         '200':
           description: Base64-encoded document encryption key for client-side decryption
@@ -2564,17 +2570,14 @@ paths:
         '500':
           $ref: '#/components/responses/InternalServerError'
 
-  /v1/agreements/{executionId}/execution-key-envelopes:
+  /v1/agreements/{executionId}/key-envelopes:
     post:
-      operationId: appendAgreementExecutionKeyEnvelopesV1
-      summary: Append agreement execution-key envelopes
+      operationId: appendAgreementKeyEnvelopesV1
+      summary: Append client-created scope key envelopes
       x-visibility: internal
       description: |
-        Issues server-wrapped execution-key envelopes for additional authorized session public keys.
-        The request contains public key IDs only. Inklok wraps the agreement key to
-        the requested RSA-OAEP public keys and never persists plaintext key material.
-        This is a cryptographic access grant event. Inklok commits the envelope append
-        and KEY_ACCESS_GRANTED audit record atomically, or fail the request without changing access.
+        Stores envelopes created by an authorized client. The server validates scope
+        authorization but never unwraps or re-wraps a scope DEK.
       x-required-roles: [workflow-operator, organization-admin]
       tags:
         - Agreements
@@ -2591,25 +2594,27 @@ paths:
           application/json:
             schema:
               type: object
-              required: [publicKeyIds]
+              required: [envelopes]
               properties:
-                publicKeyIds:
+                envelopes:
                   type: array
                   minItems: 1
                   maxItems: 50
                   items:
-                    type: string
+                    $ref: '#/components/schemas/KeyEnvelope'
       responses:
         '200':
-          description: Updated execution-key grant set
+          description: Updated scope envelope set
           content:
             application/json:
               schema:
                 type: object
-                required: [executionKey, appended]
+                required: [envelopes, appended]
                 properties:
-                  executionKey:
-                    $ref: '#/components/schemas/ExecutionKeyGrantSet'
+                  envelopes:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KeyEnvelope'
                   appended:
                     type: integer
         '400':
@@ -3117,18 +3122,17 @@ paths:
           $ref: '#/components/responses/InternalServerError'
       x-inklok-lambda: signing-acknowledge-execution
 
-  /v1/signing/unwrap-deks:
+  /v1/signing/scope-envelopes:
     post:
-      operationId: unwrapSigningDeks
-      summary: Resolve signer-wrapped document keys and execution key envelopes
+      operationId: managedScopeRegrant
+      summary: Regrant authorized managed scope envelopes
       x-visibility: internal
       description: |
-        Returns wrapped key material scoped to the authenticated signer.
-
-        - Requires a signing access token
-        - Returns document key material for current PDF compatibility
-        - Returns executionKey envelopes for client-side sensitive placeholder decryption
-        - Audited for signer access
+        Derives the caller's authorized managed scopes from the verified Cognito
+        membership or signer token, recovers those scope DEKs inside the managed
+        recovery boundary, and returns only RSA-OAEP envelopes for the caller's
+        validated registered transient public key. The request cannot select scope
+        IDs and the response never contains plaintext values or raw DEKs.
       tags:
         - Signing
       security:
@@ -3139,58 +3143,35 @@ paths:
           application/json:
             schema:
               type: object
-              required: [executionId]
+              required: [executionId, destinationPublicKeyId]
               properties:
                 executionId:
                   type: string
+                destinationPublicKeyId:
+                  type: string
             example:
               executionId: "exec_123"
+              destinationPublicKeyId: "session_key_123"
       responses:
         '200':
-          description: Wrapped key material for signer-visible document and execution key envelopes
+          description: Scoped managed envelopes for the authenticated principal
           content:
             application/json:
               schema:
                 type: object
-                required: [documentDek, placeholders]
+                required: [keyScopes, envelopes]
                 properties:
-                  documentDek:
-                    type: object
-                    required: [encrypted, alg]
-                    properties:
-                      encrypted:
-                        type: string
-                      alg:
-                        type: string
-                        enum: [KMS-WRAPPED-BASE64, RSA-OAEP]
-                  placeholders:
-                    type: object
-                    description: Reserved empty map; placeholder values use executionKey envelopes.
-                    additionalProperties:
-                      type: object
-                      required: [encrypted, alg]
-                      properties:
-                        encrypted:
-                          type: string
-                        alg:
-                          type: string
-                          enum: [KMS-WRAPPED-BASE64, RSA-OAEP]
-                  executionKey:
-                    $ref: '#/components/schemas/ExecutionKeyGrantSet'
-              example:
-                documentDek:
-                  encrypted: "base64..."
-                  alg: "KMS-WRAPPED-BASE64"
-                placeholders: {}
-                executionKey:
-                  keyId: "ek_01H..."
-                  alg: "INKLOK-EK-AES-256-GCM-RSA-OAEP-256"
+                  keyScopes:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KeyScope'
                   envelopes:
-                    - keyId: "ek_01H..."
-                      subjectId: "party_abc"
-                      subjectType: "signer"
-                      alg: "RSA-OAEP-256"
-                      wrappedKey: "base64..."
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KeyEnvelope'
+              example:
+                keyScopes: []
+                envelopes: []
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -3201,7 +3182,7 @@ paths:
           $ref: '#/components/responses/NotFound'
         '500':
           $ref: '#/components/responses/InternalServerError'
-      x-inklok-lambda: signing-unwrap-deks
+      x-inklok-lambda: managed-scope-regrant
 
 components:
   securitySchemes:
@@ -4616,7 +4597,7 @@ components:
           type: string
           nullable: true
         plan:
-          $ref: '#/components/schemas/Plan'
+          $ref: '#/components/schemas/PlatformPlan'
         totalApiRequests:
           type: integer
           minimum: 0
@@ -5619,88 +5600,203 @@ components:
             $ref: '#/components/schemas/CreateExecutionParticipantInput'
         crypto:
           type: object
-          required: [executionKey]
+          required: [keyScopes]
           description: Security material used to protect agreement field values.
           properties:
-            executionKey:
-              $ref: '#/components/schemas/ExecutionKeyGrantSet'
-
-    ExecutionKeyGrantSet:
+            keyScopes:
+              type: array
+              minItems: 1
+              items:
+                $ref: '#/components/schemas/KeyScope'
+            envelopes:
+              type: array
+              items:
+                $ref: '#/components/schemas/KeyEnvelope'
+            managedRecoveryCapabilities:
+              type: array
+              items:
+                $ref: '#/components/schemas/ManagedRecoveryCapability'
+
+    KeyScope:
       type: object
-      description: Security metadata used to protect agreement field values for authorized readers.
-      required: [keyId, alg, envelopes]
+      required: [keyScopeId, type, version]
       properties:
-        keyId:
+        keyScopeId:
           type: string
-          description: Customer-provided key identifier for this agreement.
-        alg:
+        agreementId:
+          type: string
+        type:
           type: string
-          enum: [INKLOK-EK-AES-256-GCM-RSA-OAEP-256]
-        plaintextKey:
+          enum: [PARTY_PRIVATE, SHARED, ORG_AUTHORIZED, WORKSPACE_AUTHORIZED]
+        partyId:
           type: string
-          writeOnly: true
-          description: Secret key material provided when the agreement is created.
-        encryptedKey:
-          $ref: '#/components/schemas/EncryptedExecutionKey'
-        envelopes:
+        members:
           type: array
-          minItems: 1
           items:
-            $ref: '#/components/schemas/ExecutionKeyEnvelope'
+            type: string
+        authorizationPolicy:
+          type: object
+          additionalProperties: true
+        cryptoPrincipalRefs:
+          type: array
+          items:
+            type: string
+        version:
+          type: integer
+          minimum: 1
+        protectionMode:
+          type: string
+          enum: [MANAGED, STRICT_ZK]
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
 
-    EncryptedExecutionKey:
+    KeyEnvelope:
       type: object
-      readOnly: true
-      required: [alg, ciphertext]
+      required: [envelopeId, keyScopeId, recipientPrincipalId, recipientKeyId, wrappedKey, mode, keyVersion]
       properties:
-        alg:
+        envelopeId:
+          type: string
+        agreementId:
+          type: string
+        keyScopeId:
           type: string
-          enum: [AWS-KMS]
-        ciphertext:
+        recipientPrincipalId:
           type: string
-          description: Base64 protected ciphertext for the execution key.
-        kmsKeyId:
+        recipientKeyId:
           type: string
+        wrappedKey:
+          type: string
+          description: Client-created RSA-OAEP wrapped scope DEK.
+        mode:
+          type: string
+          enum: [MANAGED, STRICT_ZK]
+        keyVersion:
+          type: integer
+          minimum: 1
         createdAt:
           type: string
           format: date-time
+          readOnly: true
+        revokedAt:
+          type: string
+          format: date-time
+          nullable: true
 
-    ExecutionKeyEnvelope:
+    ManagedRecoveryCapability:
       type: object
-      required: [keyId, subjectId, subjectType, alg, wrappedKey]
+      required: [capabilityId, allowedKeyScopeIds, scopes, state]
       properties:
-        keyId:
+        capabilityId:
           type: string
-        subjectId:
+        agreementId:
           type: string
-          description: Signer party ID or authenticated org-session subject ID.
-        subjectType:
+        partyId:
           type: string
-          enum: [signer, org-session]
-        alg:
+        scopes:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/ManagedRecoveryScope'
+        allowedKeyScopeIds:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        kmsKeyVersion:
           type: string
-          enum: [RSA-OAEP-256]
-        wrappedKey:
+        state:
           type: string
-          description: Base64 RSA-OAEP wrapped execution key. Inklok does not unwrap this value.
-        publicKeyId:
+          enum: [ACTIVE, RETIRED, EXPIRED]
+        retiredAt:
           type: string
+          format: date-time
           nullable: true
         createdAt:
           type: string
           format: date-time
           readOnly: true
 
+    ManagedRecoveryScope:
+      type: object
+      required: [keyScopeId, kmsWrappedScopeDek]
+      properties:
+        keyScopeId:
+          type: string
+        kmsWrappedScopeDek:
+          type: string
+
+    CryptoPrincipal:
+      type: object
+      required: [principalId, type, subjectId]
+      properties:
+        principalId:
+          type: string
+        type:
+          type: string
+          enum: [USER, PARTY, ORG_ROLE, WORKSPACE_ROLE]
+        subjectId:
+          type: string
+        currentKeyVersion:
+          type: integer
+          minimum: 1
+
+    PrincipalKey:
+      type: object
+      required: [keyId, principalId, algorithm, publicKey, keyVersion, status, createdAt]
+      properties:
+        keyId:
+          type: string
+        principalId:
+          type: string
+        algorithm:
+          type: string
+          enum: [RSA-OAEP-256]
+        publicKey:
+          type: string
+        keyVersion:
+          type: integer
+          minimum: 1
+        status:
+          type: string
+          enum: [active, retired]
+        createdAt:
+          type: string
+          format: date-time
+        revokedAt:
+          type: string
+          format: date-time
+          nullable: true
+
+    PrincipalKeyEnvelope:
+      type: object
+      required: [principalId, keyVersion, recipientPrincipalId, recipientKeyId, wrappedKey]
+      properties:
+        principalId:
+          type: string
+        keyVersion:
+          type: integer
+          minimum: 1
+        recipientPrincipalId:
+          type: string
+        recipientKeyId:
+          type: string
+        wrappedKey:
+          type: string
+
     CryptoIdentity:
       type: object
-      description: Session public-key metadata used to unwrap execution-key envelopes client-side.
-      required: [publicKeyId, subjectType, subjectId, publicKeySpki, alg, status]
+      description: Public-key metadata for a versioned crypto principal.
+      required: [publicKeyId, principalId, principalType, subjectId, publicKeySpki, alg, keyVersion, status]
       properties:
         publicKeyId:
           type: string
-        subjectType:
+        principalId:
+          type: string
+        principalType:
           type: string
-          enum: [signer, org-session]
+          enum: [USER, PARTY, ORG_ROLE, WORKSPACE_ROLE]
         subjectId:
           type: string
         orgId:
@@ -5712,6 +5808,9 @@ components:
         alg:
           type: string
           enum: [RSA-OAEP-256]
+        keyVersion:
+          type: integer
+          minimum: 1
         status:
           type: string
           enum: [active, retired]

package/package.json

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