@parity/product-sdk-auth

Exports

Classes

Functions

Interfaces

Type Aliases

Variables

Re-exports

Convenience re-exports from leaf packages. Click through for the canonical documentation.

Classes

class SignerNotAvailableError

Extends: Error

Constructors

constructor

new SignerNotAvailableError(): SignerNotAvailableError

Functions

createAuthClient()

Build an auth client bound to a product’s AuthConfig. All adapter creation, address derivation, and session-storage scoping read from config, so the same code serves any product.

createAuthClient(config: AuthConfig): AuthClient

parseDevAccountName()

Parse a well-known dev-account SURI (//Alice, //Bob, …).

Requires the // hard-derivation prefix and an exact-case name, matching Substrate SURI semantics (and createDevSigner, which derives //${name}). A bare Alice or a different case is NOT a dev SURI — it falls through to the mnemonic path in resolveSigner, where it fails as an invalid mnemonic.

parseDevAccountName(suri: string): DevAccountName | null

requestResourceAllocation()

Send a host_request_resource_allocation request over the user’s active session. The host (mobile wallet) prompts the user to approve and returns one outcome per requested resource in order.

Throws on transport-level failures (Statement Store unreachable, encryption error, etc.). Per-resource refusals are reported as Rejected/NotAvailable outcomes — callers inspect the array to decide whether to proceed.

requestResourceAllocation(session: UserSession, productId: string, resources: { tag: "StatementStoreAllowance"; value: undefined } | { tag: "SmartContractAllowance"; value: number } | { tag: "AutoSigning"; value: undefined } | { tag: "BulletInAllowance"; value: undefined }[] = DEFAULT_RESOURCES, onExisting: "Ignore" | "Increase" = "Ignore"): Promise<{ tag: "Rejected"; value: undefined } | { tag: "Allocated"; value: { tag: "StatementStoreAllowance"; value: { slotAccountKey: Uint8Array<ArrayBufferLike> } } | { tag: "SmartContractAllowance"; value: undefined } | { tag: "AutoSigning"; value: { productDerivationSecret: string; productRootPrivateKey: Uint8Array<ArrayBufferLike> } } | { tag: "BulletInAllowance"; value: { slotAccountKey: Uint8Array<ArrayBufferLike> } } } | { tag: "NotAvailable"; value: undefined }[]>

resolveSigner()

Resolve a PolkadotSigner.

1. --suri flag → dev signer (dev name like //Alice, OR a BIP-39 mnemonic with optional //<path> derivation suffix)
2. Persisted QR session → session signer (via authClient.getSessionSigner)
3. Neither → SignerNotAvailableError

resolveSigner(authClient: AuthClient, options?: SignerOptions): Promise<ResolvedSigner>

summarizeOutcomes()

Bucket allocation outcomes by tag. Order-sensitive: outcomes[i] maps to resources[i]. Outcomes without a matching resource are silently dropped.

summarizeOutcomes(outcomes: { tag: "Rejected"; value: undefined } | { tag: "Allocated"; value: { tag: "StatementStoreAllowance"; value: { slotAccountKey: Uint8Array<ArrayBufferLike> } } | { tag: "SmartContractAllowance"; value: undefined } | { tag: "AutoSigning"; value: { productDerivationSecret: string; productRootPrivateKey: Uint8Array<ArrayBufferLike> } } | { tag: "BulletInAllowance"; value: { slotAccountKey: Uint8Array<ArrayBufferLike> } } } | { tag: "NotAvailable"; value: undefined }[], resources: { tag: "StatementStoreAllowance"; value: undefined } | { tag: "SmartContractAllowance"; value: number } | { tag: "AutoSigning"; value: undefined } | { tag: "BulletInAllowance"; value: undefined }[]): AllocationSummary

Interfaces

interface AllocationSummary

Properties

granted

rejected

unavailable

interface AuthClient

The product-bound auth surface returned by createAuthClient.

Methods

clearLocalAppStorage

clearLocalAppStorage(dir?: string): Promise<void>

connect

connect(): Promise<ConnectResult>

findSession

findSession(): Promise<LogoutHandle | null>

getSessionSigner

getSessionSigner(): Promise<SessionHandle | null>

requestAllocation

requestAllocation(session: UserSession, resources?: { tag: "StatementStoreAllowance"; value: undefined } | { tag: "SmartContractAllowance"; value: number } | { tag: "AutoSigning"; value: undefined } | { tag: "BulletInAllowance"; value: undefined }[], onExisting?: "Ignore" | "Increase"): Promise<{ tag: "Rejected"; value: undefined } | { tag: "Allocated"; value: { tag: "StatementStoreAllowance"; value: { slotAccountKey: Uint8Array<ArrayBufferLike> } } | { tag: "SmartContractAllowance"; value: undefined } | { tag: "AutoSigning"; value: { productDerivationSecret: string; productRootPrivateKey: Uint8Array<ArrayBufferLike> } } | { tag: "BulletInAllowance"; value: { slotAccountKey: Uint8Array<ArrayBufferLike> } } } | { tag: "NotAvailable"; value: undefined }[]>

waitForLogin

waitForLogin(handle: LoginHandle, onStatus: (status: LoginStatus) => void): Promise<string | null>

waitForLogout

waitForLogout(handle: LogoutHandle, onStatus: (status: LogoutStatus) => void): Promise<void>

interface AuthConfig

Per-product configuration injected into createAuthClient. Lifting the sign-in glue out of playground-cli (issue #411) means the env-specific constants playground hard-coded in its config.ts (DAPP_ID, product id, People-chain endpoints) become consumer-supplied so the same package serves playground and dot (and future products) unchanged.

Properties

dappId

The dApp identity string. Scopes the on-disk session namespace (~/.polkadot-apps/${dappId}_*) and the SSO pairing — each product gets its own, independently-revocable session.

derivationIndex

Derivation index of the product account (0 = default).

peopleEndpoints

People-parachain RPC endpoints the terminal adapter connects to.

productId

Product id used to derive the product account (/product/{productId}/{index}).

interface LoginHandle

Properties

adapter

authPromise

The authenticate() promise — already running since connect().

interface LogoutHandle

Properties

adapter

address

session

interface ResolvedSigner

Properties

address

addresses

Root / product / H160 triple — present for QR/mobile sessions only.

signer

source

userSession

Present for QR/mobile sessions; absent for local dev/SURI signers.

Methods

destroy

Tear down session adapter. Call in a finally block. No-op for dev signers.

destroy(): void

interface SessionAddresses

The three addresses we surface from a paired session.

• rootAddress — SS58 of session.rootAccountId, the rootUserAccountId the mobile app sent over the SSO handshake (bare-mnemonic sr25519 root on current mobile builds). Keyed by Resources.Consumers on the People parachain, so it’s the right input for lookupUsername.
• productAddress — SS58 of the product account derived via product/{productId}/{index} from rootAccountId. This is what actually signs on-chain transactions from the CLI.
• productH160 — the same product pubkey as a 20-byte EVM address (Revive / contracts view). Derived from the SAME pubkey as productAddress.

Properties

productAddress

productH160

rootAddress

interface SessionHandle

A session signer bundle — the signer plus an explicit destroy() that tears down the long-lived adapter the signer depends on. Callers MUST invoke destroy() once done — the WebSocket keeps the event loop alive.

Properties

address

addresses

signer

userSession

Methods

destroy

destroy(): void

interface SignerOptions

Properties

suri

Secret URI like “//Alice”. Takes priority over session.

Type Aliases

type AllocationOutcome

Outcome of one allocation. Re-exported from terminal’s wire-derived type under the name auth consumers already use. We don’t read the inner Allocated payload (allowance slot keys, derivation secrets) — the host stores them and uses them transparently on subsequent calls. We just need the tag to know whether the allocation succeeded.

type AllocationOutcome = ApAllocationOutcome

type ConnectResult

type ConnectResult = { address: string; addresses: SessionAddresses; kind: "existing" } | { kind: "qr"; login: LoginHandle; qrCode: string }

type LoginStatus

type LoginStatus = { step: "waiting" } | { step: "paired" } | { stage: string; step: "pending" } | { address: string; addresses: SessionAddresses; step: "success" } | { message: string; step: "error" }

type LogoutStatus

type LogoutStatus = { address: string; step: "disconnecting" } | { address: string; step: "success" } | { address: string; reason: string; step: "partial" } | { message: string; step: "error" }

type ResourceTag

Tag-only view, handy for downstream code that doesn’t care about payloads.

type ResourceTag = AllocatableResource["tag"]

type SignerSource

type SignerSource = "dev" | "session"

Variables

DEFAULT_RESOURCES

Default mobile-granted resource set for a CLI product account: write access to the statement store + Bulletin, plus PGAS sponsoring for the default (index 0) product account.

let DEFAULT_RESOURCES: AllocatableResource[] = ...