@inklok/api-spec 7.7.2 → 7.8.0

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.0"
   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
@@ -2564,17 +2564,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 +2588,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':
@@ -2625,6 +2624,63 @@ paths:
         '500':
           $ref: '#/components/responses/InternalServerError'
 
+  /v1/signing/managed-regrant:
+    post:
+      operationId: managedScopeRegrant
+      summary: Regrant authorized managed scope envelopes
+      x-visibility: internal
+      x-required-roles: []
+      description: |
+        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:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [executionId, destinationPublicKeyId]
+              properties:
+                executionId:
+                  type: string
+                destinationPublicKeyId:
+                  type: string
+      responses:
+        '200':
+          description: Scoped managed envelopes for the authenticated principal
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [keyScopes, envelopes]
+                properties:
+                  keyScopes:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KeyScope'
+                  envelopes:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KeyEnvelope'
+        '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'
+      x-inklok-lambda: managed-scope-regrant
+
   /v1/agreements/{executionId}/resend-completion-emails:
     post:
       operationId: agreementResendCompletionEmails
@@ -3117,17 +3173,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: resolveSigningScopeEnvelopes
+      summary: Resolve signer-authorized 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
+        - Returns only scope envelopes authorized for the signer
         - Audited for signer access
       tags:
         - Signing
@@ -3147,7 +3203,7 @@ paths:
               executionId: "exec_123"
       responses:
         '200':
-          description: Wrapped key material for signer-visible document and execution key envelopes
+          description: Wrapped document material and signer-visible scoped field envelopes
           content:
             application/json:
               schema:
@@ -3163,34 +3219,20 @@ paths:
                       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'
+                  keyScopes:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KeyScope'
+                  envelopes:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KeyEnvelope'
               example:
                 documentDek:
                   encrypted: "base64..."
                   alg: "KMS-WRAPPED-BASE64"
-                placeholders: {}
-                executionKey:
-                  keyId: "ek_01H..."
-                  alg: "INKLOK-EK-AES-256-GCM-RSA-OAEP-256"
-                  envelopes:
-                    - keyId: "ek_01H..."
-                      subjectId: "party_abc"
-                      subjectType: "signer"
-                      alg: "RSA-OAEP-256"
-                      wrappedKey: "base64..."
+                keyScopes: []
+                envelopes: []
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -3201,7 +3243,7 @@ paths:
           $ref: '#/components/responses/NotFound'
         '500':
           $ref: '#/components/responses/InternalServerError'
-      x-inklok-lambda: signing-unwrap-deks
+      x-inklok-lambda: signing-scope-envelopes
 
 components:
   securitySchemes:
@@ -4616,7 +4658,7 @@ components:
           type: string
           nullable: true
         plan:
-          $ref: '#/components/schemas/Plan'
+          $ref: '#/components/schemas/PlatformPlan'
         totalApiRequests:
           type: integer
           minimum: 0
@@ -5619,88 +5661,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
-          enum: [INKLOK-EK-AES-256-GCM-RSA-OAEP-256]
-        plaintextKey:
+        type:
+          type: string
+          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
+          items:
+            type: string
+        authorizationPolicy:
+          type: object
+          additionalProperties: true
+        cryptoPrincipalRefs:
           type: array
-          minItems: 1
           items:
-            $ref: '#/components/schemas/ExecutionKeyEnvelope'
+            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
-          enum: [AWS-KMS]
-        ciphertext:
+        agreementId:
+          type: string
+        keyScopeId:
+          type: string
+        recipientPrincipalId:
+          type: string
+        recipientKeyId:
+          type: string
+        wrappedKey:
           type: string
-          description: Base64 protected ciphertext for the execution key.
-        kmsKeyId:
+          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 +5869,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.0",
   "description": "Canonical OpenAPI specification for the Inklok public API.",
   "main": "openapi.yaml",
   "license": "MIT",