@inklok/api-spec 7.10.0 → 7.11.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.10.0"
+  version: "7.11.0"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -2567,6 +2567,38 @@ paths:
         '500':
           $ref: '#/components/responses/InternalServerError'
 
+  /v1/templates/{workflowId}/agreements/prepare:
+    post:
+      operationId: prepareAgreementGuestInvitationsV1
+      summary: Prepare an agreement cryptographic context
+      description: |
+        First stage of agreement creation. Reserves the authoritative execution and party IDs,
+        then returns short-lived one-time bootstrap material used by the client to construct the
+        guest invitation capabilities required by the create/finalize request. Preparation does
+        not create a Vault-visible agreement or consume agreement creation usage.
+
+        The response must be finalized against the same workflow, organization, and authenticated
+        principal before `expiresIn` elapses. Raw bootstrap values are never persisted by Inklok.
+      x-required-roles: [workflow-operator, organization-admin]
+      x-required-scopes: [agreements:write]
+      tags: [Agreements]
+      parameters:
+        - name: workflowId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Short-lived authoritative context and one-time material for agreement creation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PrepareGuestInvitationsResponse'
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '500': { $ref: '#/components/responses/InternalServerError' }
+
   /v1/agreements/{executionId}:
     get:
       operationId: getAgreementV1
@@ -3075,6 +3107,10 @@ paths:
                 properties:
                   execution_id:
                     type: string
+                  expires_at:
+                    type: string
+                    format: date-time
+                    description: Immutable agreement deadline; signing is rejected at or after this instant.
                   agreement_title:
                     type: string
                     nullable: true
@@ -3131,6 +3167,19 @@ paths:
                             type: string
                             example: RSA-OAEP-256
                         description: Encrypted document key metadata for this signer
+                  key_scopes:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KeyScope'
+                  key_envelopes:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KeyEnvelope'
+                  invitation_capabilities:
+                    type: array
+                    description: Active agreement-specific guest capabilities. Only the authenticated party receives its encrypted private-key package; other parties expose public addressing data only.
+                    items:
+                      $ref: '#/components/schemas/GuestInvitationCapability'
                   parties:
                     type: array
                     items:
@@ -6183,7 +6232,7 @@ components:
 
     ExecutionStatus:
       type: string
-      enum: [pending, in_progress, completed, cancelled]
+      enum: [pending, in_progress, completed, cancelled, expired]
 
     ParticipantStatus:
       type: string
@@ -6288,8 +6337,16 @@ components:
 
     CreateExecutionRequest:
       type: object
-      required: [agreementTitle, participants, crypto]
+      required: [agreementTitle, participants, crypto, preparedExecutionId, guestInvitations]
       properties:
+        preparedExecutionId:
+          type: string
+          format: uuid
+        guestInvitations:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/CreateGuestInvitationInput'
         agreementTitle:
           type: string
           minLength: 1
@@ -6324,6 +6381,65 @@ components:
               items:
                 $ref: '#/components/schemas/ManagedRecoveryCapability'
 
+    PrepareGuestInvitationsResponse:
+      type: object
+      required: [executionId, expiresIn, parties]
+      properties:
+        executionId: { type: string, format: uuid }
+        expiresIn: { type: integer }
+        parties:
+          type: array
+          items:
+            type: object
+            required: [roleId, partyId, authorizationCode, bootstrapSecret]
+            properties:
+              roleId: { type: string }
+              partyId: { type: string }
+              authorizationCode: { type: string, writeOnly: true }
+              bootstrapSecret: { type: string, writeOnly: true }
+
+    CreateGuestInvitationInput:
+      type: object
+      required: [partyId, authorizationCode, bootstrapSecret, capability]
+      properties:
+        partyId: { type: string }
+        authorizationCode: { type: string, writeOnly: true }
+        bootstrapSecret: { type: string, writeOnly: true }
+        capability:
+          $ref: '#/components/schemas/GuestInvitationCapabilityInput'
+
+    GuestInvitationCapabilityInput:
+      type: object
+      required: [protocol, invitationKeyId, publicKeySpki, encryptedPrivateKey, iv, salt, aad, kdf, cipher]
+      properties:
+        protocol: { type: string, enum: [inklok-guest-invitation-v1] }
+        invitationKeyId: { type: string }
+        publicKeySpki: { type: string }
+        encryptedPrivateKey: { type: string }
+        iv: { type: string }
+        salt: { type: string }
+        aad: { type: string }
+        kdf: { type: string, enum: [HKDF-SHA-256] }
+        cipher: { type: string, enum: [AES-256-GCM] }
+
+    GuestInvitationCapability:
+      type: object
+      required: [protocol, partyId, invitationKeyId, invitationPrincipalId, publicKeySpki, status]
+      properties:
+        protocol: { type: string, enum: [inklok-guest-invitation-v1] }
+        partyId: { type: string }
+        invitationKeyId: { type: string }
+        invitationPrincipalId: { type: string }
+        publicKeySpki: { type: string }
+        encryptedPrivateKey: { type: string }
+        iv: { type: string }
+        salt: { type: string }
+        aad: { type: string }
+        kdf: { type: string, enum: [HKDF-SHA-256] }
+        cipher: { type: string, enum: [AES-256-GCM] }
+        status: { type: string, enum: [active] }
+        createdAt: { type: string, format: date-time }
+
     KeyScope:
       type: object
       required: [keyScopeId, type, version]
@@ -6342,6 +6458,13 @@ components:
           type: array
           items:
             type: string
+        fieldIds:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          description: Protected workflow fields assigned to this scope. Required by new agreement creation clients so one party may own multiple scopes with different sharing policies.
+          items:
+            type: string
         authorizationPolicy:
           type: object
           additionalProperties: true
@@ -6355,7 +6478,7 @@ components:
         protectionMode:
           type: string
           enum: [MANAGED, STRICT_ZK]
-          description: Current signing creation accepts MANAGED only. STRICT_ZK is reserved and not enabled.
+          description: Agreement signing creation requires STRICT_ZK. MANAGED remains in the response model for legacy records.
         createdAt:
           type: string
           format: date-time
@@ -6912,6 +7035,7 @@ components:
           currentStep,
           totalSteps,
           createdAt,
+          expiresAt,
           updatedAt,
           pdfEngineVersion,
           agreementTitle,
@@ -6944,6 +7068,11 @@ components:
           type: string
           format: date-time
           readOnly: true
+        expiresAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Immutable deadline exactly 30 days after agreement creation.
         updatedAt:
           type: string
           format: date-time
@@ -7036,6 +7165,11 @@ components:
         executionId:
           type: string
           description: The identifier of an agreement instance.
+        expiresAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Immutable agreement deadline for active agreements.
         organizationId:
           type: string
           nullable: true

package/package.json

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