feat(docs): document TDF assertions in SDK docs#268
Conversation
Add comprehensive assertions section to tdf.mdx covering types, scopes, AppliesToState, statements, signing/verification, system metadata assertions, and end-to-end examples in Go/Java/JS. Add type reference entries for AssertionConfig, Assertion, Statement, AssertionKey, and AssertionVerificationKeys. Add WithSystemMetadataAssertion to encrypt options. Fix Go scope constant (TrustedDataObj → TrustedDataObjScope). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdded documentation and cross-language examples for TDF Assertions, renamed several Encrypt Options headings, updated Go assertion examples to use Changes
Sequence Diagram(s)(omitted) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces comprehensive documentation for TDF Assertions, covering types, scopes, signing mechanisms, and system metadata assertions across Go, Java, and JavaScript SDKs. The review feedback points out naming inconsistencies for the "TrustedDataObjScope" constant and the "state" property in the newly added code examples and descriptions, which should be corrected for cross-SDK consistency.
|
📄 Preview deployed to https://opentdf-docs-pr-268.surge.sh |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
code_samples/tdf/encrypt_options.mdx (1)
551-555: Consider making the JS system-metadata snippet directly executable.This snippet currently only builds params. A short
client.createTDF(...)usage line here would match the rest of this page’s pattern and improve copy/paste usability.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@code_samples/tdf/encrypt_options.mdx` around lines 551 - 555, The snippet only constructs EncryptParams via EncryptParamsBuilder; update it to show an executable example by invoking the SDK's createTDF call with those params (e.g., call client.createTDF(encryptParams) or the equivalent async method) so readers can copy-paste a complete encrypt flow; reference the EncryptParamsBuilder usage and the client.createTDF (or SDK method name) to insert a single-line call after .build() demonstrating invocation and handling of the returned TDF.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/sdks/tdf.mdx`:
- Around line 1191-1428: The docs page contains large inline language-specific
examples (the Go block using rsa.GenerateKey and client.CreateTDF, the Java
block building AssertionConfig and Config.newTDFConfig, and the JS block calling
client.createTDF/client.read and EncryptParamsBuilder) that should be moved into
separate files under code_samples and referenced from this MDX; extract each
long example into a single source file per language, replace the inline fenced
code with an MDX include/reference to the corresponding sample, and update the
surrounding text to reference the samples (preserving IDs like "handling-1",
assertion field names, and the call sites client.CreateTDF,
sdk.GetSystemMetadataAssertionConfig, Config.newTDFConfig, and client.createTDF)
so the docs no longer duplicate large blocks and remain maintainable.
---
Nitpick comments:
In `@code_samples/tdf/encrypt_options.mdx`:
- Around line 551-555: The snippet only constructs EncryptParams via
EncryptParamsBuilder; update it to show an executable example by invoking the
SDK's createTDF call with those params (e.g., call
client.createTDF(encryptParams) or the equivalent async method) so readers can
copy-paste a complete encrypt flow; reference the EncryptParamsBuilder usage and
the client.createTDF (or SDK method name) to insert a single-line call after
.build() demonstrating invocation and handling of the returned TDF.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 56051994-8734-44bf-90d6-f1cd69c339d0
📒 Files selected for processing (2)
code_samples/tdf/encrypt_options.mdxdocs/sdks/tdf.mdx
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
Move system metadata and end-to-end assertion examples from inline tdf.mdx into code_samples/tdf/assertion_examples.mdx, following the repo convention for long code examples. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
There was a problem hiding this comment.
🧹 Nitpick comments (1)
code_samples/tdf/assertion_examples.mdx (1)
20-28: Complete the Go customization flow to avoid a dead-end snippet.This block says “before passing it to
WithAssertions” but does not show that final call, so the example currently stops short of the intended usage.Suggested doc snippet update
cfg, err := sdk.GetSystemMetadataAssertionConfig() +if err != nil { + log.Fatal(err) +} // cfg.Statement.Value contains JSON like: // {"tdf_spec_version":"4.3.0","creation_date":"2026-03-31T12:00:00Z", // "operating_system":"linux","sdk_version":"Go-0.3.4", // "go_version":"go1.23.0","architecture":"amd64"} + +// Optionally customize cfg.Statement.Value here, then pass it to WithAssertions: +_, err = client.CreateTDF(&buf, plaintext, + sdk.WithKasInformation(sdk.KASInfo{URL: kasURL}), + sdk.WithAssertions(cfg), +)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@code_samples/tdf/assertion_examples.mdx` around lines 20 - 28, The example stops before showing how to pass the inspected/modified config to WithAssertions; update the snippet to show retrieving cfg via GetSystemMetadataAssertionConfig, optionally mutating cfg.Statement.Value (or other fields) as needed, then calling WithAssertions(cfg) when building your assertion pipeline so readers see the full flow (use the existing symbols GetSystemMetadataAssertionConfig, cfg.Statement.Value and WithAssertions to locate where to add the final call).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@code_samples/tdf/assertion_examples.mdx`:
- Around line 20-28: The example stops before showing how to pass the
inspected/modified config to WithAssertions; update the snippet to show
retrieving cfg via GetSystemMetadataAssertionConfig, optionally mutating
cfg.Statement.Value (or other fields) as needed, then calling
WithAssertions(cfg) when building your assertion pipeline so readers see the
full flow (use the existing symbols GetSystemMetadataAssertionConfig,
cfg.Statement.Value and WithAssertions to locate where to add the final call).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 238ceb37-bb50-4446-b0f1-f9307b2861fa
📒 Files selected for processing (2)
code_samples/tdf/assertion_examples.mdxdocs/sdks/tdf.mdx
✅ Files skipped from review due to trivial changes (1)
- docs/sdks/tdf.mdx
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
elizabethhealy
left a comment
elizabethhealy
left a comment
There was a problem hiding this comment.
lgtm! i think a second review from @pflynn-virtru or @sujankota would be helpful as they know a lot more about assertions
…nflict The encrypt options "Assertions" header produced the same #assertions anchor as the main Assertions section, causing TOC links to jump to the wrong spot. Renamed to "WithAssertions" to match the SDK option name and avoid the duplicate anchor. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
85929d5
Documents the naming convention for code_samples headers to avoid duplicate anchors when imported into doc pages. References #273 for planned CI enforcement. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3 participants
Summary
docs/sdks/tdf.mdxcovering types, scopes, AppliesToState, statements, signing/verification, and end-to-end examples in Go/Java/JSWithSystemMetadataAssertion) — available in all three SDKs (Go, Java, JS)AssertionConfig,Assertion,Statement,AssertionKey, andAssertionVerificationKeysWithSystemMetadataAssertionto the encrypt options referencesdk.TrustedDataObj→sdk.TrustedDataObjScopeTest plan
npm run buildpasses with no new broken anchors🤖 Generated with Claude Code
Summary by CodeRabbit