diff --git a/docs/sdks/authorization.mdx b/docs/sdks/authorization.mdx index 0524e2cb..72640fb5 100644 --- a/docs/sdks/authorization.mdx +++ b/docs/sdks/authorization.mdx @@ -6,6 +6,7 @@ title: Authorization import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import JsAuthNote from '../../code_samples/js_auth_note.mdx' +import SdkVersion from '@site/src/components/SdkVersion'; # Authorization @@ -19,20 +20,35 @@ All examples on this page assume you have created a platform client. See [Authen ```go -client, err := sdk.New("http://localhost:8080", - sdk.WithClientCredentials("opentdf", "secret", nil), +package main + +import ( + "context" + "log" + + "github.com/opentdf/platform/sdk" ) -if err != nil { - log.Fatal(err) -} -// All Go snippets below use `client` and `context.Background()`. +func main() { + client, err := sdk.New("http://localhost:8080", + sdk.WithClientCredentials("opentdf", "secret", nil), + ) + if err != nil { + log.Fatal(err) + } + + // All Go snippets below use `client` and `context.Background()`. + _, _ = client, context.Background() +} ``` ```java +import io.opentdf.platform.sdk.*; +import java.util.Collections; + SDK sdk = SDKBuilder.newBuilder() .platformEndpoint("http://localhost:8080") .clientSecret("opentdf", "secret") @@ -40,6 +56,7 @@ SDK sdk = SDKBuilder.newBuilder() .build(); // All Java snippets below use `sdk`. +// Remember to call sdk.close() when done. ``` @@ -49,7 +66,7 @@ SDK sdk = SDKBuilder.newBuilder() import { authTokenInterceptor, clientCredentialsTokenProvider } from '@opentdf/sdk'; import { PlatformClient } from '@opentdf/sdk/platform'; -const platformClient = new PlatformClient({ +const platform = new PlatformClient({ interceptors: [authTokenInterceptor(clientCredentialsTokenProvider({ clientId: 'opentdf', clientSecret: 'secret', oidcOrigin: 'http://localhost:8080/auth/realms/opentdf', @@ -57,7 +74,7 @@ const platformClient = new PlatformClient({ platformUrl: 'http://localhost:8080', }); -// All JavaScript snippets below use `platformClient`. +// All JavaScript snippets below use `platform`. ``` @@ -72,6 +89,8 @@ Every authorization call requires an `EntityIdentifier` — the entity (user, se + + | Helper | Description | |--------|-------------| | `authorizationv2.ForEmail(email)` | Identify by email address | @@ -88,10 +107,41 @@ req := &authorizationv2.GetDecisionRequest{ // ... } ``` +
+Without helpers (manual proto construction) + +```go +import ( + "github.com/opentdf/platform/protocol/go/entity" + authorizationv2 "github.com/opentdf/platform/protocol/go/authorization/v2" +) + +req := &authorizationv2.GetDecisionRequest{ + EntityIdentifier: &authorizationv2.EntityIdentifier{ + Identifier: &authorizationv2.EntityIdentifier_EntityChain{ + EntityChain: &entity.EntityChain{ + Entities: []*entity.Entity{ + { + EntityType: &entity.Entity_EmailAddress{EmailAddress: "alice@example.com"}, + // or &entity.Entity_ClientId{ClientId: "..."} + // or &entity.Entity_UserName{UserName: "..."} + Category: entity.Entity_CATEGORY_SUBJECT, + }, + }, + }, + }, + }, + // ... +} +``` + +
 + + | Helper | Description | |--------|-------------| | `EntityIdentifiers.forEmail(email)` | Identify by email address | @@ -107,7 +157,6 @@ GetDecisionRequest request = GetDecisionRequest.newBuilder() // ... .build(); ``` -
