> For AI agents: the documentation index is at https://sdk.nimbusprivacy.xyz/llms.txt, and every page is available as Markdown at its URL with .md appended. # Sessions (/reference/sessions) A session is the user's private account, opened on this device. [Sessions](https://sdk.nimbusprivacy.xyz/helpers/sessions) walks through opening one, switching wallets and signing out. ## openNimbusSession Use it after the wallet connects, to unlock the user's private account. ```ts function openNimbusSession( sdk: NimbusSdk, args: { readonly connectedWallet: WalletStandardSigner }, options?: OpenNimbusSessionOptions, ): Promise; ``` Opens a session for the connected wallet on the SDK's cluster: reads the signature secret from the signature secret store or asks the wallet to sign the unlock message once, derives the seed, the platform wallet, the identity and its keys, reads its registration standing, and opens its note store in IndexedDB. The wallet signs only when the store holds no secret for this wallet, cluster and chain; what its signature yields is written to the store before anything else, so a reload opens without asking again. The same wallet always opens the same identity on the same cluster, on any device. A secret the store returns is trusted: a store an attacker can write to can open another identity under this wallet's name. The note store is named by `buildNoteStoreBackendName`, one database per deployment and identity. A registered identity's store keeps the birthday it has, or starts at slot 0 on a device that has none, so every note is read; an unregistered identity's store is left without one, for registering to set. Opening reaches only the context API, which takes no gateway token, so a session opens whether or not it has one; the token is first sent when a flow reaches a gateway service. **Parameters** | Parameter | Type | Description | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `sdk` | `NimbusSdk` | The loaded SDK. | | `args` | ``{ /** * The connected wallet's signer, as {@link openWalletConnection} builds it: its account must * offer `solana:signMessage` on the cluster's chain. */ readonly connectedWallet: WalletStandardSigner; }`` | The connected wallet. | | `options?` | `OpenNimbusSessionOptions` | The signature secret store, the platform wallet's account index and the gateway token. | **Returns** `Promise` `opened` with the session, or `declined` when the user refused to sign. **Throws** [`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"wallet-unsupported"` when the wallet lacks `solana:signMessage` or the cluster's chain, its account's address is not its public key's, or it fails while signing, signs other bytes than the unlock message, or answers a signature that does not verify; `"misconfigured"` when `accountIndex` is not an integer in `[0, 2^31)` or `gatewayToken` is a string that is not an RFC 6750 bearer token; `"unsupported-browser"` when the browser refuses the signature secret store's storage or the note store's database; `"unreadable"` when the note store holds another deployment's rows or a newer schema, or the context API answers what cannot be read; `"service-unavailable"` when the context API cannot be reached or refuses. **Example** ```ts import { openNimbusSession } from "@umbra/nimbus-solana-web"; import type { NimbusSdk, WalletStandardSigner } from "@umbra/nimbus-solana-web"; declare const sdk: NimbusSdk; declare const connectedWallet: WalletStandardSigner; declare const fetchGatewayToken: (wallet: string) => Promise; const opened = await openNimbusSession( sdk, { connectedWallet }, { gatewayToken: async () => fetchGatewayToken(connectedWallet.account.address) }, ); if (opened.kind === "opened" && opened.session.registration.kind === "unregistered") { // register before the first deposit } ``` Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/session.ts`. ## closeNimbusSession Use it when the user signs out, switches wallets, or the wallet disconnects. ```ts function closeNimbusSession(session: NimbusSession): void; ``` Closes a session: zeroes its wallet seed and the keys a sync holds, drops a held gateway token, and closes its note store. The signature secret store is left as it is, so the next open needs no signature; call its `wipeSignatureSecret` as well to sign the user out. Every later use of the session fails. Closing twice does nothing more. **Parameters** | Parameter | Type | Description | | --------- | --------------- | --------------------- | | `session` | `NimbusSession` | The session to close. | **Example** ```ts import { closeNimbusSession } from "@umbra/nimbus-solana-web"; import type { NimbusSession } from "@umbra/nimbus-solana-web"; declare const session: NimbusSession; closeNimbusSession(session); ``` Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/session.ts`. ## createMemorySignatureSecretStore Use it when no secret may touch the browser's storage, and a signature after every reload is acceptable. ```ts function createMemorySignatureSecretStore(): SignatureSecretStore; ``` Creates a signature secret store that keeps secrets in this page's memory only, so the wallet signs again after every reload. Nothing reaches Web Storage. A wiped secret's bytes are zeroed. **Returns** `SignatureSecretStore` The store's read, write and wipe functions. **Example** ```ts import { createMemorySignatureSecretStore } from "@umbra/nimbus-solana-web"; const signatureSecretStore = createMemorySignatureSecretStore(); ``` Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/signature-secret-store.ts`. ## createTabSignatureSecretStore Use it for the default: one signature per tab, kept until the tab closes. ```ts function createTabSignatureSecretStore( options?: SignatureSecretStoreOptions, ): SignatureSecretStore; ``` Creates the default signature secret store, over the browser's `sessionStorage`: the secret lasts as long as the tab, survives a reload, and is gone when the tab closes. The secret is kept base64-encoded and unencrypted; any script running on the page's origin can read it while the tab is open. The store touches `sessionStorage` only when one of its functions is called. **Parameters** | Parameter | Type | Description | | ---------- | ----------------------------- | ----------------------------------------- | | `options?` | `SignatureSecretStoreOptions` | The prefix every entry's key starts with. | **Returns** `SignatureSecretStore` The store's read, write and wipe functions. **Throws** Nothing itself; its functions throw [`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"unsupported-browser"` when the browser has no `sessionStorage`, refuses access to it or refuses a write, as a full quota does. **Example** ```ts import { createTabSignatureSecretStore, openNimbusSession, } from "@umbra/nimbus-solana-web"; import type { NimbusSdk, WalletStandardSigner } from "@umbra/nimbus-solana-web"; declare const sdk: NimbusSdk; declare const connectedWallet: WalletStandardSigner; const opened = await openNimbusSession( sdk, { connectedWallet }, { signatureSecretStore: createTabSignatureSecretStore({ keyPrefix: "my-app/" }) }, ); ``` Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/signature-secret-store.ts`. ## createPersistentSignatureSecretStore Use it when users should sign once per device, and you accept the secret staying in `localStorage`. ```ts function createPersistentSignatureSecretStore( options?: SignatureSecretStoreOptions, ): SignatureSecretStore; ``` Creates a signature secret store over the browser's `localStorage`: the secret survives closing the browser, so the wallet signs once per device until the secret is wiped. The secret is kept base64-encoded and unencrypted, indefinitely: any script that ever runs on the page's origin can read it, and anyone with access to the browser profile can copy it from disk. The store touches `localStorage` only when one of its functions is called. **Parameters** | Parameter | Type | Description | | ---------- | ----------------------------- | ----------------------------------------- | | `options?` | `SignatureSecretStoreOptions` | The prefix every entry's key starts with. | **Returns** `SignatureSecretStore` The store's read, write and wipe functions. **Throws** Nothing itself; its functions throw [`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"unsupported-browser"` when the browser has no `localStorage`, refuses access to it or refuses a write, as a full quota does. **Example** ```ts import { createPersistentSignatureSecretStore } from "@umbra/nimbus-solana-web"; const signatureSecretStore = createPersistentSignatureSecretStore(); ``` Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/signature-secret-store.ts`. Last updated 21 October 2026