From 4be13ffbe7fb6dccf07fcd02973650a3a1286b27 Mon Sep 17 00:00:00 2001 From: Bernat Date: Fri, 4 Sep 2026 18:13:33 +0200 Subject: [PATCH 1/4] KMP SDK Doc update --- .../context-manager.md | 907 +++++++++++++++--- docs/kotlin-multiplatform-sdk/initialize.md | 20 + 2 files changed, 784 insertions(+), 143 deletions(-) diff --git a/docs/kotlin-multiplatform-sdk/context-manager.md b/docs/kotlin-multiplatform-sdk/context-manager.md index 5525b321..f0bd73be 100644 --- a/docs/kotlin-multiplatform-sdk/context-manager.md +++ b/docs/kotlin-multiplatform-sdk/context-manager.md @@ -7,628 +7,1249 @@ required when setting the operation context, authentication tokens, and other se All the values that are provided to the context manager are automatically stored in [secure storage](initialize.md#secure-storage). ::: -## Set operation context +## Set API environment -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +Changes the environment the SDK operates against. It can be changed at any time, although it is recommended to +set it up through the [SdkConfig builder](initialize.md#sdk-config-builder) instead. + +:::info +Not available on **C#** and **Python** — pass the environment to the constructor on those platforms. +::: ```kotlin showLineNumbers -sdk.contextManager().setOperationContext( - userId = USER_ID, - certificateChain = USER_CERTIFICATE_CHAIN_LIST, - keyPair = KEY_PAIR, - isKeyPairVerified = IS_KEY_PAIR_VERIFIED -) +sdk.contextManager().setApiEnvironment(ApiEnvironment.PROD) ``` ```java showLineNumbers -sdk.contextManager().setOperationContext(USER_ID, USER_CERTIFICATE_CHAIN_LIST, KEY_PAIR, IS_KEY_PAIR_VERIFIED); +sdk.contextManager().setApiEnvironment(ApiEnvironment.PROD); ``` ```swift showLineNumbers -sdk.contextManager().setOperationContext( - userId: USER_ID, - certificateChain: USER_CERTIFICATE_CHAIN_LIST, - publicKey: PUBLIC_KEY, - privateKey: PRIVATE_KEY, - isKeyPairVerified: IS_KEY_PAIR_VERIFIED -) +sdk.contextManager().setApiEnvironment(apiEnvironment: ApiEnvironment.prod) ``` ```js showLineNumbers -sdk.contextManager().setOperationContext( - "USER_ID", - USER_CERTIFICATE_CHAIN_LIST, - PUBLIC_KEY, - PRIVATE_KEY -); +sdk.contextManager().setApiEnvironment("PROD"); +``` + + + + +## Get API environment + +Returns the environment the SDK is currently operating against. Defaults to `PROD` when it has never been set. + + + + +```kotlin showLineNumbers +// Returns an ApiEnvironment +val apiEnvironment = sdk.contextManager().getApiEnvironment() +``` + + + + +```java showLineNumbers +// Returns an ApiEnvironment +var apiEnvironment = sdk.contextManager().getApiEnvironment(); +``` + + + + +```swift showLineNumbers +// Returns an ApiEnvironment +let apiEnvironment = sdk.contextManager().getApiEnvironment() +``` + + + + +```js showLineNumbers +// Returns a string +const apiEnvironment = sdk.contextManager().getApiEnvironment(); ``` ```csharp showLineNumbers -sdk.GetContextManager().SetOperationContext( - userId: USER_ID, - certificateChain: USER_CERTIFICATE_CHAIN, - publicKey: PUBLIC_KEY, - privateKey: PRIVATE_KEY -); +// Returns an ApiEnvironment +var apiEnvironment = sdk.GetContextManager().GetApiEnvironment(); ``` ```python showLineNumbers -sdk.contextManager.set_operation_context( - "USER_ID", - "USER_CERTIFICATE_CHAIN_AS_STRING", - "BASE64_PUBLIC_KEY", - "BASE64_PRIVATE_KEY" -) +# Returns a str +apiEnvironment = sdk.contextManager.get_api_environment() ``` -## Get Context State +## Set cloud auth token -Checks the state of the context by verifying that the [auth token is valid](#is-cloud-auth-token-invalid-or-expired), -the [key pair is valid](#is-key-pair-valid) and [verified](#is-key-pair-verified), -and the [certificate chain is valid](#is-certificate-chain-invalid-or-expired). -When **checkServerInvalidation** is set to **true**, it also checks if the auth token has been invalidated on the backend. -This requires a network request. When **checkServerInvalidation** is **false**, this server check is skipped, -meaning the auth token might be accepted even if it has been invalidated. +If the SDK was initialized without an authentication token, you can provide or update the token using this function. ```kotlin showLineNumbers -// Returns a ContextState -val result = sdk.contextManager().getContextState(true) +sdk.contextManager().setCloudAuthToken("AUTH_TOKEN") ``` ```java showLineNumbers -// Returns a CompletableFuture -var result = sdk.contextManager().getContextStateAsync(true); +sdk.contextManager().setCloudAuthToken("AUTH_TOKEN"); ``` ```swift showLineNumbers -// Returns a ContextState asynchronously -let result = await sdk.contextManager().getContextState(checkServerInvalidation: true) +sdk.contextManager().setCloudAuthToken(token: "AUTH_TOKEN") ``` ```js showLineNumbers -// Returns a Promise -const result = await sdk.contextManager().getContextState(true); +sdk.contextManager().setCloudAuthToken("AUTH_TOKEN"); ``` ```csharp showLineNumbers -// Returns a Task -var result = await sdk.GetContextManager().GetContextState(checkServerInvalidation: true); +sdk.GetContextManager().SetCloudAuthToken("AUTH_TOKEN"); ``` ```python showLineNumbers -# Returns a Future[SimpleNamespace] -result = await sdk.contextManager.get_context_state(True) +sdk.contextManager.set_cloud_auth_token("AUTH_TOKEN") ``` -## Is certificate chain invalid or expired - -Checks if the current certificate chain from the context is invalid or expired -(we consider it expired if it will expire within the next 7 days). +## Get cloud auth token ```kotlin showLineNumbers -val result = sdk.contextManager().isCertificateChainInvalidOrExpired() +val token = sdk.contextManager().getCloudAuthToken() ``` ```java showLineNumbers -var result = sdk.contextManager().isCertificateChainInvalidOrExpired(); +var token = sdk.contextManager().getCloudAuthToken(); ``` ```swift showLineNumbers -let result = sdk.contextManager().isCertificateChainInvalidOrExpired() +let token = sdk.contextManager().getCloudAuthToken() ``` ```js showLineNumbers -const result = sdk.contextManager().isCertificateChainInvalidOrExpired(); +const token = sdk.contextManager().getCloudAuthToken(); ``` ```csharp showLineNumbers -var result = sdk.GetContextManager().IsCertificateChainInvalidOrExpired(); +var token = sdk.GetContextManager().GetCloudAuthToken(); ``` ```python showLineNumbers -result = sdk.contextManager.is_certificate_chain_invalid_or_expired() +token = sdk.contextManager.get_cloud_auth_token() ``` -## Is key pair valid +## Is cloud auth token invalid or expired -Checks if the current key pair from the context is valid. +Checks if the current cloud auth token from the context is invalid, expired +(we consider it expired if it will expire within the next 24 hours) or invalidated. +When **checkServerInvalidation** is set to **true**, it also checks if the auth token has been invalidated on the backend. +This requires a network request. When **checkServerInvalidation** is **false**, this server check is skipped, +meaning the auth token might be accepted even if it has been invalidated on the server. ```kotlin showLineNumbers -val result = sdk.contextManager().isKeyPairValid() +// Returns a Boolean +val result = sdk.contextManager().isCloudAuthTokenInvalidOrExpired(true) ``` ```java showLineNumbers -var result = sdk.contextManager().isKeyPairValid(); +// Returns a CompletableFuture +var result = sdk.contextManager().isCloudAuthTokenInvalidOrExpiredAsync(true); ``` ```swift showLineNumbers -let result = sdk.contextManager().isKeyPairValid() +// Returns a Bool asynchronously +let result = await sdk.contextManager().isCloudAuthTokenInvalidOrExpired(checkServerInvalidation: true) ``` ```js showLineNumbers -const result = sdk.contextManager().isKeyPairValid(); +// Returns a Promise +const result = await sdk.contextManager().isCloudAuthTokenInvalidOrExpired(true); ``` ```csharp showLineNumbers -var result = sdk.GetContextManager().IsKeyPairValid(); +// Returns a Task +var result = await sdk.GetContextManager().IsCloudAuthTokenInvalidOrExpired(checkServerInvalidation: true); ``` ```python showLineNumbers -result = sdk.contextManager.is_key_pair_valid() +# Returns a Future[SimpleNamespace] +result = await sdk.contextManager.is_cloud_auth_token_invalid_or_expired(True) ``` -## Is key pair verified - -Checks if the current key pair from the context has been verified. +## Set cloud refresh token ```kotlin showLineNumbers -val result = sdk.contextManager().isKeyPairVerified() +sdk.contextManager().setCloudRefreshToken("REFRESH_TOKEN") ``` ```java showLineNumbers -var result = sdk.contextManager().isKeyPairVerified(); +sdk.contextManager().setCloudRefreshToken("REFRESH_TOKEN"); ``` ```swift showLineNumbers -let result = sdk.contextManager().isKeyPairVerified() +sdk.contextManager().setCloudRefreshToken(token: "REFRESH_TOKEN") ``` ```js showLineNumbers -const result = sdk.contextManager().isKeyPairVerified(); +sdk.contextManager().setCloudRefreshToken("REFRESH_TOKEN"); ``` ```csharp showLineNumbers -var result = sdk.GetContextManager().IsKeyPairVerified(); +sdk.GetContextManager().SetCloudRefreshToken("REFRESH_TOKEN"); ``` ```python showLineNumbers -result = sdk.contextManager.is_key_pair_verified() +sdk.contextManager.set_cloud_refresh_token("REFRESH_TOKEN") ``` -## Set cloud auth token - -If the SDK was initialized without an authentication token, you can provide or update the token using this function. +## Get cloud refresh token ```kotlin showLineNumbers -sdk.contextManager().setCloudAuthToken("AUTH_TOKEN") +val token = sdk.contextManager().getCloudRefreshToken() ``` ```java showLineNumbers -sdk.contextManager().setCloudAuthToken("AUTH_TOKEN"); +var token = sdk.contextManager().getCloudRefreshToken(); ``` ```swift showLineNumbers -sdk.contextManager().setCloudAuthToken(token: "AUTH_TOKEN") +let token = sdk.contextManager().getCloudRefreshToken() ``` ```js showLineNumbers -sdk.contextManager().setCloudAuthToken("AUTH_TOKEN"); +const token = sdk.contextManager().getCloudRefreshToken(); ``` ```csharp showLineNumbers -sdk.GetContextManager().SetCloudAuthToken("AUTH_TOKEN"); +var token = sdk.GetContextManager().GetCloudRefreshToken(); ``` ```python showLineNumbers -sdk.contextManager.set_cloud_auth_token("AUTH_TOKEN") +token = sdk.contextManager.get_cloud_refresh_token() ``` -## Get cloud auth token +## Set fusion host + +Sets the host of the on-premise Fusion server used by the [fusion resource](fusion.md). It can be changed at any +time, although it is recommended to set it up through the [SdkConfig builder](initialize.md#sdk-config-builder) +instead. ```kotlin showLineNumbers -val token = sdk.contextManager().getCloudAuthToken() +sdk.contextManager().setFusionHost(URI("http://localhost:27700")) ``` ```java showLineNumbers -var token = sdk.contextManager().getCloudAuthToken(); +sdk.contextManager().setFusionHost(URI.create("http://localhost:27700")); ``` ```swift showLineNumbers -let token = sdk.contextManager().getCloudAuthToken() +sdk.contextManager().setFusionHost(host: NSURLComponents(string: "http://localhost:27700")!) ``` ```js showLineNumbers -const token = sdk.contextManager().getCloudAuthToken(); +sdk.contextManager().setFusionHost("http://localhost:27700"); ``` ```csharp showLineNumbers -var token = sdk.GetContextManager().GetCloudAuthToken(); +sdk.GetContextManager().SetFusionHost("http://localhost:27700"); ``` ```python showLineNumbers -token = sdk.contextManager.get_cloud_auth_token() +sdk.contextManager.set_fusion_host("http://localhost:27700") ``` -## Is cloud auth token invalid or expired +## Get fusion host -Checks if the current cloud auth token from the context is invalid, expired -(we consider it expired if it will expire within the next 24 hours) or invalidated. -When **checkServerInvalidation** is set to **true**, it also checks if the auth token has been invalidated on the backend. -This requires a network request. When **checkServerInvalidation** is **false**, this server check is skipped, -meaning the auth token might be accepted even if it has been invalidated on the server. +Returns the currently configured Fusion host. Defaults to `http://localhost:27700` when it has never been set. ```kotlin showLineNumbers -// Returns a Boolean -val result = sdk.contextManager().isCloudAuthTokenInvalidOrExpired(true) +// Returns a URI +val fusionHost = sdk.contextManager().getFusionHost() ``` ```java showLineNumbers -// Returns a CompletableFuture -var result = sdk.contextManager().isCloudAuthTokenInvalidOrExpiredAsync(true); +// Returns a URI +var fusionHost = sdk.contextManager().getFusionHost(); ``` ```swift showLineNumbers -// Returns a Bool asynchronously -let result = await sdk.contextManager().isCloudAuthTokenInvalidOrExpired(checkServerInvalidation: true) +// Returns an NSURLComponents +let fusionHost = sdk.contextManager().getFusionHost() ``` ```js showLineNumbers -// Returns a Promise -const result = await sdk.contextManager().isCloudAuthTokenInvalidOrExpired(true); +// Returns a string +const fusionHost = sdk.contextManager().getFusionHost(); ``` ```csharp showLineNumbers -// Returns a Task -var result = await sdk.GetContextManager().IsCloudAuthTokenInvalidOrExpired(checkServerInvalidation: true); +// Returns a string +var fusionHost = sdk.GetContextManager().GetFusionHost(); ``` ```python showLineNumbers -# Returns a Future[SimpleNamespace] -result = await sdk.contextManager.is_cloud_auth_token_invalid_or_expired(True) +# Returns a str +fusionHost = sdk.contextManager.get_fusion_host() ``` -## Set cloud refresh token +## Set fusion auth token ```kotlin showLineNumbers -sdk.contextManager().setCloudRefreshToken("REFRESH_TOKEN") +sdk.contextManager().setFusionAuthToken("FUSION_AUTH_TOKEN") ``` ```java showLineNumbers -sdk.contextManager().setCloudRefreshToken("REFRESH_TOKEN"); +sdk.contextManager().setFusionAuthToken("FUSION_AUTH_TOKEN"); ``` ```swift showLineNumbers -sdk.contextManager().setCloudRefreshToken(token: "REFRESH_TOKEN") +sdk.contextManager().setFusionAuthToken(token: "FUSION_AUTH_TOKEN") ``` ```js showLineNumbers -sdk.contextManager().setCloudRefreshToken("REFRESH_TOKEN"); +sdk.contextManager().setFusionAuthToken("FUSION_AUTH_TOKEN"); ``` ```csharp showLineNumbers -sdk.GetContextManager().SetCloudRefreshToken("REFRESH_TOKEN"); +sdk.GetContextManager().SetFusionAuthToken("FUSION_AUTH_TOKEN"); ``` ```python showLineNumbers -sdk.contextManager.set_cloud_refresh_token("REFRESH_TOKEN") +sdk.contextManager.set_fusion_auth_token("FUSION_AUTH_TOKEN") ``` -## Get cloud refresh token +## Get fusion auth token ```kotlin showLineNumbers -val token = sdk.contextManager().getCloudRefreshToken() +val token = sdk.contextManager().getFusionAuthToken() ``` ```java showLineNumbers -var token = sdk.contextManager().getCloudRefreshToken(); +var token = sdk.contextManager().getFusionAuthToken(); ``` ```swift showLineNumbers -let token = sdk.contextManager().getCloudRefreshToken() +let token = sdk.contextManager().getFusionAuthToken() ``` ```js showLineNumbers -const token = sdk.contextManager().getCloudRefreshToken(); +const token = sdk.contextManager().getFusionAuthToken(); ``` ```csharp showLineNumbers -var token = sdk.GetContextManager().GetCloudRefreshToken(); +var token = sdk.GetContextManager().GetFusionAuthToken(); ``` ```python showLineNumbers -token = sdk.contextManager.get_cloud_refresh_token() +token = sdk.contextManager.get_fusion_auth_token() ``` -## Set fusion auth token +## Set user ID + +Sets the user identifier used by the secure [lock operations](lock-operations.md). It is usually set for you by +[set operation context](#set-operation-context). ```kotlin showLineNumbers -sdk.contextManager().setFusionAuthToken("FUSION_AUTH_TOKEN") +sdk.contextManager().setUserId(USER_ID) ``` ```java showLineNumbers -sdk.contextManager().setFusionAuthToken("FUSION_AUTH_TOKEN"); +sdk.contextManager().setUserId(USER_ID); ``` ```swift showLineNumbers -sdk.contextManager().setFusionAuthToken(token: "FUSION_AUTH_TOKEN") +sdk.contextManager().setUserId(userId: USER_ID) ``` ```js showLineNumbers -sdk.contextManager().setFusionAuthToken("FUSION_AUTH_TOKEN"); +sdk.contextManager().setUserId("USER_ID"); ``` ```csharp showLineNumbers -sdk.GetContextManager().SetFusionAuthToken("FUSION_AUTH_TOKEN"); +sdk.GetContextManager().SetUserId(USER_ID); ``` ```python showLineNumbers -sdk.contextManager.set_fusion_auth_token("FUSION_AUTH_TOKEN") +sdk.contextManager.set_user_id("USER_ID") ``` -## Get fusion auth token +## Get user ID ```kotlin showLineNumbers -val token = sdk.contextManager().getFusionAuthToken() +// Returns a UUID +val userId = sdk.contextManager().getUserId() ``` ```java showLineNumbers -var token = sdk.contextManager().getFusionAuthToken(); +// Returns a UUID +var userId = sdk.contextManager().getUserId(); ``` ```swift showLineNumbers -let token = sdk.contextManager().getFusionAuthToken() +// Returns an NSUUID +let userId = sdk.contextManager().getUserId() ``` ```js showLineNumbers -const token = sdk.contextManager().getFusionAuthToken(); +// Returns a string +const userId = sdk.contextManager().getUserId(); ``` ```csharp showLineNumbers -var token = sdk.GetContextManager().GetFusionAuthToken(); +// Returns a Guid +var userId = sdk.GetContextManager().GetUserId(); ``` ```python showLineNumbers -token = sdk.contextManager.get_fusion_auth_token() +# Returns a str +userId = sdk.contextManager.get_user_id() +``` + + + + +## Set user email + +Sets the email address associated with the context. It is set automatically by +[login](accountless.md#login) and [registration](accountless.md#register-a-new-user). + + + + +```kotlin showLineNumbers +sdk.contextManager().setUserEmail("EMAIL") +``` + + + + +```java showLineNumbers +sdk.contextManager().setUserEmail("EMAIL"); +``` + + + + +```swift showLineNumbers +sdk.contextManager().setUserEmail(email: "EMAIL") +``` + + + + +```js showLineNumbers +sdk.contextManager().setUserEmail("EMAIL"); +``` + + + + +```csharp showLineNumbers +sdk.GetContextManager().SetUserEmail("EMAIL"); +``` + + + + +```python showLineNumbers +sdk.contextManager.set_user_email("EMAIL") +``` + + + + +## Get user email + + + + +```kotlin showLineNumbers +val email = sdk.contextManager().getUserEmail() +``` + + + + +```java showLineNumbers +var email = sdk.contextManager().getUserEmail(); +``` + + + + +```swift showLineNumbers +let email = sdk.contextManager().getUserEmail() +``` + + + + +```js showLineNumbers +const email = sdk.contextManager().getUserEmail(); +``` + + + + +```csharp showLineNumbers +var email = sdk.GetContextManager().GetUserEmail(); +``` + + + + +```python showLineNumbers +email = sdk.contextManager.get_user_email() +``` + + + + +## Set certificate chain + +Sets the certificate chain used to sign the secure [lock operations](lock-operations.md). It is usually set for +you by [set operation context](#set-operation-context) or by +[register ephemeral key](account.md#register-ephemeral-key). + +:::info +* Only the **first** certificate of the chain is inspected by + [is certificate chain invalid or expired](#is-certificate-chain-invalid-or-expired). +* Not available on **C#** and **Python** — use [set operation context](#set-operation-context) instead. + ::: + + + + +```kotlin showLineNumbers +sdk.contextManager().setCertificateChain(USER_CERTIFICATE_CHAIN_LIST) +``` + + + + +```java showLineNumbers +sdk.contextManager().setCertificateChain(USER_CERTIFICATE_CHAIN_LIST); +``` + + + + +```swift showLineNumbers +sdk.contextManager().setCertificateChain(certificateChain: USER_CERTIFICATE_CHAIN_LIST) +``` + + + + +```js showLineNumbers +sdk.contextManager().setCertificateChain(USER_CERTIFICATE_CHAIN_LIST); +``` + + + + +## Get certificate chain + +Returns the stored certificate chain, or **null** when none has been set. + +:::info +On Kotlin and Java the chain is returned as `X509Certificate` objects; on Swift and JavaScript as base64 +encoded strings. Not available on **C#** and **Python**. +::: + + + + +```kotlin showLineNumbers +// Returns a List +val certificateChain = sdk.contextManager().getCertificateChain() +``` + + + + +```java showLineNumbers +// Returns a List +var certificateChain = sdk.contextManager().getCertificateChain(); +``` + + + + +```swift showLineNumbers +// Returns a [String] +let certificateChain = sdk.contextManager().getCertificateChain() +``` + + + + +```js showLineNumbers +// Returns a string[] +const certificateChain = sdk.contextManager().getCertificateChain(); +``` + + + + +## Is certificate chain invalid or expired + +Checks if the current certificate chain from the context is invalid or expired +(we consider it expired if it will expire within the next 7 days). + + + + +```kotlin showLineNumbers +val result = sdk.contextManager().isCertificateChainInvalidOrExpired() +``` + + + + +```java showLineNumbers +var result = sdk.contextManager().isCertificateChainInvalidOrExpired(); +``` + + + + +```swift showLineNumbers +let result = sdk.contextManager().isCertificateChainInvalidOrExpired() +``` + + + + +```js showLineNumbers +const result = sdk.contextManager().isCertificateChainInvalidOrExpired(); +``` + + + + +```csharp showLineNumbers +var result = sdk.GetContextManager().IsCertificateChainInvalidOrExpired(); +``` + + + + +```python showLineNumbers +result = sdk.contextManager.is_certificate_chain_invalid_or_expired() +``` + + + + +## Set key pair + +Sets the key pair used to sign the secure [lock operations](lock-operations.md). It is usually set for you by +[set operation context](#set-operation-context), [assisted login](helper.md#assisted-login) or +[assisted register](helper.md#assisted-register). + +:::info +* Setting a new key pair does **not** mark it as verified. Use [set key pair verified](#set-key-pair-verified), + or register it through [register ephemeral key](account.md#register-ephemeral-key). +* Keys generated on any platform are accepted — see [crypto](crypto.md) for the supported encodings. +* Not available on **C#** and **Python** — use [set operation context](#set-operation-context) instead. + ::: + + + + +```kotlin showLineNumbers +sdk.contextManager().setKeyPair(KEY_PAIR) +``` + + + + +```java showLineNumbers +sdk.contextManager().setKeyPair(KEY_PAIR); +``` + + + + +```swift showLineNumbers +sdk.contextManager().setKeyPair( + publicKey: PUBLIC_KEY, + privateKey: PRIVATE_KEY +) +``` + + + + +```js showLineNumbers +sdk.contextManager().setKeyPair(PUBLIC_KEY, PRIVATE_KEY); +``` + + + + +## Get key pair + +Returns the stored key pair, or **null** when either the public or the private key is missing. + +:::info +Not available on **C#** and **Python**. +::: + + + + +```kotlin showLineNumbers +// Returns a KeyPair +val keyPair = sdk.contextManager().getKeyPair() +``` + + + + +```java showLineNumbers +// Returns a KeyPair +var keyPair = sdk.contextManager().getKeyPair(); +``` + + + + +```swift showLineNumbers +// Returns a Crypto.KeyPair +let keyPair = sdk.contextManager().getKeyPair() +``` + + + + +```js showLineNumbers +// Returns a Crypto.KeyPair +const keyPair = sdk.contextManager().getKeyPair(); +``` + + + + +## Set key pair verified + +Marks a public key as verified, meaning it has successfully completed +[two-factor verification](account.md#verify-ephemeral-key-registration). Pass **null** to clear the verification. + +:::info +* [Is key pair verified](#is-key-pair-verified) compares the value stored here against the current public key, so + setting a key pair that does not match clears the verified state in practice. +* Not available on **C#** and **Python** — use the `isKeyPairVerified` flag of + [set operation context](#set-operation-context) instead. + ::: + + + + +```kotlin showLineNumbers +sdk.contextManager().setKeyPairVerified(PUBLIC_KEY) +``` + + + + +```java showLineNumbers +sdk.contextManager().setKeyPairVerified(PUBLIC_KEY); +``` + + + + +```swift showLineNumbers +sdk.contextManager().setKeyPairVerified(publicKey: PUBLIC_KEY) +``` + + + + +```js showLineNumbers +sdk.contextManager().setKeyPairVerified(PUBLIC_KEY); +``` + + + + +## Is key pair verified + +Checks if the current key pair from the context has been verified. + + + + +```kotlin showLineNumbers +val result = sdk.contextManager().isKeyPairVerified() +``` + + + + +```java showLineNumbers +var result = sdk.contextManager().isKeyPairVerified(); +``` + + + + +```swift showLineNumbers +let result = sdk.contextManager().isKeyPairVerified() +``` + + + + +```js showLineNumbers +const result = sdk.contextManager().isKeyPairVerified(); +``` + + + + +```csharp showLineNumbers +var result = sdk.GetContextManager().IsKeyPairVerified(); +``` + + + + +```python showLineNumbers +result = sdk.contextManager.is_key_pair_verified() +``` + + + + +## Is key pair valid + +Checks if the current key pair from the context is valid. + + + + +```kotlin showLineNumbers +val result = sdk.contextManager().isKeyPairValid() +``` + + + + +```java showLineNumbers +var result = sdk.contextManager().isKeyPairValid(); +``` + + + + +```swift showLineNumbers +let result = sdk.contextManager().isKeyPairValid() +``` + + + + +```js showLineNumbers +const result = sdk.contextManager().isKeyPairValid(); +``` + + + + +```csharp showLineNumbers +var result = sdk.GetContextManager().IsKeyPairValid(); +``` + + + + +```python showLineNumbers +result = sdk.contextManager.is_key_pair_valid() +``` + + + + +## Set operation context + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```kotlin showLineNumbers +sdk.contextManager().setOperationContext( + userId = USER_ID, + certificateChain = USER_CERTIFICATE_CHAIN_LIST, + keyPair = KEY_PAIR, + isKeyPairVerified = IS_KEY_PAIR_VERIFIED +) +``` + + + + +```java showLineNumbers +sdk.contextManager().setOperationContext(USER_ID, USER_CERTIFICATE_CHAIN_LIST, KEY_PAIR, IS_KEY_PAIR_VERIFIED); +``` + + + + +```swift showLineNumbers +sdk.contextManager().setOperationContext( + userId: USER_ID, + certificateChain: USER_CERTIFICATE_CHAIN_LIST, + publicKey: PUBLIC_KEY, + privateKey: PRIVATE_KEY, + isKeyPairVerified: IS_KEY_PAIR_VERIFIED +) +``` + + + + +```js showLineNumbers +sdk.contextManager().setOperationContext( + "USER_ID", + USER_CERTIFICATE_CHAIN_LIST, + PUBLIC_KEY, + PRIVATE_KEY +); +``` + + + + +```csharp showLineNumbers +sdk.GetContextManager().SetOperationContext( + userId: USER_ID, + certificateChain: USER_CERTIFICATE_CHAIN, + publicKey: PUBLIC_KEY, + privateKey: PRIVATE_KEY +); +``` + + + + +```python showLineNumbers +sdk.contextManager.set_operation_context( + "USER_ID", + "USER_CERTIFICATE_CHAIN_AS_STRING", + "BASE64_PUBLIC_KEY", + "BASE64_PRIVATE_KEY" +) +``` + + + + +## Get Context State + +Checks the state of the context by verifying that the [auth token is valid](#is-cloud-auth-token-invalid-or-expired), +the [key pair is valid](#is-key-pair-valid) and [verified](#is-key-pair-verified), +and the [certificate chain is valid](#is-certificate-chain-invalid-or-expired). +When **checkServerInvalidation** is set to **true**, it also checks if the auth token has been invalidated on the backend. +This requires a network request. When **checkServerInvalidation** is **false**, this server check is skipped, +meaning the auth token might be accepted even if it has been invalidated. + + + + +```kotlin showLineNumbers +// Returns a ContextState +val result = sdk.contextManager().getContextState(true) +``` + + + + +```java showLineNumbers +// Returns a CompletableFuture +var result = sdk.contextManager().getContextStateAsync(true); +``` + + + + +```swift showLineNumbers +// Returns a ContextState asynchronously +let result = await sdk.contextManager().getContextState(checkServerInvalidation: true) +``` + + + + +```js showLineNumbers +// Returns a Promise +const result = await sdk.contextManager().getContextState(true); +``` + + + + +```csharp showLineNumbers +// Returns a Task +var result = await sdk.GetContextManager().GetContextState(checkServerInvalidation: true); +``` + + + + +```python showLineNumbers +# Returns a Future[SimpleNamespace] +result = await sdk.contextManager.get_context_state(True) ``` diff --git a/docs/kotlin-multiplatform-sdk/initialize.md b/docs/kotlin-multiplatform-sdk/initialize.md index e18f7013..d5d3434f 100644 --- a/docs/kotlin-multiplatform-sdk/initialize.md +++ b/docs/kotlin-multiplatform-sdk/initialize.md @@ -50,6 +50,10 @@ val sdkConfig = SdkConfig.Builder() val sdk = KDoordeckFactory.initialize(sdkConfig) ``` +:::info +You should also call `sdk.release()` at the end of your application's lifecycle to release the SDK resources. +::: + @@ -60,6 +64,10 @@ var sdkConfig = SdkConfig.Builder() var sdk = KDoordeckFactory.INSTANCE.initializeAsync(sdkConfig); ``` +:::info +You should also call `sdk.release();` at the end of your application's lifecycle to release the SDK resources. +::: + @@ -70,6 +78,10 @@ let sdkConfig = SdkConfig.Builder() let sdk = await KDoordeckFactory().initialize(sdkConfig: sdkConfig) ``` +:::info +You should also call `sdk.release()` at the end of your application's lifecycle to release the SDK resources. +::: + @@ -83,6 +95,10 @@ const sdk = await com.doordeck.multiplatform.sdk.KDoordeckFactory.initialize( ); ``` +:::info +You should also call `sdk.release()` at the end of your application's lifecycle to release the SDK resources. +::: + @@ -101,5 +117,9 @@ You should also call `sdk.Release();` at the end of your application’s lifecyc sdk = doordeck_headless_sdk.InitializeSdk(cloud_auth_token="AUTH_TOKEN") ``` +:::info +You should also call `sdk.release()` at the end of your application's lifecycle to release the SDK resources. +::: + From 9a6515c84999ada9d4414658a961a663ed33a430 Mon Sep 17 00:00:00 2001 From: Bernat Date: Fri, 4 Sep 2026 19:00:56 +0200 Subject: [PATCH 2/4] wip [skip actions] --- .../context-manager.md | 111 ++++++++++++++---- 1 file changed, 88 insertions(+), 23 deletions(-) diff --git a/docs/kotlin-multiplatform-sdk/context-manager.md b/docs/kotlin-multiplatform-sdk/context-manager.md index f0bd73be..674c1394 100644 --- a/docs/kotlin-multiplatform-sdk/context-manager.md +++ b/docs/kotlin-multiplatform-sdk/context-manager.md @@ -12,10 +12,6 @@ All the values that are provided to the context manager are automatically stored Changes the environment the SDK operates against. It can be changed at any time, although it is recommended to set it up through the [SdkConfig builder](initialize.md#sdk-config-builder) instead. -:::info -Not available on **C#** and **Python** — pass the environment to the constructor on those platforms. -::: - @@ -44,6 +40,20 @@ sdk.contextManager().setApiEnvironment(apiEnvironment: ApiEnvironment.prod) sdk.contextManager().setApiEnvironment("PROD"); ``` + + + +```csharp showLineNumbers +// Not implemented yet +``` + + + + +```python showLineNumbers +// Not implemented yet +``` + @@ -758,10 +768,8 @@ you by [set operation context](#set-operation-context) or by [register ephemeral key](account.md#register-ephemeral-key). :::info -* Only the **first** certificate of the chain is inspected by - [is certificate chain invalid or expired](#is-certificate-chain-invalid-or-expired). -* Not available on **C#** and **Python** — use [set operation context](#set-operation-context) instead. - ::: +Only the **first** certificate of the chain is inspected by [is certificate chain invalid or expired](#is-certificate-chain-invalid-or-expired). +::: @@ -791,6 +799,20 @@ sdk.contextManager().setCertificateChain(certificateChain: USER_CERTIFICATE_CHAI sdk.contextManager().setCertificateChain(USER_CERTIFICATE_CHAIN_LIST); ``` + + + +```csharp showLineNumbers +// Not implemented yet +``` + + + + +```python showLineNumbers +// Not implemented yet +``` + @@ -798,11 +820,6 @@ sdk.contextManager().setCertificateChain(USER_CERTIFICATE_CHAIN_LIST); Returns the stored certificate chain, or **null** when none has been set. -:::info -On Kotlin and Java the chain is returned as `X509Certificate` objects; on Swift and JavaScript as base64 -encoded strings. Not available on **C#** and **Python**. -::: - @@ -835,6 +852,20 @@ let certificateChain = sdk.contextManager().getCertificateChain() const certificateChain = sdk.contextManager().getCertificateChain(); ``` + + + +```csharp showLineNumbers +// Not implemented yet +``` + + + + +```python showLineNumbers +// Not implemented yet +``` + @@ -898,7 +929,6 @@ Sets the key pair used to sign the secure [lock operations](lock-operations.md). * Setting a new key pair does **not** mark it as verified. Use [set key pair verified](#set-key-pair-verified), or register it through [register ephemeral key](account.md#register-ephemeral-key). * Keys generated on any platform are accepted — see [crypto](crypto.md) for the supported encodings. -* Not available on **C#** and **Python** — use [set operation context](#set-operation-context) instead. ::: @@ -932,6 +962,20 @@ sdk.contextManager().setKeyPair( sdk.contextManager().setKeyPair(PUBLIC_KEY, PRIVATE_KEY); ``` + + + +```csharp showLineNumbers +// Not implemented yet +``` + + + + +```python showLineNumbers +// Not implemented yet +``` + @@ -939,10 +983,6 @@ sdk.contextManager().setKeyPair(PUBLIC_KEY, PRIVATE_KEY); Returns the stored key pair, or **null** when either the public or the private key is missing. -:::info -Not available on **C#** and **Python**. -::: - @@ -975,6 +1015,20 @@ let keyPair = sdk.contextManager().getKeyPair() const keyPair = sdk.contextManager().getKeyPair(); ``` + + + +```csharp showLineNumbers +// Not implemented yet +``` + + + + +```python showLineNumbers +// Not implemented yet +``` + @@ -984,11 +1038,8 @@ Marks a public key as verified, meaning it has successfully completed [two-factor verification](account.md#verify-ephemeral-key-registration). Pass **null** to clear the verification. :::info -* [Is key pair verified](#is-key-pair-verified) compares the value stored here against the current public key, so - setting a key pair that does not match clears the verified state in practice. -* Not available on **C#** and **Python** — use the `isKeyPairVerified` flag of - [set operation context](#set-operation-context) instead. - ::: +[Is key pair verified](#is-key-pair-verified) compares the value stored here against the current public key, so setting a key pair that does not match clears the verified state in practice. +::: @@ -1018,6 +1069,20 @@ sdk.contextManager().setKeyPairVerified(publicKey: PUBLIC_KEY) sdk.contextManager().setKeyPairVerified(PUBLIC_KEY); ``` + + + +```csharp showLineNumbers +// Not implemented yet +``` + + + + +```python showLineNumbers +// Not implemented yet +``` + From d5be521a8423210d86e0bf98dda0554c49702a15 Mon Sep 17 00:00:00 2001 From: Bernat Date: Fri, 4 Sep 2026 19:21:09 +0200 Subject: [PATCH 3/4] wip --- .../context-manager.md | 29 ++++++++++++------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/kotlin-multiplatform-sdk/context-manager.md b/docs/kotlin-multiplatform-sdk/context-manager.md index 674c1394..79c9ed77 100644 --- a/docs/kotlin-multiplatform-sdk/context-manager.md +++ b/docs/kotlin-multiplatform-sdk/context-manager.md @@ -114,7 +114,8 @@ apiEnvironment = sdk.contextManager.get_api_environment() ## Set cloud auth token -If the SDK was initialized without an authentication token, you can provide or update the token using this function. +If the SDK was initialized without an authentication token, you can provide or update the token using this function, +also it is set automatically by [login](accountless.md#login), [register](accountless.md#register-a-new-user), and [refresh-token](account.md#request-a-new-refresh-token). @@ -269,6 +270,9 @@ result = await sdk.contextManager.is_cloud_auth_token_invalid_or_expired(True) ## Set cloud refresh token +It is set automatically by [login](accountless.md#login), [register](accountless.md#register-a-new-user), +and [refresh-tokens](account.md#request-a-new-refresh-token). + @@ -469,6 +473,8 @@ fusionHost = sdk.contextManager.get_fusion_host() ## Set fusion auth token +It is set automatically by [fusion login](fusion.md#login). + @@ -564,7 +570,8 @@ token = sdk.contextManager.get_fusion_auth_token() ## Set user ID Sets the user identifier used by the secure [lock operations](lock-operations.md). It is usually set for you by -[set operation context](#set-operation-context). +[set operation context](#set-operation-context), [register ephemeral key](account.md#register-ephemeral-key) +and [verify ephemeral key](account.md#verify-ephemeral-key-registration). @@ -764,8 +771,8 @@ email = sdk.contextManager.get_user_email() ## Set certificate chain Sets the certificate chain used to sign the secure [lock operations](lock-operations.md). It is usually set for -you by [set operation context](#set-operation-context) or by -[register ephemeral key](account.md#register-ephemeral-key). +you by [set operation context](#set-operation-context), [register ephemeral key](account.md#register-ephemeral-key) +and [verify ephemeral key](account.md#verify-ephemeral-key-registration). :::info Only the **first** certificate of the chain is inspected by [is certificate chain invalid or expired](#is-certificate-chain-invalid-or-expired). @@ -922,14 +929,13 @@ result = sdk.contextManager.is_certificate_chain_invalid_or_expired() ## Set key pair Sets the key pair used to sign the secure [lock operations](lock-operations.md). It is usually set for you by -[set operation context](#set-operation-context), [assisted login](helper.md#assisted-login) or -[assisted register](helper.md#assisted-register). +[set operation context](#set-operation-context), [register ephemeral key](account.md#register-ephemeral-key) +and [verify ephemeral key](account.md#verify-ephemeral-key-registration). :::info -* Setting a new key pair does **not** mark it as verified. Use [set key pair verified](#set-key-pair-verified), - or register it through [register ephemeral key](account.md#register-ephemeral-key). -* Keys generated on any platform are accepted — see [crypto](crypto.md) for the supported encodings. - ::: +Setting a new key pair does **not** mark it as verified. Use [set key pair verified](#set-key-pair-verified), +or register it through [register ephemeral key](account.md#register-ephemeral-key) plus and [verify ephemeral key](account.md#verify-ephemeral-key-registration). +::: @@ -1038,7 +1044,8 @@ Marks a public key as verified, meaning it has successfully completed [two-factor verification](account.md#verify-ephemeral-key-registration). Pass **null** to clear the verification. :::info -[Is key pair verified](#is-key-pair-verified) compares the value stored here against the current public key, so setting a key pair that does not match clears the verified state in practice. +[Is key pair verified](#is-key-pair-verified) compares the value stored here against the current public key, +so setting a key pair that does not match clears the verified state in practice. ::: From 627ab19e8a925596ab450f9ae8ae0846778d2506 Mon Sep 17 00:00:00 2001 From: Bernat Date: Fri, 4 Sep 2026 19:46:35 +0200 Subject: [PATCH 4/4] wip --- docs/kotlin-multiplatform-sdk/crypto.md | 16 ++++++++++++++++ docs/kotlin-multiplatform-sdk/initialize.md | 15 ++++++++------- 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/kotlin-multiplatform-sdk/crypto.md b/docs/kotlin-multiplatform-sdk/crypto.md index 74d740e0..93753788 100644 --- a/docs/kotlin-multiplatform-sdk/crypto.md +++ b/docs/kotlin-multiplatform-sdk/crypto.md @@ -1,7 +1,23 @@ # Crypto +The crypto manager exposes the cryptographic primitives the SDK uses for +[ephemeral key registration](account.md#register-ephemeral-key) and for signing +[lock operations](lock-operations.md). All key pairs are **Ed25519**. + +Each platform uses its own crypto provider and its own native key encoding: + +| Platform | Provider | +|:---------------------:|:-------------------:| +| JVM | Java Security API | +| Android | Bouncy Castle | +| iOS / macOS / watchOS | Apple CryptoKit | +| JS / Broswer / Node | Libsodium | +| C# / Python | Libsodium | + ## Generate a key pair +Generates a brand-new Ed25519 key pair. The key pair is **not** stored automatically. + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/docs/kotlin-multiplatform-sdk/initialize.md b/docs/kotlin-multiplatform-sdk/initialize.md index d5d3434f..6caba247 100644 --- a/docs/kotlin-multiplatform-sdk/initialize.md +++ b/docs/kotlin-multiplatform-sdk/initialize.md @@ -23,13 +23,14 @@ If you initialize the SDK without a cloud auth token, you will need to either pr By default, the SDK stores the context information on its own, as shown in the following table: -| Platform | Storage | -|:---------------------:|:------------------------------:| -| Android | `EncryptedSharedPreferences` | -| JVM | `Memory` | -| iOS / macOS / watchOS | `Keychain` | -| JS / Node | `LocalStorage` | -| C# / Python | `Memory` | +| Platform | Storage | +|:---------------------:|:----------------------------:| +| Android | `EncryptedSharedPreferences` | +| JVM | `Memory` | +| iOS / macOS / watchOS | `Keychain` | +| JS Browser | `LocalStorage` | +| JS Node | `Memory` | +| C# / Python | `Memory` | :::info To override the default secure storage, you must implement the `SecureStorage` interface and pass the class through the `setSecureStorageOverride` function from `SdkConfig` builder.