diff --git a/docs/sdks/authorization.mdx b/docs/sdks/authorization.mdx index 0b600d36..a5dbb85a 100644 --- a/docs/sdks/authorization.mdx +++ b/docs/sdks/authorization.mdx @@ -602,7 +602,7 @@ await platform.v2.authorization.getDecision({ ... }) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `entityIdentifier` | [`EntityIdentifier`](#entityidentifier) | Yes | The entity requesting access. Use [helpers](#entityidentifier) like `ForEmail(...)` (Go) or `EntityIdentifiers.forEmail(...)` (Java/JS). | -| `action` | `Action` | Yes | The action being performed (e.g., `decrypt`, `read`). | +| `action` | [`Action`](/sdks/policy#action) | Yes | The action being performed (e.g., `decrypt`, `read`). | | `resource` | [`Resource`](#resource) | Yes | The resource being accessed. Use [helpers](#resource) like `ForAttributeValues(...)` (Go) or `Resources.forAttributeValues(...)` (Java/JS). | **Example** @@ -789,7 +789,7 @@ if (decision?.decision === Decision.PERMIT) { **Returns** -A [ResourceDecision](#resourcedecision) with a [Decision](#decision) (permit/deny) and any required [obligations](/components/policy/obligations) the consuming application must enforce. +A [ResourceDecision](#resourcedecision) with a [Decision](#decision) (permit/deny) and any required [obligations](/sdks/obligations) the consuming application must enforce. --- @@ -827,14 +827,16 @@ await platform.v2.authorization.getDecisionBulk({ ... }) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `decisionRequests` | `[]GetDecisionMultiResourceRequest` | Yes | Each entry contains an entity, action, and one or more resources to evaluate. | +| `decisionRequests` | [`[]GetDecisionMultiResourceRequest`](#getdecisionmultiresourcerequest) | Yes | Each entry contains an entity, action, and one or more resources to evaluate. | + +### GetDecisionMultiResourceRequest Each `GetDecisionMultiResourceRequest` contains: | Field | Type | Required | Description | |-------|------|----------|-------------| | `entityIdentifier` | [`EntityIdentifier`](#entityidentifier) | Yes | The entity requesting access. | -| `action` | `Action` | Yes | The action being performed. | +| `action` | [`Action`](/sdks/policy#action) | Yes | The action being performed. | | `resources` | [`[]Resource`](#resource) | Yes | Resources to evaluate, each with an `ephemeralId` for correlation. | **Example** @@ -1114,7 +1116,7 @@ Returned by [GetEntitlements](#getentitlements). One per entity, mapping attribu | Field | Type | Description | |-------|------|-------------| | `ephemeralId` | `string` | Correlates with the entity in the request. | -| `actionsPerAttributeValueFqn` | `map` | Keys are attribute value FQNs. Values are lists of [actions](/sdks/policy#action) the entity can perform on data carrying that attribute value. | +| `actionsPerAttributeValueFqn` | [`map`](#actionslist) | Keys are attribute value FQNs. Values are lists of [actions](/sdks/policy#action) the entity can perform on data carrying that attribute value. | ```go for _, e := range resp.GetEntitlements() { @@ -1132,6 +1134,16 @@ for (const e of resp.entitlements) { } ``` +### ActionsList + +A thin wrapper around a list of [`Action`](/sdks/policy#action) used as the value type in `EntityEntitlements.actionsPerAttributeValueFqn`. The wrapper exists because protobuf maps cannot have repeated value types directly. + +| Field | Type | Description | +|-------|------|-------------| +| `actions` | [`[]Action`](/sdks/policy#action) | The actions the entity can perform on data carrying the keyed attribute value. | + +In Go, reach the underlying slice with `actionsList.GetActions()`. In Java, `actionsList.getActionsList()`. In JavaScript, the value is surfaced directly as an `Actions` object whose `.actions` field is the array. + ### GetDecisionMultiResourceResponse Returned by [GetDecisionBulk](#getdecisionbulk). One per entity+action combination in the request. diff --git a/docs/sdks/platform-client.mdx b/docs/sdks/platform-client.mdx index 6995b5cc..0e11aca2 100644 --- a/docs/sdks/platform-client.mdx +++ b/docs/sdks/platform-client.mdx @@ -6,6 +6,7 @@ title: Overview 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'; # Overview @@ -90,6 +91,37 @@ const platform = new PlatformClient({ ...auth, platformUrl: 'http://localhost:80 +## Health checks + +`IsHealthy` reports whether the platform is reachable and serving requests. Use it in readiness probes, smoke tests, or to gate startup logic on platform availability. + + + +```go +healthy, err := client.IsHealthy(ctx) +if err != nil { + // err is sdk.ErrHealthCheckUnsupported (IPC mode), or wraps + // sdk.ErrPlatformUnreachable on transport failure or ctx cancellation + log.Printf("health check failed: %v", err) + return +} +if !healthy { + // reachable, but reports NOT_SERVING or UNKNOWN + log.Println("platform is not ready") +} +``` + +The check honors the supplied `context.Context` for deadlines and cancellation, and propagates OTEL tracing when `otelconnect.NewInterceptor` is registered via `WithExtraClientOptions`. + +### Return values + +| Result | Meaning | +|---|---| +| `(true, nil)` | Platform reports `SERVING`. | +| `(false, nil)` | Platform is reachable but reports `NOT_SERVING` or `UNKNOWN`. | +| `(false, err)` | Transport failure or context cancellation. The error wraps `sdk.ErrPlatformUnreachable`. | +| `(false, sdk.ErrHealthCheckUnsupported)` | The SDK is configured in IPC mode, which does not support health checks. | + ## Response Objects All platform API calls return protobuf response objects. The way you access fields differs by language: **Go** uses generated getter methods prefixed with `Get`, **Java** uses standard getters, and **JavaScript** uses direct property access with optional chaining. diff --git a/docs/sdks/policy.mdx b/docs/sdks/policy.mdx index 65e6a6cb..fec4316a 100644 --- a/docs/sdks/policy.mdx +++ b/docs/sdks/policy.mdx @@ -1616,7 +1616,7 @@ await platform.v1.subjectMapping.updateSubjectConditionSet({ ... }) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` (UUID) | Yes | The subject condition set ID to update. | -| `subjectSets` | `[]SubjectSet` | No | Replaces the entire condition tree. Omit to update metadata only. | +| `subjectSets` | [`[]SubjectSet`](#subjectset) | No | Replaces the entire condition tree. Omit to update metadata only. | | `metadata` | [`Metadata`](#metadata) | No | Optional [labels](#metadata). | | `metadataUpdateBehavior` | `string` | No | `METADATA_UPDATE_ENUM_REPLACE` or `METADATA_UPDATE_ENUM_EXTEND` (default). | @@ -2345,7 +2345,7 @@ await platform.v1.subjectMapping.matchSubjectMappings({ ... }) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `subjectProperties` | `[]SubjectProperty` | Yes | Key-value pairs from an entity's claims. Each has `externalSelectorValue` (the claim path, e.g., `.clientId`) and `externalValue` (the claim value). | +| `subjectProperties` | [`[]SubjectProperty`](#subjectproperty) | Yes | Key-value pairs from an entity's claims. Each has `externalSelectorValue` (the claim path, e.g., `.clientId`) and `externalValue` (the claim value). | **Example** diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index 592be43e..9baa9727 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -628,7 +628,7 @@ func (s SDK) PrepareBulkDecrypt(ctx context.Context, opts ...BulkDecryptOption) |-------|------|-------------| | `Reader` | `io.ReadSeeker` | Source of the encrypted TDF. | | `Writer` | `io.Writer` | Destination for the decrypted plaintext. | -| `TriggeredObligations` | `RequiredObligations` | Populated after rewrap with obligation FQNs required by this TDF. See [Obligations in bulk decrypt](#obligations-in-bulk-decrypt). | +| `TriggeredObligations` | [`RequiredObligations`](#requiredobligations) | Populated after rewrap with obligation FQNs required by this TDF. See [Obligations in bulk decrypt](#obligations-in-bulk-decrypt). | **Options** @@ -1423,19 +1423,19 @@ The `Manifest` type is returned by [`CreateTDF`](#createtdf) and accessible via | Field | Type | Description | |-------|------|-------------| | `TDFVersion` | `string` | TDF spec version (e.g. `"4.3.0"`). Serialized as `schemaVersion` in the manifest JSON. | -| `EncryptionInformation` | `EncryptionInformation` | Encryption method, key access objects, and integrity information. | -| `Payload` | `Payload` | Metadata about the encrypted payload. | -| `Assertions` | `[]Assertion` | Cryptographically bound or signed statements attached to the TDF. Empty if none were added at encrypt time. | +| `EncryptionInformation` | [`EncryptionInformation`](#encryptioninformation) | Encryption method, key access objects, and integrity information. | +| `Payload` | [`Payload`](#manifest-payload) | Metadata about the encrypted payload. | +| `Assertions` | [`[]Assertion`](#assertion) | Cryptographically bound or signed statements attached to the TDF. Empty if none were added at encrypt time. | -**EncryptionInformation Fields** +#### EncryptionInformation | Field | Type | Description | |-------|------|-------------| -| `KeyAccessObjs` | `[]KeyAccess` | One entry per KAS holding a key grant. Split TDFs have multiple entries. | +| `KeyAccessObjs` | [`[]KeyAccess`](#keyaccess) | One entry per KAS holding a key grant. Split TDFs have multiple entries. | | `Method.Algorithm` | `string` | Encryption algorithm (e.g. `"AES-256-GCM"`). | | `Policy` | `string` | Base64-encoded policy object. Use [`tdfReader.Policy()`](#policy) to decode. | -**KeyAccess Fields** +#### KeyAccess | Field | Type | Description | |-------|------|-------------| @@ -1444,7 +1444,7 @@ The `Manifest` type is returned by [`CreateTDF`](#createtdf) and accessible via | `SplitID` | `string` | Key split identifier. Entries sharing the same ID share a key segment; different IDs represent independent splits. | | `KID` | `string` | Key identifier on the KAS, if set. | -**Payload Fields** +#### Payload (manifest field) {#manifest-payload} | Field | Type | Description | |-------|------|-------------| @@ -1503,11 +1503,24 @@ for _, a := range manifest.Assertions { | Field | Type | Description | |-------|------|-------------| | `ID` | `string` | Assertion identifier (matches the `AssertionConfig.ID` used at encrypt time). | -| `Type` | `AssertionType` | `"handling"` or `"other"`. | -| `Scope` | `Scope` | `"tdo"` or `"payload"`. | -| `AppliesToState` | `AppliesToState` | `"encrypted"` or `"unencrypted"`. | -| `Statement` | `Statement` | The assertion content. | -| `Binding` | `Binding` | Cryptographic binding — `Method` (`"jws"`) and `Signature` (JWS token). | +| `Type` | [`AssertionType`](#assertion-types) | `"handling"` or `"other"`. | +| `Scope` | [`Scope`](#scopes) | `"tdo"` or `"payload"`. | +| `AppliesToState` | [`AppliesToState`](#appliestostate) | `"encrypted"` or `"unencrypted"`. | +| `Statement` | [`Statement`](#statement-type) | The assertion content. | +| `Binding` | [`Binding`](#binding) | Cryptographic binding — `Method` (`"jws"`) and `Signature` (JWS token). | + +--- + +### Binding + +The cryptographic binding attached to a signed [`Assertion`](#assertion). + +**Fields** + +| Field | Type | Description | +|-------|------|-------------| +| `Method` | `string` | Binding method. Currently `"jws"`. | +| `Signature` | `string` | The JWS token that binds the assertion to the TDF. | --- @@ -1542,11 +1555,25 @@ Passed to `WithAssertionVerificationKeys` when loading a TDF. Maps assertion IDs | Field | Type | Description | |-------|------|-------------| -| `DefaultKey` | `AssertionKey` | Fallback key used when no ID-specific key is found. | +| `DefaultKey` | [`AssertionKey`](#assertionkey) | Fallback key used when no ID-specific key is found. | | `Keys` | `map[string]AssertionKey` | Map of assertion ID to verification key. | --- +### RequiredObligations + +Returned by [`Reader.Obligations()`](#obligations) and populated on each `BulkTDF.TriggeredObligations` field after [`PrepareBulkDecrypt`](#bulkdecrypt). Wraps the obligation FQNs the platform requires the consuming application to enforce before granting access to the TDF's payload. + +Supported in the Go and JavaScript SDKs. + +**Fields** + +| Field | Go | JavaScript | Description | +|-------|-----|------------|-------------| +| FQNs / fqns | `FQNs []string` | `fqns: string[]` | Obligation value FQNs required for this TDF. Empty when no obligations are triggered. | + +--- + ---