From 1f8c45fdf280bb5b8ea39f8bb6ba474dbca51b5a Mon Sep 17 00:00:00 2001
From: Conan Scott <conanscott@gmail.com>
Date: Thu, 2 Jul 2026 14:32:38 +1000
Subject: [PATCH] docs(fusion): add openapi.yaml (tokenize + restore)

OpenAPI 3.0 spec for the de-id transforms with concrete request/response
schemas, both /tokenize and /restore, an x-api-key securityScheme for
backend-direct calls, and both servers (backend custom domain + Fusion listener,
which injects the key).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 fusion/openapi.yaml | 130 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 fusion/openapi.yaml

diff --git a/fusion/openapi.yaml b/fusion/openapi.yaml
new file mode 100644
index 0000000..05f5325
--- /dev/null
+++ b/fusion/openapi.yaml
@@ -0,0 +1,130 @@
+openapi: 3.0.3
+info:
+  title: HNCB De-identification API (tokenize / restore)
+  version: 1.0.0
+  description: |
+    Ingress/egress transforms for the reversible PII de-identification round trip.
+
+    Two access paths:
+    - **Direct to the backend** (`hncb-deid.apim-apac-demo.com`): the caller MUST send
+      the `x-api-key` shared secret (this spec's `ApiKeyAuth`).
+    - **Via Fusion** (the gateway listener): the gateway injects `x-api-key` on the
+      backend leg, so the portal/UI caller sends only the JSON body — no key. For that
+      path, treat the security requirement as satisfied by the gateway.
+
+servers:
+  - url: https://hncb-deid.apim-apac-demo.com
+    description: Backend (custom domain) — requires x-api-key
+  - url: https://aus-design.sandbox.fusion.services.axway.com:4443
+    description: Fusion listener — gateway injects the key; send body only
+
+# Backend-direct requirement. Fusion callers omit the header (the gateway adds it).
+security:
+  - ApiKeyAuth: []
+
+paths:
+  /tokenize:
+    post:
+      summary: Tokenize a query (de-identify PII before it leaves for the cloud)
+      operationId: tokenizeQuery
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - query
+              properties:
+                query:
+                  type: string
+                  example: 請幫我整理王小明最近三個月的理財往來，並給我下次拜訪話術。
+      responses:
+        "200":
+          description: Successful tokenization response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  deidentified_prompt:
+                    type: string
+                    description: The query with PII replaced by tokens.
+                    example: 請幫我整理CUST_264978最近三個月的理財往來，並給我下次拜訪話術。
+                  session_id:
+                    type: string
+                    description: Correlates this request's tokens for later /restore.
+                    example: 9d15023985154d79a477d4e5b8b2c87c
+                  tokens:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        token:
+                          type: string
+                          example: CUST_264978
+                        type:
+                          type: string
+                          description: Entity type detected (PERSON, TW_ROC_ID).
+                          example: PERSON
+        "400":
+          description: Missing/invalid body (query required)
+        "401":
+          description: Unauthorized (missing/invalid API key)
+        "502":
+          description: Detector unavailable
+
+  /restore:
+    post:
+      summary: Restore (detokenize) identity in a tokenized response
+      operationId: restoreIdentity
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - session_id
+                - text
+              properties:
+                session_id:
+                  type: string
+                  description: The session_id returned by /tokenize.
+                  example: 9d15023985154d79a477d4e5b8b2c87c
+                text:
+                  type: string
+                  description: Tokenized text (e.g. the agent's answer) to re-identify.
+                  example: 針對客戶 CUST_264978 的保守型投資組合，建議…
+      responses:
+        "200":
+          description: Successful restore response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  final:
+                    type: string
+                    description: Text with identity re-attached (envelope + inline tokens).
+                    example: |
+                      （客戶：王小明）
+                      針對客戶 王小明 的保守型投資組合，建議…
+                  restored:
+                    type: integer
+                    description: Number of tokens restored for this session.
+                    example: 1
+        "400":
+          description: Missing session_id or text
+        "401":
+          description: Unauthorized (missing/invalid API key)
+
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: x-api-key
+      description: |
+        Shared secret (`tokenize_api_key`). Required for direct backend calls;
+        injected by Fusion on the gateway path.