Rework for SaaS Fusion: calls /tokenize + /restore HTTPS endpoints

fusion/POLICY_SETUP.md

@@ -1,46 +1,40 @@
-# Fusion policy setup (steps 2, 3-route, 8)
+# Fusion (shared SaaS) policy setup (steps 2, 3-route, 8)
 
-This is the one part that isn't Terraform/CLI — it's configured in the Amplify
-AI Gateway (Fusion) itself. Below is the flow the gateway must implement. It is
-the orchestration + transformation layer only; detection and the vault are the
-separate components it calls.
+Fusion is a **shared SaaS instance** — configured in the Amplify AI Gateway
+console, not deployed by this repo. Because it's SaaS it **cannot reach private
+VPC resources or use local AWS creds**, so it does not call Presidio or DynamoDB
+directly. Instead it calls two **public HTTPS endpoints** this repo exposes
+(built in `gateway_api/`, tasks T1/T2), which do the detection, minting, vault
+writes, and restore on the AWS side. Fusion owns the orchestration and routing.
 
-## Endpoints to fill in
-- `PRESIDIO_URL`  = `http://<presidio-task-ip>:5001/analyze`
-- `VAULT_TABLE`   = `hncb-deid-demo-vault` (DynamoDB)
-- `AGENT_RUNTIME_ARN` = printed by `scripts/agentcore_setup.sh` (step 3)
+## Endpoints Fusion calls
+- `TOKENIZE_URL` = `https://<...>/tokenize`  (ingress: detect + mint + vault-write + splice)
+- `RESTORE_URL`  = `https://<...>/restore`   (egress: vault lookup + re-attach identity)
+- `AGENT_RUNTIME_ARN` (or its HTTPS invoke endpoint) = printed by `scripts/agentcore_setup.sh`
+- Secure all three with an API key / OAuth from the Fusion outbound config.
 
 ## Ingress policy  (advisor request → cloud)
-1. **Authenticate** the advisor and apply the RBAC / business-purpose check.
-2. **Detect**: POST the raw query to `PRESIDIO_URL`. You get back typed findings:
-   `[{entity_type, start, end, score, text}]`. (Findings, not redaction.)
-3. **Mint + splice** (Fusion owns this):
-   - for each finding, generate a fresh **random** token — different every request.
-     Convention: `CUST_<random>` for a PERSON that resolves to a customer,
-     `TW_<random>` for a `TW_ROC_ID`, etc.
-   - write the reversible entry to the vault:
-     `{ token, type, value, session_id, expires_at }`
-   - replace each finding's span in the text with its token.
-4. **Route**: invoke `AGENT_RUNTIME_ARN` with `{ "prompt": "<de-identified text>" }`.
-5. **Trace**: log the **tokenized** payload only — never the pre-substitution text.
+1. **Authenticate** the advisor; apply the RBAC / business-purpose check.
+2. **Tokenize**: POST `{ query }` to `TOKENIZE_URL`. Receive
+   `{ deidentified_prompt, session_id }`. (The endpoint runs detect → mint →
+   vault-write → splice; detection returns typed findings, never a redacted blob.)
+3. **Route**: invoke the agent with `{ "prompt": deidentified_prompt }`.
+4. **Trace**: log the **tokenized** payload only — never the raw query.
 
 ## Egress policy  (cloud response → advisor)
 1. Receive the agent's de-identified result.
-2. **Restore**: for this `session_id`, look up the vault and re-attach the real
-   identity (envelope-level here — the talking points are generic, so you prepend
-   "王小明 —"; if any token appears inline, swap it back too).
-3. Return `{ "final": "<restored answer>", "deidentified_prompt": "<what the cloud saw>" }`
-   so the UI can show the split view.
+2. **Restore**: POST `{ session_id, text }` to `RESTORE_URL`; receive `{ final }`.
+3. Return `{ "final": ..., "deidentified_prompt": ... }` so the UI shows the split view.
 
-## Vault item shape (DynamoDB)
+## Vault item shape (DynamoDB, written by /tokenize)
 ```
 { "token": "CUST_000123", "type": "CUSTOMER", "value": "cust-0001",
   "session_id": "<conv id>", "expires_at": <epoch+ttl> }
 ```
 
-## Demo-simplest alternative
-If wiring all of this into Fusion policy is too much for the first recording,
-implement steps 2-5 as a thin Fusion flow that calls a small "tokenizer" Lambda
-(detect → mint → vault write → splice) and a "restore" Lambda on egress. Same
-architecture on screen, less console clicking. The point of the demo is that the
-gateway owns the flow and the cloud only ever sees tokens.
+## Why this split
+Keeping detection, minting, and the vault behind `/tokenize` and `/restore` means
+the only things exposed to the SaaS gateway are two authenticated HTTPS endpoints —
+no AWS creds or private resources leave the account, and Fusion stays a pure
+orchestration/routing layer. That is also the cleanest story on camera: the
+gateway owns the flow; the cloud only ever sees tokens.