From a4b3802acf9e8d98bb85fa32c855e6399992b0a9 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 21 Apr 2026 13:36:22 -0700 Subject: [PATCH 1/6] feat(docs): document SDK v0.16.0 changes - Add KAS error classification section (breaking change): ErrTampered vs ErrKASRequestError distinction with migration guide - Add OIDC trailing-slash issuer troubleshooting for Authentik-style IDPs - Add GetObligationTrigger RPC documentation with Go/JS examples Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/sdks/obligations.mdx | 67 +++++++++++++++++++++++++++++++++++ docs/sdks/troubleshooting.mdx | 45 +++++++++++++++++++++++ 2 files changed, 112 insertions(+) diff --git a/docs/sdks/obligations.mdx b/docs/sdks/obligations.mdx index 662c90fe..978f5b74 100644 --- a/docs/sdks/obligations.mdx +++ b/docs/sdks/obligations.mdx @@ -989,6 +989,73 @@ The created [Obligation Trigger object](#obligation-trigger-object). +
+Get an Obligation Trigger + +**Signature** + + + + +```go +client.Obligations.GetObligationTrigger(ctx, &obligations.GetObligationTriggerRequest{...}) +``` + + + + +```typescript +await platform.v1.obligation.getObligationTrigger({ ... }) +``` + + + + +**Parameters** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | `string` (UUID) | Yes | The trigger UUID. | + +**Example** + + + + +```go +import "github.com/opentdf/platform/protocol/go/policy/obligations" + +resp, err := client.Obligations.GetObligationTrigger(context.Background(), + &obligations.GetObligationTriggerRequest{ + Id: "7e8f9a0b-...", + }, +) +if err != nil { + log.Fatal(err) +} +log.Printf("Trigger ID: %s\n", resp.GetTrigger().GetId()) +``` + + + + +```typescript +const resp = await platform.v1.obligation.getObligationTrigger({ + id: '7e8f9a0b-...', +}); + +console.log(`Trigger ID: ${resp.trigger?.id}`); +``` + + + + +**Returns** + +A single [Obligation Trigger object](#obligation-trigger-object). + +
+
List Obligation Triggers diff --git a/docs/sdks/troubleshooting.mdx b/docs/sdks/troubleshooting.mdx index e4f8f60b..83ab2e2b 100644 --- a/docs/sdks/troubleshooting.mdx +++ b/docs/sdks/troubleshooting.mdx @@ -29,6 +29,14 @@ Check that your identity provider is accessible: curl https:/// ``` +## OIDC Discovery Fails with Trailing-Slash Issuer + +**Error**: `unexpected end of JSON input` during OIDC discovery + +**Cause**: Some identity providers (e.g., [Authentik](https://goauthentik.io/)) include a trailing slash in their OIDC issuer URL (e.g., `https://idp.example/app/`). SDK versions before v0.16.0 concatenated this with `/.well-known/openid-configuration`, producing a double-slash URL that returned a redirect instead of JSON. + +**Solution**: Upgrade to Go SDK **v0.16.0+**, which normalizes the issuer URL automatically using `url.JoinPath`. No code changes required. + ## Token Expired **Error**: `token expired`, `invalid token`, or `jwt expired` @@ -245,6 +253,43 @@ otdfctl policy subject-mappings create \ 3. **Verify file integrity** — TDFs are tamper-evident; any modification after encryption will cause decryption to fail 4. **Check file transfer** — binary TDF files can be corrupted by text-mode transfers; ensure files are transferred in binary mode +## KAS Error Classification (Go SDK v0.16.0+) + +:::caution Breaking Change in v0.16.0 +The Go SDK v0.16.0 changed how KAS (Key Access Server) errors are classified. If your code checks `errors.Is(err, sdk.ErrTampered)`, read this section carefully. +::: + +**Background**: When decrypting a TDF, the SDK contacts the KAS to unwrap keys. The KAS can return errors for two very different reasons: + +1. **Integrity failure (tamper)** — the TDF's policy binding or encrypted key has been modified +2. **Misconfiguration** — the request was malformed, used an unsupported key type, or the client lacks permission + +**What changed**: Prior to v0.16.0, *all* KAS 400-level errors were classified as `ErrTampered`. This made `errors.Is(err, sdk.ErrTampered)` unreliable — it returned `true` even for configuration errors. Starting in v0.16.0, the SDK distinguishes between tamper and misconfiguration: + +| Error source | SDK sentinel | `errors.Is(err, sdk.ErrTampered)`? | +|---|---|---| +| Policy binding mismatch | `ErrRewrapBadRequest` | Yes | +| DEK decryption failure | `ErrRewrapBadRequest` | Yes | +| Corrupted policy body | `ErrRewrapBadRequest` | Yes | +| Misconfiguration (e.g., wrong key type) | `ErrKASRequestError` | No | +| Access denied (403) | `ErrRewrapForbidden` | No | + +**Migration**: If your code catches all KAS errors via `ErrTampered`, add a check for `ErrKASRequestError`: + +```go +if errors.Is(err, sdk.ErrTampered) { + // Integrity failure — the TDF was modified after encryption +} else if errors.Is(err, sdk.ErrKASRequestError) { + // Client or configuration error (400 or 403 from KAS) +} +``` + +:::note +`ErrRewrapForbidden` (403) now wraps `ErrKASRequestError`, so `errors.Is(err, sdk.ErrKASRequestError)` matches both misconfiguration 400s and forbidden 403s. +::: + +See [opentdf/platform#3166](https://github.com/opentdf/platform/issues/3166) for full details. + ## Entity Resolution Failed **Error**: `entity resolution failed` or `failed to resolve entity` From be8b48f28b711efbdfa36b59a30b18534114d626 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 21 Apr 2026 13:37:46 -0700 Subject: [PATCH 2/6] chore(docs): add version annotation to GetObligationTrigger Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/sdks/obligations.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sdks/obligations.mdx b/docs/sdks/obligations.mdx index 978f5b74..c643aef0 100644 --- a/docs/sdks/obligations.mdx +++ b/docs/sdks/obligations.mdx @@ -1011,6 +1011,8 @@ await platform.v1.obligation.getObligationTrigger({ ... }) +*Available since SDK v0.16.0* + **Parameters** | Parameter | Type | Required | Description | From da3d2fda679bf1c2f5c7f02e920979f34b03d3ff Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 21 Apr 2026 13:38:13 -0700 Subject: [PATCH 3/6] chore(docs): link version annotation to release Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/sdks/obligations.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdks/obligations.mdx b/docs/sdks/obligations.mdx index c643aef0..2088dd64 100644 --- a/docs/sdks/obligations.mdx +++ b/docs/sdks/obligations.mdx @@ -1011,7 +1011,7 @@ await platform.v1.obligation.getObligationTrigger({ ... }) -*Available since SDK v0.16.0* +*Available since [SDK v0.16.0](https://github.com/opentdf/platform/releases/tag/sdk/v0.16.0)* **Parameters** From 32ec75aed1a7ce975cf1ea11ecc4e81a3295fd8a Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 21 Apr 2026 13:39:39 -0700 Subject: [PATCH 4/6] chore(docs): move version annotation inside Go tab Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/sdks/obligations.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdks/obligations.mdx b/docs/sdks/obligations.mdx index 2088dd64..20c1bf05 100644 --- a/docs/sdks/obligations.mdx +++ b/docs/sdks/obligations.mdx @@ -1001,6 +1001,8 @@ The created [Obligation Trigger object](#obligation-trigger-object). client.Obligations.GetObligationTrigger(ctx, &obligations.GetObligationTriggerRequest{...}) ``` +*Available since [SDK v0.16.0](https://github.com/opentdf/platform/releases/tag/sdk/v0.16.0)* + @@ -1011,8 +1013,6 @@ await platform.v1.obligation.getObligationTrigger({ ... }) -*Available since [SDK v0.16.0](https://github.com/opentdf/platform/releases/tag/sdk/v0.16.0)* - **Parameters** | Parameter | Type | Required | Description | From f6659e54628385a38b3aefccd40230cbccf4f7e6 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 21 Apr 2026 13:47:07 -0700 Subject: [PATCH 5/6] fix(docs): remove unverified JS examples from GetObligationTrigger GetObligationTrigger is only available in the Go SDK as of v0.16.0. The JS web-sdk has not yet generated this method. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/sdks/obligations.mdx | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/docs/sdks/obligations.mdx b/docs/sdks/obligations.mdx index 20c1bf05..e83997eb 100644 --- a/docs/sdks/obligations.mdx +++ b/docs/sdks/obligations.mdx @@ -1003,13 +1003,6 @@ client.Obligations.GetObligationTrigger(ctx, &obligations.GetObligationTriggerRe *Available since [SDK v0.16.0](https://github.com/opentdf/platform/releases/tag/sdk/v0.16.0)* - - - -```typescript -await platform.v1.obligation.getObligationTrigger({ ... }) -``` - @@ -1038,17 +1031,6 @@ if err != nil { log.Printf("Trigger ID: %s\n", resp.GetTrigger().GetId()) ``` - - - -```typescript -const resp = await platform.v1.obligation.getObligationTrigger({ - id: '7e8f9a0b-...', -}); - -console.log(`Trigger ID: ${resp.trigger?.id}`); -``` - From 71bc3c162d57eee26f94c6db706cffef75903136 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 21 Apr 2026 13:50:17 -0700 Subject: [PATCH 6/6] fix(docs): address review feedback on troubleshooting - Clarify OIDC trailing-slash issue is Go SDK specific (JS unaffected) - Add sdk. prefix to error sentinels in KAS classification table Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/sdks/troubleshooting.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/sdks/troubleshooting.mdx b/docs/sdks/troubleshooting.mdx index 83ab2e2b..75a2d9f4 100644 --- a/docs/sdks/troubleshooting.mdx +++ b/docs/sdks/troubleshooting.mdx @@ -33,9 +33,9 @@ curl https:/// **Error**: `unexpected end of JSON input` during OIDC discovery -**Cause**: Some identity providers (e.g., [Authentik](https://goauthentik.io/)) include a trailing slash in their OIDC issuer URL (e.g., `https://idp.example/app/`). SDK versions before v0.16.0 concatenated this with `/.well-known/openid-configuration`, producing a double-slash URL that returned a redirect instead of JSON. +**Cause**: Some identity providers (e.g., [Authentik](https://goauthentik.io/)) include a trailing slash in their OIDC issuer URL (e.g., `https://idp.example/app/`). The Go SDK before v0.16.0 concatenated this with `/.well-known/openid-configuration`, producing a double-slash URL that returned a redirect instead of JSON. The JavaScript SDK is unaffected (browser fetch follows redirects automatically). -**Solution**: Upgrade to Go SDK **v0.16.0+**, which normalizes the issuer URL automatically using `url.JoinPath`. No code changes required. +**Solution**: Upgrade to Go SDK **v0.16.0+**, which normalizes the issuer URL automatically. No code changes required. ## Token Expired @@ -268,11 +268,11 @@ The Go SDK v0.16.0 changed how KAS (Key Access Server) errors are classified. If | Error source | SDK sentinel | `errors.Is(err, sdk.ErrTampered)`? | |---|---|---| -| Policy binding mismatch | `ErrRewrapBadRequest` | Yes | -| DEK decryption failure | `ErrRewrapBadRequest` | Yes | -| Corrupted policy body | `ErrRewrapBadRequest` | Yes | -| Misconfiguration (e.g., wrong key type) | `ErrKASRequestError` | No | -| Access denied (403) | `ErrRewrapForbidden` | No | +| Policy binding mismatch | `sdk.ErrRewrapBadRequest` | Yes | +| DEK decryption failure | `sdk.ErrRewrapBadRequest` | Yes | +| Corrupted policy body | `sdk.ErrRewrapBadRequest` | Yes | +| Misconfiguration (e.g., wrong key type) | `sdk.ErrKASRequestError` | No | +| Access denied (403) | `sdk.ErrRewrapForbidden` | No | **Migration**: If your code catches all KAS errors via `ErrTampered`, add a check for `ErrKASRequestError`: