feat(docs): expand TDF documentation

code_samples/tdf/decrypt_options.mdx

@@ -0,0 +1,358 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Decrypt Options
+
+The following options can be passed to the decrypt call to control how the TDF is opened and validated.
+
+---
+
+### KAS Allowlist
+
+Restrict decryption to only contact KAS endpoints on an explicit allowlist. If the TDF references a KAS not on the list, decryption will fail. This is a security control to prevent credential exfiltration to a rogue KAS.
+
+<Tabs>
+<TabItem value="go" label="Go">
+
+```go
+import (
+    "bytes"
+
+    "github.com/opentdf/platform/sdk"
+)
+
+tdfReader, err := client.LoadTDF(
+    bytes.NewReader(encryptedBytes),
+    sdk.WithKasAllowlist([]string{
+        "https://kas.example.com",
+        "https://kas-backup.example.com",
+    }),
+)
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+import io.opentdf.platform.sdk.Config;
+import io.opentdf.platform.sdk.TDF;
+
+Config.TDFReaderConfig readerConfig = Config.newTDFReaderConfig(
+    Config.WithKasAllowlist(
+        "https://kas.example.com",
+        "https://kas-backup.example.com"
+    )
+);
+TDF.Reader reader = sdk.loadTDF(fileChannel, readerConfig);
+```
+
+</TabItem>
+<TabItem value="js" label="JavaScript">
+
+```typescript
+const plaintext = await client.read({
+    source: { type: 'buffer', location: encryptedBytes },
+    allowedKASEndpoints: [
+        'https://kas.example.com',
+        'https://kas-backup.example.com',
+    ],
+});
+```
+
+</TabItem>
+</Tabs>
+
+---
+
+### Ignore KAS Allowlist
+
+Disable the KAS allowlist check entirely. The SDK will contact any KAS referenced in the TDF manifest without restriction.
+
+:::warning Security consideration
+Only use this in controlled environments (e.g., integration tests, airgapped deployments where all KAS endpoints are trusted). In production, the allowlist is an important defence against credential forwarding attacks.
+:::
+
+<Tabs>
+<TabItem value="go" label="Go">
+
+```go
+import (
+    "bytes"
+
+    "github.com/opentdf/platform/sdk"
+)
+
+tdfReader, err := client.LoadTDF(
+    bytes.NewReader(encryptedBytes),
+    sdk.WithIgnoreAllowlist(true),
+)
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+import io.opentdf.platform.sdk.Config;
+import io.opentdf.platform.sdk.TDF;
+
+Config.TDFReaderConfig readerConfig = Config.newTDFReaderConfig(
+    Config.WithIgnoreKasAllowlist(true)
+);
+TDF.Reader reader = sdk.loadTDF(fileChannel, readerConfig);
+```
+
+</TabItem>
+<TabItem value="js" label="JavaScript">
+
+```typescript
+const plaintext = await client.read({
+    source: { type: 'buffer', location: encryptedBytes },
+    ignoreAllowlist: true,
+});
+```
+
+</TabItem>
+</Tabs>
+
+---
+
+### Assertion Verification Keys
+
+Provide public keys used to verify signed assertions embedded in the TDF. If an assertion was signed during encryption, you must supply the corresponding verification key here or verification will fail.
+
+<Tabs>
+<TabItem value="go" label="Go">
+
+```go
+import (
+    "bytes"
+
+    "github.com/opentdf/platform/sdk"
+)
+
+verificationKeys := sdk.AssertionVerificationKeys{
+    Keys: map[string]sdk.AssertionKey{
+        "assertion-1": {
+            Alg: sdk.AssertionKeyAlgRS256,
+            Key: rsaPublicKey, // *rsa.PublicKey
+        },
+    },
+}
+
+tdfReader, err := client.LoadTDF(
+    bytes.NewReader(encryptedBytes),
+    sdk.WithAssertionVerificationKeys(verificationKeys),
+)
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+import io.opentdf.platform.sdk.AssertionConfig;
+import io.opentdf.platform.sdk.Config;
+import io.opentdf.platform.sdk.TDF;
+import java.util.Map;
+
+var assertionKey = new AssertionConfig.AssertionKey(
+    AssertionConfig.AssertionKeyAlg.RS256,
+    rsaPublicKey
+);
+
+var verificationKeys = new Config.AssertionVerificationKeys();
+verificationKeys.keys = Map.of("assertion-1", assertionKey);
+
+Config.TDFReaderConfig readerConfig = Config.newTDFReaderConfig(
+    Config.withAssertionVerificationKeys(verificationKeys)
+);
+TDF.Reader reader = sdk.loadTDF(fileChannel, readerConfig);
+```
+
+</TabItem>
+<TabItem value="js" label="JavaScript">
+
+```typescript
+const plaintext = await client.read({
+    source: { type: 'buffer', location: encryptedBytes },
+    assertionVerificationKeys: {
+        keys: {
+            'assertion-1': {
+                alg: 'RS256',
+                key: rsaPublicKey, // CryptoKey
+            },
+        },
+    },
+});
+```
+
+</TabItem>
+</Tabs>
+
+---
+
+### Disable Assertion Verification
+
+Skip cryptographic verification of all assertions in the TDF. The assertions will still be read and returned, but their signatures will not be checked.
+
+:::warning
+Disabling assertion verification removes a tamper-detection layer. Only use this when you have explicitly verified the TDF's integrity through another mechanism.
+:::
+
+<Tabs>
+<TabItem value="go" label="Go">
+
+```go
+import (
+    "bytes"
+
+    "github.com/opentdf/platform/sdk"
+)
+
+tdfReader, err := client.LoadTDF(
+    bytes.NewReader(encryptedBytes),
+    sdk.WithDisableAssertionVerification(true),
+)
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+import io.opentdf.platform.sdk.Config;
+import io.opentdf.platform.sdk.TDF;
+
+Config.TDFReaderConfig readerConfig = Config.newTDFReaderConfig(
+    Config.withDisableAssertionVerification(true)
+);
+TDF.Reader reader = sdk.loadTDF(fileChannel, readerConfig);
+```
+
+</TabItem>
+<TabItem value="js" label="JavaScript">
+
+```typescript
+const plaintext = await client.read({
+    source: { type: 'buffer', location: encryptedBytes },
+    noVerify: true,
+});
+```
+
+</TabItem>
+</Tabs>
+
+---
+
+### Session Key Type
+
+During decryption, the SDK generates a short-lived (ephemeral) asymmetric key pair and sends the public half to the KAS. The KAS uses it to securely return the unwrapped Data Encryption Key back to the SDK. This option controls the algorithm used for that ephemeral key pair.
+
+The default is `rsa:2048`. Use `ec:secp256r1` (or another EC variant) for smaller messages and faster key exchange. Must match an algorithm supported by the KAS.
+
+<Tabs>
+<TabItem value="go" label="Go">
+
+```go
+import (
+    "bytes"
+
+    "github.com/opentdf/platform/lib/ocrypto"
+    "github.com/opentdf/platform/sdk"
+)
+
+tdfReader, err := client.LoadTDF(
+    bytes.NewReader(encryptedBytes),
+    sdk.WithSessionKeyType(ocrypto.EC256Key),
+)
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+import io.opentdf.platform.sdk.Config;
+import io.opentdf.platform.sdk.TDF;
+
+Config.TDFReaderConfig readerConfig = Config.newTDFReaderConfig(
+    Config.WithSessionKeyType(KeyType.EC256Key)
+);
+TDF.Reader reader = sdk.loadTDF(fileChannel, readerConfig);
+```
+
+</TabItem>
+<TabItem value="js" label="JavaScript">
+
+```typescript
+const plaintext = await client.read({
+    source: { type: 'buffer', location: encryptedBytes },
+    wrappingKeyAlgorithm: 'ec:secp256r1',
+});
+```
+
+</TabItem>
+</Tabs>
+
+---
+
+### Fulfillable Obligations
+
+Declare which obligation FQNs the calling application is prepared to fulfil. The platform may attach obligations to an access decision — if an obligation is not declared as fulfillable, decryption may be denied.
+
+<Tabs>
+<TabItem value="go" label="Go">
+
+```go
+import (
+    "bytes"
+
+    "github.com/opentdf/platform/sdk"
+)
+
+tdfReader, err := client.LoadTDF(
+    bytes.NewReader(encryptedBytes),
+    sdk.WithTDFFulfillableObligationFQNs([]string{
+        "https://example.com/obl/audit/value/log",
+        "https://example.com/obl/watermark/value/apply",
+    }),
+)
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+Fulfillable obligations are not yet supported in the Java SDK TDF reader config. Configure them at the SDK level via `SDKBuilder` if available, or handle obligation enforcement in your application logic after reading the policy object.
+
+</TabItem>
+<TabItem value="js" label="JavaScript">
+
+```typescript
+const plaintext = await client.read({
+    source: { type: 'buffer', location: encryptedBytes },
+    fulfillableObligationFQNs: [
+        'https://example.com/obl/audit/value/log',
+        'https://example.com/obl/watermark/value/apply',
+    ],
+});
+```
+
+</TabItem>
+</Tabs>
+
+---
+
+### Max Manifest Size (Go only)
+
+Limit the maximum size of the TDF manifest that the SDK will parse. This is a defence against malformed or malicious TDFs with abnormally large manifests.
+
+```go
+import (
+    "bytes"
+
+    "github.com/opentdf/platform/sdk"
+)
+
+tdfReader, err := client.LoadTDF(
+    bytes.NewReader(encryptedBytes),
+    sdk.WithMaxManifestSize(1 * 1024 * 1024), // 1 MB limit
+)
+```
+