Without helpers (manual proto construction) @@ -129,6 +178,8 @@ EntityIdentifier.newBuilder() + + | Helper | Description | |--------|-------------| | `EntityIdentifiers.forEmail(email)` | Identify by email address | @@ -140,12 +191,11 @@ EntityIdentifier.newBuilder() ```typescript import { EntityIdentifiers } from '@opentdf/sdk'; -const response = await platformClient.v2.authorization.getDecision({ +const response = await platform.v2.authorization.getDecision({ entityIdentifier: EntityIdentifiers.forEmail('alice@example.com'), // ... }); ``` -
Without helpers (manual object construction) @@ -216,7 +266,7 @@ sdk.getServices().authorization().getEntitlements(req).get() ```typescript -await platformClient.v2.authorization.getEntitlements({ ... }) +await platform.v2.authorization.getEntitlements({ ... }) ``` @@ -352,7 +402,7 @@ for (EntityEntitlements entitlement : resp.getEntitlementsList()) { ```typescript import { EntityIdentifiers } from '@opentdf/sdk'; -const response = await platformClient.v2.authorization.getEntitlements({ +const response = await platform.v2.authorization.getEntitlements({ entityIdentifier: EntityIdentifiers.forEmail('bob@OrgA.com'), }); @@ -366,7 +416,7 @@ To expand hierarchy rules: ```typescript import { EntityIdentifiers } from '@opentdf/sdk'; -const response = await platformClient.v2.authorization.getEntitlements({ +const response = await platform.v2.authorization.getEntitlements({ entityIdentifier: EntityIdentifiers.forEmail('user@company.com'), withComprehensiveHierarchy: true, }); @@ -407,7 +457,7 @@ sdk.getServices().authorization().getDecision(req).get() ```typescript -await platformClient.v2.authorization.getDecision({ ... }) +await platform.v2.authorization.getDecision({ ... }) ``` @@ -594,7 +644,7 @@ if (decision.getDecision() == Decision.DECISION_PERMIT) { import { EntityIdentifiers } from '@opentdf/sdk'; import { Decision } from '@opentdf/sdk/platform/authorization/v2/authorization_pb.js'; -const response = await platformClient.v2.authorization.getDecision({ +const response = await platform.v2.authorization.getDecision({ entityIdentifier: EntityIdentifiers.forEmail('user@company.com'), action: { name: 'decrypt' }, resource: { @@ -654,7 +704,7 @@ sdk.getServices().authorization().getDecisionBulk(req).get() ```typescript -await platformClient.v2.authorization.getDecisionBulk({ ... }) +await platform.v2.authorization.getDecisionBulk({ ... }) ``` @@ -835,7 +885,7 @@ import GetDecisionsExample from '@site/code_samples/java/get-decisions.mdx'; ```typescript import { EntityIdentifiers } from '@opentdf/sdk'; -const response = await platformClient.v2.authorization.getDecisionBulk({ +const response = await platform.v2.authorization.getDecisionBulk({ decisionRequests: [ { entityIdentifier: EntityIdentifiers.forEmail('user@company.com'), diff --git a/docs/sdks/discovery.mdx b/docs/sdks/discovery.mdx index cf06cf26..f47ed8bd 100644 --- a/docs/sdks/discovery.mdx +++ b/docs/sdks/discovery.mdx @@ -6,6 +6,7 @@ title: Discovery import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import JsAuthNote from '../../code_samples/js_auth_note.mdx' +import SdkVersion from '@site/src/components/SdkVersion'; # Discovery @@ -21,20 +22,35 @@ All examples on this page assume you have created a platform client. See [Authen ```go -client, err := sdk.New("http://localhost:8080", - sdk.WithClientCredentials("opentdf", "secret", nil), +package main + +import ( + "context" + "log" + + "github.com/opentdf/platform/sdk" ) -if err != nil { - log.Fatal(err) -} -// All Go snippets below use `client` and `context.Background()`. +func main() { + client, err := sdk.New("http://localhost:8080", + sdk.WithClientCredentials("opentdf", "secret", nil), + ) + if err != nil { + log.Fatal(err) + } + + // All Go snippets below use `client` and `context.Background()`. + _, _ = client, context.Background() +} ``` ```java +import io.opentdf.platform.sdk.*; +import java.util.Collections; + SDK sdk = SDKBuilder.newBuilder() .platformEndpoint("http://localhost:8080") .clientSecret("opentdf", "secret") @@ -42,6 +58,7 @@ SDK sdk = SDKBuilder.newBuilder() .build(); // All Java snippets below use `sdk`. +// Remember to call sdk.close() when done. ``` @@ -77,25 +94,28 @@ Returns all active attributes on the platform. Use this to see what's available + + ```go client.ListAttributes(ctx, ...namespaceFilter) ``` - + + ```java sdk.listAttributes() sdk.listAttributes(namespaceFilter) ``` - + + ```typescript await listAttributes(platformUrl, auth, namespaceFilter?) ``` - @@ -190,24 +210,27 @@ Reports whether an attribute definition exists on the platform. Returns `true`/` + + ```go client.AttributeExists(ctx, attributeFqn) ``` - + + ```java sdk.attributeExists(attributeFqn) ``` - + + ```typescript await attributeExists(platformUrl, auth, attributeFqn) ``` - @@ -272,24 +295,27 @@ Reports whether a specific attribute value FQN exists on the platform. Returns ` + + ```go client.AttributeValueExists(ctx, valueFqn) ``` - + + ```java sdk.attributeValueExists(valueFqn) ``` - + + ```typescript await attributeValueExists(platformUrl, auth, valueFqn) ``` - @@ -354,24 +380,27 @@ Checks that a list of attribute value FQNs exist on the platform **before** call + + ```go client.ValidateAttributes(ctx, fqns...) ``` - + + ```java sdk.validateAttributes(fqns) ``` - + + ```typescript await validateAttributes(platformUrl, auth, fqns) ``` - @@ -475,24 +504,27 @@ Returns the attribute value FQNs assigned to a specific entity (person or non-pe + + ```go client.GetEntityAttributes(ctx, entity) ``` - + + ```java sdk.getEntityAttributes(entity) ``` - + + ```typescript await platform.v2.authorization.getEntitlements({ ... }) ``` - The JS SDK does not expose a standalone `getEntityAttributes` function. Use `getEntitlements` via `PlatformClient` in a Node.js server environment. diff --git a/docs/sdks/obligations.mdx b/docs/sdks/obligations.mdx index e83997eb..33df801d 100644 --- a/docs/sdks/obligations.mdx +++ b/docs/sdks/obligations.mdx @@ -5,11 +5,14 @@ title: Obligations import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import SdkVersion from '@site/src/components/SdkVersion'; # Obligations An **obligation** is a PDP-to-PEP directive that accompanies an access decision: "permit, provided these controls are enforced." Obligations are scoped to a namespace and can carry multiple values and triggers. See [Obligations](/components/policy/obligations) for the policy concept. +Obligations are managed through the [**policy** service](/sdks/policy) — the methods on this page use the same `client` (Go) or `platform` (JS) instance as [Policy](/sdks/policy). + ## Setup All examples on this page assume you have created a platform client. See [Authentication](/sdks/authentication) for full details including DPoP key binding. @@ -997,12 +1000,11 @@ The created [Obligation Trigger object](#obligation-trigger-object). + + ```go client.Obligations.GetObligationTrigger(ctx, &obligations.GetObligationTriggerRequest{...}) ``` - -*Available since [SDK v0.16.0](https://github.com/opentdf/platform/releases/tag/sdk/v0.16.0)* - @@ -1185,5 +1187,5 @@ The removed [Obligation Trigger object](#obligation-trigger-object). | `id` | `string` (UUID) | Unique identifier, generated by the platform. | | `obligationValue` | [`ObligationValue`](#obligation-value-object) | The obligation value this trigger fires for. | | `action` | [`Action`](/sdks/policy#action) | The action that activates this trigger (e.g., `read`). | -| `attributeValue` | [`Value`](/sdks/policy#attribute-value-object) | The attribute value that must be present on the data. | +| `attributeValue` | [`AttributeValue`](/sdks/policy#attribute-value-object) | The attribute value that must be present on the data. | | `metadata` | [`Metadata`](/sdks/policy#metadata) | Optional [labels](/sdks/policy#metadata). | diff --git a/docs/sdks/policy.mdx b/docs/sdks/policy.mdx index dbc75f62..a63b0c1b 100644 --- a/docs/sdks/policy.mdx +++ b/docs/sdks/policy.mdx @@ -16,7 +16,7 @@ import JsAuthNote from '../../code_samples/js_auth_note.mdx' # Managing Policy -Policy is the set of rules that govern who can access data and under what conditions. It is made up of **namespaces**, **attributes**, **subject mappings**, and **subject condition sets**. See [Policy](/components/policy) for the concept overview. The SDK provides CRUD access to these policy rules through remote gRPC calls powered by the [platform service client](/sdks/platform-client). +Policy is the set of rules that govern who can access data and under what conditions. It is made up of [**namespaces**](#namespaces), [**attributes**](#attributes), [**subject mappings**](#subject-mappings), [**subject condition sets**](#subject-condition-sets), and [**obligations**](/sdks/obligations). See [Policy](/components/policy) for the concept overview. The SDK provides CRUD access to these policy rules through remote gRPC calls powered by the [platform service client](/sdks/platform-client). ## Setup diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index 4f387684..0364aa94 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -98,6 +98,7 @@ SDK sdk = SDKBuilder.newBuilder() .platformEndpoint("https://platform.example.com") .clientSecret("client-id", "client-secret") .build(); +// Remember to call sdk.close() when done. // Encrypt var kasInfo = new Config.KASInfo(); diff --git a/src/components/SdkVersion/index.tsx b/src/components/SdkVersion/index.tsx new file mode 100644 index 00000000..e2cd74a5 --- /dev/null +++ b/src/components/SdkVersion/index.tsx @@ -0,0 +1,60 @@ +import React from 'react'; + +type SdkVersionProps = { + language: 'go' | 'java' | 'js'; + version: string; + source: 'opentdf'; + status?: 'added' | 'deprecated'; + removal?: string; +}; + +const labels: Record = { + go: 'Go SDK', + java: 'Java SDK', + js: 'JS SDK', +}; + +function releaseUrl(language: string, version: string, source: string): string { + if (source === 'opentdf') { + switch (language) { + case 'go': + return `https://github.com/opentdf/platform/releases/tag/sdk/v${version}`; + case 'java': + return `https://github.com/opentdf/java-sdk/releases/tag/v${version}`; + case 'js': + return `https://github.com/opentdf/web-sdk/releases/tag/sdk-v${version}`; + } + } + return ''; +} + +function VersionLink({ url, children }: { url: string; children: React.ReactNode }) { + if (url) { + return {children}; + } + return <>{children}; +} + +export default function SdkVersion({ language, version, source, status = 'added', removal }: SdkVersionProps) { + const label = labels[language] ?? language; + const url = releaseUrl(language, version, source); + + if (status === 'deprecated') { + const removalUrl = removal ? releaseUrl(language, removal, source) : ''; + return ( + + {label} v{version} + {removal && ( + <>–v{removal} + )} + {' (deprecated)'} + + ); + } + + return ( + + {label} v{version}+ + + ); +}