@raytio/core 11.5.0 → 11.6.0

package/README.md

@@ -16,8 +16,39 @@ If you wish to use `@raytio/core` directly, an example of configuring polyfills
 
 ## Table of contents
 
+### Classes
+
+- [LocalSecretRequiredError](classes/LocalSecretRequiredError.md)
+- [PGPKeyExportError](classes/PGPKeyExportError.md)
+- [PGPKeyImportError](classes/PGPKeyImportError.md)
+- [UnknownKdfAlgorithmError](classes/UnknownKdfAlgorithmError.md)
+
+### Interfaces
+
+- [Argon2idConfig](interfaces/Argon2idConfig.md)
+- [EncryptedPrivateKey](interfaces/EncryptedPrivateKey.md)
+- [ExportPGPKeyOptions](interfaces/ExportPGPKeyOptions.md)
+- [ExportedPGPKey](interfaces/ExportedPGPKey.md)
+- [FormattedLocalSecret](interfaces/FormattedLocalSecret.md)
+- [KdfResult](interfaces/KdfResult.md)
+- [KeyValidationResult](interfaces/KeyValidationResult.md)
+- [LocalSecretStorage](interfaces/LocalSecretStorage.md)
+- [PGPKeyPair](interfaces/PGPKeyPair.md)
+- [PGPKeyStorage](interfaces/PGPKeyStorage.md)
+- [PGPPublicKeyProperties](interfaces/PGPPublicKeyProperties.md)
+- [ParsedPGPKey](interfaces/ParsedPGPKey.md)
+- [Pbkdf2Config](interfaces/Pbkdf2Config.md)
+- [StoredLocalSecret](interfaces/StoredLocalSecret.md)
+- [StoredPGPPrivateKey](interfaces/StoredPGPPrivateKey.md)
+
 ### Type Aliases
 
+- [BadgeDefinition](#badgedefinition)
+- [BadgeResult](#badgeresult)
+- [BadgeState](#badgestate)
+- [BadgeStateDisplay](#badgestatedisplay)
+- [KdfConfig](#kdfconfig)
+- [PGPKeyAlgorithm](#pgpkeyalgorithm)
 - [SafeHarbourObj](#safeharbourobj)
 - [SafeHarbourResult](#safeharbourresult)
 - [ServerAA](#serveraa)
@@ -26,43 +57,176 @@ If you wish to use `@raytio/core` directly, an example of configuring polyfills
 
 ### Variables
 
+- [AES\_GCM\_IV\_SIZE](#aes_gcm_iv_size)
+- [DEFAULT\_ARGON2ID\_PARAMS](#default_argon2id_params)
+- [KEY\_FINGERPRINT\_LENGTH](#key_fingerprint_length)
+- [LOCAL\_SECRET\_CHARSET](#local_secret_charset)
+- [LOCAL\_SECRET\_DB\_CONFIG](#local_secret_db_config)
+- [LOCAL\_SECRET\_GROUP\_SIZE](#local_secret_group_size)
+- [LOCAL\_SECRET\_SIZE](#local_secret_size)
+- [PGP\_KEY\_DB\_CONFIG](#pgp_key_db_config)
 - [TAG\_DENYLIST](#tag_denylist)
 
 ### Functions
 
+- [base64ToUint8Array](#base64touint8array)
+- [bytesToPem](#bytestopem)
 - [calcSafeHarbourScore](#calcsafeharbourscore)
 - [calculateScore](#calculatescore)
+- [canonicalJsonify](#canonicaljsonify)
 - [checkJsonSignature](#checkjsonsignature)
+- [computeKeyFingerprint](#computekeyfingerprint)
+- [constantTimeEqual](#constanttimeequal)
 - [convertInstanceToRuleInput](#convertinstancetoruleinput)
 - [convertServerRelationship](#convertserverrelationship)
 - [createAA](#createaa)
+- [createArgon2idConfig](#createargon2idconfig)
 - [createHashedNId](#createhashednid)
+- [createIndexedDBPGPKeyStorage](#createindexeddbpgpkeystorage)
+- [createIndexedDBStorage](#createindexeddbstorage)
+- [decryptPrivateKey](#decryptprivatekey)
 - [decryptSharedData](#decryptshareddata)
+- [deleteLocalSecret](#deletelocalsecret)
+- [deletePGPPrivateKey](#deletepgpprivatekey)
+- [deriveArgon2id](#deriveargon2id)
+- [deriveKey](#derivekey)
+- [derivePbkdf2](#derivepbkdf2)
+- [deriveTwoSecretKdf](#derivetwosecretkdf)
+- [encryptPrivateKey](#encryptprivatekey)
+- [evaluateBadge](#evaluatebadge)
 - [evaluateRule](#evaluaterule)
+- [evaluateUserBadges](#evaluateuserbadges)
 - [expandSchema](#expandschema)
+- [exportPGPKeyToArmored](#exportpgpkeytoarmored)
+- [extractPemType](#extractpemtype)
 - [findSchemaLabel](#findschemalabel)
 - [findSuitableLocale](#findsuitablelocale)
+- [formatFingerprint](#formatfingerprint)
+- [formatLocalSecret](#formatlocalsecret)
 - [fromCognitoAttributes](#fromcognitoattributes)
+- [generateDeviceId](#generatedeviceid)
+- [generateLocalSecret](#generatelocalsecret)
+- [generatePGPKeyPair](#generatepgpkeypair)
+- [generateRandomBytes](#generaterandombytes)
+- [generateSalt](#generatesalt)
 - [getAADecryptor](#getaadecryptor)
 - [getAAPublicKey](#getaapublickey)
+- [getKdfVersion](#getkdfversion)
+- [getLocalSecret](#getlocalsecret)
+- [getLocalSecretRecord](#getlocalsecretrecord)
 - [getMissingDataForInstance](#getmissingdataforinstance)
 - [getNidFromUrn](#getnidfromurn)
+- [getOrCreateDeviceId](#getorcreatedeviceid)
 - [getOwnRealVerifications](#getownrealverifications)
+- [getPGPPrivateKey](#getpgpprivatekey)
 - [getPOVerification](#getpoverification)
 - [getSomeoneElsesRealVerifications](#getsomeoneelsesrealverifications)
+- [hasLocalSecret](#haslocalsecret)
+- [hasPGPPrivateKey](#haspgpprivatekey)
 - [hashPassword](#hashpassword)
+- [importPrivateKey](#importprivatekey)
+- [importPublicKey](#importpublickey)
+- [isArgon2Available](#isargon2available)
+- [isArgon2idConfig](#isargon2idconfig)
+- [isArmoredPGPKey](#isarmoredpgpkey)
 - [isConditionMet](#isconditionmet)
 - [isEncrypted](#isencrypted)
 - [isEncryptedFile](#isencryptedfile)
+- [isPbkdf2Config](#ispbkdf2config)
+- [isPemFormat](#ispemformat)
 - [isScoreConfigValid](#isscoreconfigvalid)
 - [isScoreResultValid](#isscoreresultvalid)
+- [isValidFormattedLocalSecret](#isvalidformattedlocalsecret)
+- [isValidLocalSecret](#isvalidlocalsecret)
+- [maskLocalSecret](#masklocalsecret)
+- [normalizePassword](#normalizepassword)
+- [parseArmoredPGPKey](#parsearmoredpgpkey)
+- [parseLocalSecret](#parselocalsecret)
+- [pemToBytes](#pemtobytes)
 - [repairDate](#repairdate)
+- [requiresLocalSecret](#requireslocalsecret)
+- [setArgon2Module](#setargon2module)
+- [signData](#signdata)
+- [signText](#signtext)
 - [someEncrypted](#someencrypted)
 - [sortSchemaProperties](#sortschemaproperties)
+- [storeLocalSecret](#storelocalsecret)
+- [storePGPPrivateKey](#storepgpprivatekey)
 - [toCognitoAttributes](#tocognitoattributes)
+- [uint8ArrayToBase64](#uint8arraytobase64)
+- [validateImportedKey](#validateimportedkey)
+- [verifySignature](#verifysignature)
+- [verifyTextSignature](#verifytextsignature)
+- [xorBytes](#xorbytes)
 
 ## Type Aliases
 
+### BadgeDefinition
+
+Ƭ **BadgeDefinition**: `CommonFields`<`BId`\> & { `display`: { `states`: `Record`<[`BadgeState`](#badgestate), [`BadgeStateDisplay`](#badgestatedisplay)\>  } ; `name`: `string` ; `ruleset`: `ScoreConfig`  }
+
+Badge definition as stored in dsm_schema_badges
+
+___
+
+### BadgeResult
+
+Ƭ **BadgeResult**: `Object`
+
+Result of evaluating a badge for a user
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `badgeId` | `string` |
+| `badgeName` | `string` |
+| `diagnostics` | `ScoreResult`[``"diagnostics"``] |
+| `display` | [`BadgeStateDisplay`](#badgestatedisplay) |
+| `state` | [`BadgeState`](#badgestate) |
+
+___
+
+### BadgeState
+
+Ƭ **BadgeState**: ``"not_met"`` \| ``"partially_met"`` \| ``"fully_met"``
+
+Standard badge states - consistent across all badges
+
+___
+
+### BadgeStateDisplay
+
+Ƭ **BadgeStateDisplay**: `Object`
+
+Display configuration for a single badge state
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `color` | `string` |
+| `icon` | `string` |
+| `label` | `string` |
+
+___
+
+### KdfConfig
+
+Ƭ **KdfConfig**: [`Pbkdf2Config`](interfaces/Pbkdf2Config.md) \| [`Argon2idConfig`](interfaces/Argon2idConfig.md)
+
+Union type for all KDF configurations
+
+___
+
+### PGPKeyAlgorithm
+
+Ƭ **PGPKeyAlgorithm**: ``"RSA-4096"`` \| ``"RSA-2048"``
+
+Supported PGP key algorithms
+
+___
+
 ### SafeHarbourObj
 
 Ƭ **SafeHarbourObj**: `Partial`<`Record`<`SafeHarbourCode`, `string`[]\>\>
@@ -94,7 +258,7 @@ ___
 
 ### ServerRelationship
 
-Ƭ **ServerRelationship**: `Omit`<`Relationship`, ``"p_id"`` \| ``"start"`` \| ``"end"``\> & { `from_id`: `NId` ; `id`: `PId`  } & { `to_id`: `NId`  } \| { `to_i_id`: `IId`  }
+Ƭ **ServerRelationship**: `Omit`<`Relationship`, ``"p_id"`` \| ``"start"`` \| ``"end"``\> & { `from_id`: `NId` ; `id`: `PId` ; `to_i_id?`: `IId` \| ``null`` ; `to_id?`: `NId` \| ``null``  }
 
 This type represents the relationship format returned by the Postgres API
 
@@ -114,12 +278,144 @@ ___
 
 ## Variables
 
+### AES\_GCM\_IV\_SIZE
+
+• `Const` **AES\_GCM\_IV\_SIZE**: ``12``
+
+AES-GCM IV size in bytes
+
+___
+
+### DEFAULT\_ARGON2ID\_PARAMS
+
+• `Const` **DEFAULT\_ARGON2ID\_PARAMS**: `Object`
+
+Default Argon2id parameters (matching Bitwarden recommendations)
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `iterations` | ``3`` |
+| `memory` | ``65536`` |
+| `parallelism` | ``4`` |
+
+___
+
+### KEY\_FINGERPRINT\_LENGTH
+
+• `Const` **KEY\_FINGERPRINT\_LENGTH**: ``40``
+
+Key fingerprint length (hex characters)
+
+___
+
+### LOCAL\_SECRET\_CHARSET
+
+• `Const` **LOCAL\_SECRET\_CHARSET**: ``"23456789ABCDEFGHJKLMNPQRSTUVWXYZ"``
+
+Character set for LocalSecret display format
+
+Excludes ambiguous characters: 0, 1, I, O
+
+___
+
+### LOCAL\_SECRET\_DB\_CONFIG
+
+• `Const` **LOCAL\_SECRET\_DB\_CONFIG**: `Object`
+
+IndexedDB configuration for LocalSecret storage
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `name` | ``"raytio-secrets"`` |
+| `storeName` | ``"local-secrets"`` |
+| `version` | ``1`` |
+
+___
+
+### LOCAL\_SECRET\_GROUP\_SIZE
+
+• `Const` **LOCAL\_SECRET\_GROUP\_SIZE**: ``6``
+
+Number of characters per group in formatted display
+
+___
+
+### LOCAL\_SECRET\_SIZE
+
+• `Const` **LOCAL\_SECRET\_SIZE**: ``32``
+
+LocalSecret size in bytes (256 bits)
+
+___
+
+### PGP\_KEY\_DB\_CONFIG
+
+• `Const` **PGP\_KEY\_DB\_CONFIG**: `Object`
+
+IndexedDB configuration for PGP key storage
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `name` | ``"raytio-pgp-keys"`` |
+| `storeName` | ``"private-keys"`` |
+| `version` | ``1`` |
+
+___
+
 ### TAG\_DENYLIST
 
 • `Const` **TAG\_DENYLIST**: `SchemaTag`[]
 
 ## Functions
 
+### base64ToUint8Array
+
+▸ **base64ToUint8Array**(`base64`): `Uint8Array`
+
+Convert a base64 string to Uint8Array
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `base64` | `string` |
+
+#### Returns
+
+`Uint8Array`
+
+___
+
+### bytesToPem
+
+▸ **bytesToPem**(`bytes`, `type`): `string`
+
+Convert raw bytes to PEM format
+
+Encodes the bytes as base64 and wraps with PEM headers.
+Base64 content is wrapped at 64 characters per line per RFC 7468.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `bytes` | `Uint8Array` | Raw bytes to encode |
+| `type` | `string` | PEM type (e.g., "PUBLIC KEY", "PRIVATE KEY") |
+
+#### Returns
+
+`string`
+
+PEM-formatted string
+
+___
+
 ### calcSafeHarbourScore
 
 ▸ **calcSafeHarbourScore**(`data`): `Promise`<[`SafeHarbourResult`](#safeharbourresult)\>
@@ -165,6 +461,27 @@ Might throw an error.
 
 ___
 
+### canonicalJsonify
+
+▸ **canonicalJsonify**(`object`): `string`
+
+Creates a canonical JSON string representation of an object.
+
+Spec compliant, and matches
+https://gitlab.com/raytio/mono/-/blob/devo/common/signing/signing/canonical_json.py
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `object` | `unknown` |
+
+#### Returns
+
+`string`
+
+___
+
 ### checkJsonSignature
 
 ▸ **checkJsonSignature**(`data`, `signature`, `keyId`): `Promise`<`boolean`\>
@@ -187,6 +504,49 @@ or `getSomeoneElsesRealVerifications` instead.
 
 ___
 
+### computeKeyFingerprint
+
+▸ **computeKeyFingerprint**(`publicKeyBytes`): `Promise`<`string`\>
+
+Compute SHA-256 fingerprint of public key bytes
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `publicKeyBytes` | `Uint8Array` | Raw public key bytes (SPKI format) |
+
+#### Returns
+
+`Promise`<`string`\>
+
+First 40 hex characters of SHA-256 hash
+
+___
+
+### constantTimeEqual
+
+▸ **constantTimeEqual**(`a`, `b`): `boolean`
+
+Constant-time comparison of two byte arrays
+
+Prevents timing attacks when comparing secrets.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `a` | `Uint8Array` | First byte array |
+| `b` | `Uint8Array` | Second byte array |
+
+#### Returns
+
+`boolean`
+
+true if arrays are equal
+
+___
+
 ### convertInstanceToRuleInput
 
 ▸ **convertInstanceToRuleInput**(`POs`, `realVers`, `getSchema`): `Promise`<`RuleData`\>
@@ -253,6 +613,27 @@ as well as the `userDoc` data which is stored in the user's cognito attributes.
 
 ___
 
+### createArgon2idConfig
+
+▸ **createArgon2idConfig**(`salt`, `params?`): [`Argon2idConfig`](interfaces/Argon2idConfig.md)
+
+Create a new Argon2id configuration
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `salt` | `string` | Base64 encoded salt (optional, will generate if not provided) |
+| `params?` | `Partial`<`Pick`<[`Argon2idConfig`](interfaces/Argon2idConfig.md), ``"iterations"`` \| ``"memory"`` \| ``"parallelism"``\>\> | Optional custom parameters |
+
+#### Returns
+
+[`Argon2idConfig`](interfaces/Argon2idConfig.md)
+
+Argon2idConfig ready for storage
+
+___
+
 ### createHashedNId
 
 ▸ **createHashedNId**(`nId`, `aId`): `NId`
@@ -276,6 +657,56 @@ This was first introduced in #1048
 
 ___
 
+### createIndexedDBPGPKeyStorage
+
+▸ **createIndexedDBPGPKeyStorage**(): [`PGPKeyStorage`](interfaces/PGPKeyStorage.md)
+
+Create a PGPKeyStorage implementation using IndexedDB
+
+#### Returns
+
+[`PGPKeyStorage`](interfaces/PGPKeyStorage.md)
+
+___
+
+### createIndexedDBStorage
+
+▸ **createIndexedDBStorage**(): [`LocalSecretStorage`](interfaces/LocalSecretStorage.md)
+
+Create a LocalSecretStorage implementation using IndexedDB
+
+#### Returns
+
+[`LocalSecretStorage`](interfaces/LocalSecretStorage.md)
+
+___
+
+### decryptPrivateKey
+
+▸ **decryptPrivateKey**(`encryptedPrivateKey`, `iv`, `kek`): `Promise`<`Uint8Array`\>
+
+Decrypt private key bytes with the user's KEK using AES-GCM
+
+**`Throws`**
+
+Error if decryption fails (wrong key or tampered data)
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `encryptedPrivateKey` | `Uint8Array` | AES-GCM encrypted private key bytes |
+| `iv` | `Uint8Array` | 12-byte initialization vector used during encryption |
+| `kek` | `Uint8Array` | 32-byte Key Encryption Key from 2SKD |
+
+#### Returns
+
+`Promise`<`Uint8Array`\>
+
+Decrypted private key bytes (PKCS8 format)
+
+___
+
 ### decryptSharedData
 
 ▸ **decryptSharedData**(`«destructured»`): `Promise`<{ `applicationDecryptor`: `ApplicationDataEncryptorI` ; `instance`: `Instance`  }\>
@@ -306,76 +737,344 @@ a copy of `instanceData` with all properties decrypted.
 
 ___
 
-### evaluateRule
+### deleteLocalSecret
 
-▸ **evaluateRule**(`rule`, `data`): `Object`
+▸ **deleteLocalSecret**(`userId`): `Promise`<`void`\>
 
-evaluates an individual rule, normally you should use [calculateScore](#calculatescore)
+Delete a LocalSecret from IndexedDB
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `rule` | `ScoreRule` |
-| `data` | `RuleData` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `userId` | `string` | User's Cognito sub |
 
 #### Returns
 
-`Object`
-
-| Name | Type |
-| :------ | :------ |
-| `passed` | `boolean` |
-| `score` | `number` |
+`Promise`<`void`\>
 
 ___
 
-### expandSchema
+### deletePGPPrivateKey
 
-▸ **expandSchema**(`wrappedSchema`, `allUnexpandedSchemas`, `userLocales`): `Schema`
+▸ **deletePGPPrivateKey**(`userId`): `Promise`<`void`\>
 
-❣️ This is the main function to transform a schema from
-the JSON that the API returns, into a `Schema` object that's useful
-to the client.
+Delete an encrypted PGP private key from IndexedDB
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `wrappedSchema` | `WrappedSchema` |
-| `allUnexpandedSchemas` | `WrappedSchema`[] |
-| `userLocales` | readonly `string`[] |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `userId` | `string` | User's Cognito sub |
 
 #### Returns
 
-`Schema`
+`Promise`<`void`\>
 
 ___
 
-### findSchemaLabel
+### deriveArgon2id
 
-▸ **findSchemaLabel**(`labels`): `undefined` \| `SchemaName`
+▸ **deriveArgon2id**(`password`, `config`): `Promise`<[`KdfResult`](interfaces/KdfResult.md)\>
 
-Finds the label (on a profile object) which is the schema name
+Derive a key using Argon2id
+
+**`Throws`**
+
+Error if argon2 module is not available
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `labels` | `undefined` \| `string`[] |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `password` | `string` | User's password (will be normalized) |
+| `config` | [`Argon2idConfig`](interfaces/Argon2idConfig.md) | Argon2id configuration from Cognito attributes |
 
 #### Returns
 
-`undefined` \| `SchemaName`
+`Promise`<[`KdfResult`](interfaces/KdfResult.md)\>
+
+KdfResult containing the derived 32-byte key
 
 ___
 
-### findSuitableLocale
+### deriveKey
 
-▸ **findSuitableLocale**(`options`, `langs`): `undefined` \| `string`
+▸ **deriveKey**(`password`, `config`, `localSecret?`): `Promise`<[`KdfResult`](interfaces/KdfResult.md)\>
+
+Derive a key using the appropriate KDF based on configuration
+
+This is the main entry point for key derivation. It automatically
+selects the correct algorithm based on the config.
+
+**`Throws`**
+
+LocalSecretRequiredError if LocalSecret is required but not provided
+
+**`Throws`**
+
+UnknownKdfAlgorithmError if the algorithm is not recognized
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `password` | `string` | User's password |
+| `config` | [`KdfConfig`](#kdfconfig) | KDF configuration from Cognito attributes |
+| `localSecret?` | ``null`` \| `Uint8Array` | Optional LocalSecret for 2SKD (required for Argon2id with requires_local_secret) |
+
+#### Returns
+
+`Promise`<[`KdfResult`](interfaces/KdfResult.md)\>
+
+KdfResult containing the derived key
+
+___
+
+### derivePbkdf2
+
+▸ **derivePbkdf2**(`password`, `config`): `Promise`<[`KdfResult`](interfaces/KdfResult.md)\>
+
+Derive a key using PBKDF2
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `password` | `string` | User's password |
+| `config` | [`Pbkdf2Config`](interfaces/Pbkdf2Config.md) | PBKDF2 configuration from Cognito attributes |
+
+#### Returns
+
+`Promise`<[`KdfResult`](interfaces/KdfResult.md)\>
+
+KdfResult containing the derived 32-byte key
+
+___
+
+### deriveTwoSecretKdf
+
+▸ **deriveTwoSecretKdf**(`password`, `config`, `localSecret`): `Promise`<[`KdfResult`](interfaces/KdfResult.md)\>
+
+Derive KEK using Two-Secret Key Derivation
+
+Combines:
+1. Password → Argon2id → 32 bytes
+2. LocalSecret → 32 bytes
+3. XOR(1, 2) → KEK
+
+**`Throws`**
+
+LocalSecretRequiredError if localSecret is not provided but required
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `password` | `string` | User's password |
+| `config` | [`Argon2idConfig`](interfaces/Argon2idConfig.md) | Argon2id configuration |
+| `localSecret` | `undefined` \| ``null`` \| `Uint8Array` | Device-bound LocalSecret (32 bytes) |
+
+#### Returns
+
+`Promise`<[`KdfResult`](interfaces/KdfResult.md)\>
+
+KdfResult containing the derived KEK
+
+___
+
+### encryptPrivateKey
+
+▸ **encryptPrivateKey**(`privateKeyBytes`, `kek`): `Promise`<[`EncryptedPrivateKey`](interfaces/EncryptedPrivateKey.md)\>
+
+Encrypt private key bytes with the user's KEK using AES-GCM
+
+Uses a random 12-byte IV for each encryption operation.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `privateKeyBytes` | `Uint8Array` | Raw private key bytes (PKCS8 format) |
+| `kek` | `Uint8Array` | 32-byte Key Encryption Key from 2SKD |
+
+#### Returns
+
+`Promise`<[`EncryptedPrivateKey`](interfaces/EncryptedPrivateKey.md)\>
+
+Encrypted private key and IV
+
+___
+
+### evaluateBadge
+
+▸ **evaluateBadge**(`badge`, `ruleData`): `Promise`<[`BadgeResult`](#badgeresult)\>
+
+Evaluate a single badge definition against user data.
+Thin wrapper around calculateScore() -- threshold names map to badge states.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `badge` | [`BadgeDefinition`](#badgedefinition) |
+| `ruleData` | `RuleData` |
+
+#### Returns
+
+`Promise`<[`BadgeResult`](#badgeresult)\>
+
+___
+
+### evaluateRule
+
+▸ **evaluateRule**(`rule`, `data`): `Object`
+
+evaluates an individual rule, normally you should use [calculateScore](#calculatescore)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `rule` | `ScoreRule` |
+| `data` | `RuleData` |
+
+#### Returns
+
+`Object`
+
+| Name | Type |
+| :------ | :------ |
+| `passed` | `boolean` |
+| `score` | `number` |
+
+___
+
+### evaluateUserBadges
+
+▸ **evaluateUserBadges**(`badges`, `ruleData`): `Promise`<[`BadgeResult`](#badgeresult)[]\>
+
+Evaluate all active badge definitions against user data.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `badges` | [`BadgeDefinition`](#badgedefinition)[] |
+| `ruleData` | `RuleData` |
+
+#### Returns
+
+`Promise`<[`BadgeResult`](#badgeresult)[]\>
+
+___
+
+### expandSchema
+
+▸ **expandSchema**(`wrappedSchema`, `allUnexpandedSchemas`, `userLocales`, `fndI18nEntries?`): `Schema`
+
+This is the main function to transform a schema from
+the JSON that the API returns, into a `Schema` object that's useful
+to the client.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `wrappedSchema` | `WrappedSchema` |
+| `allUnexpandedSchemas` | `WrappedSchema`[] |
+| `userLocales` | readonly `string`[] |
+| `fndI18nEntries?` | `FndI18nEntry`[] |
+
+#### Returns
+
+`Schema`
+
+___
+
+### exportPGPKeyToArmored
+
+▸ **exportPGPKeyToArmored**(`privateKeyBytes`, `options?`): `Promise`<[`ExportedPGPKey`](interfaces/ExportedPGPKey.md)\>
+
+Export a PKCS8 private key to OpenPGP armored format
+
+This function converts existing PKCS8 RSA key material to OpenPGP format,
+preserving the original cryptographic material. The exported key can be
+used with GPG, GitHub, and other OpenPGP-compatible tools.
+
+**`Throws`**
+
+PGPKeyExportError if export fails
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `privateKeyBytes` | `Uint8Array` | PKCS8 encoded private key bytes |
+| `options` | [`ExportPGPKeyOptions`](interfaces/ExportPGPKeyOptions.md) | Export options (passphrase, userIds, date) |
+
+#### Returns
+
+`Promise`<[`ExportedPGPKey`](interfaces/ExportedPGPKey.md)\>
+
+Armored private and public keys with fingerprint
+
+___
+
+### extractPemType
+
+▸ **extractPemType**(`pem`): `string` \| ``null``
+
+Extract the type from a PEM-formatted string
+
+For example, extracts "PUBLIC KEY" from:
+-----BEGIN PUBLIC KEY-----
+...
+-----END PUBLIC KEY-----
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `pem` | `string` | PEM-formatted string |
+
+#### Returns
+
+`string` \| ``null``
+
+The type string (e.g., "PUBLIC KEY", "PRIVATE KEY"), or null if not valid PEM
+
+___
+
+### findSchemaLabel
+
+▸ **findSchemaLabel**(`labels`): `undefined` \| `SchemaName`
+
+Finds the label (on a profile object) which is the schema name
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `labels` | `undefined` \| `string`[] |
+
+#### Returns
+
+`undefined` \| `SchemaName`
+
+___
+
+### findSuitableLocale
+
+▸ **findSuitableLocale**(`options`, `langs`): `undefined` \| `string`
 
 Selects the most suitable locale to use from a list of options.
-Returns undefined if there is no language that the user speaks
+Returns undefined if there is no language that the user speaks.
+
+Priority order:
+1. Exact full locale match (e.g., user has en-NZ, schema has en-NZ)
+2. Base language match (e.g., user has en-US, schema has en)
+3. Any locale with matching base language (e.g., user has de-DE, schema has de-AT)
 
 #### Parameters
 
@@ -390,6 +1089,49 @@ Returns undefined if there is no language that the user speaks
 
 ___
 
+### formatFingerprint
+
+▸ **formatFingerprint**(`fingerprint`): `string`
+
+Format a key fingerprint for display
+
+Converts to uppercase and groups into 4-character blocks separated by spaces.
+For example: "abcd1234efgh5678" becomes "ABCD 1234 EFGH 5678"
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `fingerprint` | `string` | Raw fingerprint string (typically 40 hex characters) |
+
+#### Returns
+
+`string`
+
+Formatted fingerprint string
+
+___
+
+### formatLocalSecret
+
+▸ **formatLocalSecret**(`secret`): [`FormattedLocalSecret`](interfaces/FormattedLocalSecret.md)
+
+Format a LocalSecret for human-readable display
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `secret` | `Uint8Array` | The 32-byte LocalSecret |
+
+#### Returns
+
+[`FormattedLocalSecret`](interfaces/FormattedLocalSecret.md)
+
+Formatted LocalSecret with grouped characters
+
+___
+
 ### fromCognitoAttributes
 
 ▸ **fromCognitoAttributes**(`attributes`): `UserDoc`
@@ -409,407 +1151,1156 @@ The userAttributes come from `const attributes = await Auth.userAttributes(user)
 
 ___
 
-### getAADecryptor
+### generateDeviceId
 
-▸ **getAADecryptor**(`«destructured»`): `Promise`<{ `decryptor`: `ApplicationEncryptor` ; `publicKeyId`: `KId`  }\>
+▸ **generateDeviceId**(): `string`
 
-Fetchs the public and private keys for an Access Application, then initializes
-the [https://npm.im/@raytio/maxcryptor|Maxcryptor](https://npm.im/@raytio/maxcryptor|Maxcryptor)'s `ApplicationEncryptor`.
+Generate a unique device ID
+
+Used to identify devices for LocalSecret management.
+
+#### Returns
+
+`string`
+
+UUID v4 string
+
+___
+
+### generateLocalSecret
+
+▸ **generateLocalSecret**(): `Uint8Array`
+
+Generate a new LocalSecret
+
+Uses the Web Crypto API's getRandomValues for cryptographically
+secure random number generation.
+
+#### Returns
+
+`Uint8Array`
+
+32-byte (256-bit) random LocalSecret
+
+___
+
+### generatePGPKeyPair
+
+▸ **generatePGPKeyPair**(): `Promise`<[`PGPKeyPair`](interfaces/PGPKeyPair.md)\>
+
+Generate an RSA 4096-bit key pair for digital signatures
+
+#### Returns
+
+`Promise`<[`PGPKeyPair`](interfaces/PGPKeyPair.md)\>
+
+Generated key pair with PEM public key and raw private key bytes
+
+___
+
+### generateRandomBytes
+
+▸ **generateRandomBytes**(`length`): `Uint8Array`
+
+Generate cryptographically secure random bytes
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `«destructured»` | `Object` |
-| › `aId` | `AId` |
-| › `apiToken` | `string` |
-| › `apiUrl` | `string` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `length` | `number` | Number of bytes to generate |
+
+#### Returns
+
+`Uint8Array`
+
+Random bytes
+
+___
+
+### generateSalt
+
+▸ **generateSalt**(): `string`
+
+Generate a random salt for key derivation
+
+#### Returns
+
+`string`
+
+16-byte random salt as base64 string
+
+___
+
+### getAADecryptor
+
+▸ **getAADecryptor**(`«destructured»`): `Promise`<{ `decryptor`: `ApplicationEncryptor` ; `publicKeyId`: `KId`  }\>
+
+Fetchs the public and private keys for an Access Application, then initializes
+the [https://npm.im/@raytio/maxcryptor|Maxcryptor](https://npm.im/@raytio/maxcryptor|Maxcryptor)'s `ApplicationEncryptor`.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `«destructured»` | `Object` |
+| › `aId` | `AId` |
+| › `apiToken` | `string` |
+| › `apiUrl` | `string` |
 | › `maxcryptor` | `DataEncryptorI` |
 
 #### Returns
 
-`Promise`<{ `decryptor`: `ApplicationEncryptor` ; `publicKeyId`: `KId`  }\>
+`Promise`<{ `decryptor`: `ApplicationEncryptor` ; `publicKeyId`: `KId`  }\>
+
+an `ApplicationEncryptor` and the public key of the Access Application
+
+___
+
+### getAAPublicKey
+
+▸ **getAAPublicKey**(`«destructured»`): `Promise`<`PublicKeyNode`\>
+
+Fetches the Public Key Information for an Access Application
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `«destructured»` | `Object` |
+| › `aId` | `AId` |
+| › `apiToken?` | `string` |
+| › `apiUrl` | `string` |
+
+#### Returns
+
+`Promise`<`PublicKeyNode`\>
+
+the id and Key information of the Applications Public Key
+
+___
+
+### getKdfVersion
+
+▸ **getKdfVersion**(`config`): `number`
+
+Get the KDF version from configuration
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `config` | [`KdfConfig`](#kdfconfig) | KDF configuration |
+
+#### Returns
+
+`number`
+
+Version number (1 for PBKDF2, 2 for Argon2id with 2SKD)
+
+___
+
+### getLocalSecret
+
+▸ **getLocalSecret**(`userId`): `Promise`<`Uint8Array` \| ``null``\>
+
+Retrieve a LocalSecret from IndexedDB
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `userId` | `string` | User's Cognito sub |
+
+#### Returns
+
+`Promise`<`Uint8Array` \| ``null``\>
+
+The LocalSecret or null if not found
+
+___
+
+### getLocalSecretRecord
+
+▸ **getLocalSecretRecord**(`userId`): `Promise`<[`StoredLocalSecret`](interfaces/StoredLocalSecret.md) \| ``null``\>
+
+Get the stored LocalSecret record (including metadata)
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `userId` | `string` | User's Cognito sub |
+
+#### Returns
+
+`Promise`<[`StoredLocalSecret`](interfaces/StoredLocalSecret.md) \| ``null``\>
+
+The full storage record or null
+
+___
+
+### getMissingDataForInstance
+
+▸ **getMissingDataForInstance**(`«destructured»`): `Promise`<`Instance`\>
+
+the new API doesn't return the whole instance at once,
+so we have to make several additional API requests.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `«destructured»` | `Object` |
+| › `apiToken` | `string` |
+| › `apiUrl` | `string` |
+| › `instanceWithoutData` | `InstanceWithoutData` |
+
+#### Returns
+
+`Promise`<`Instance`\>
+
+___
+
+### getNidFromUrn
+
+▸ **getNidFromUrn**<`IDType`\>(`urn`): `IDType`
+
+two overloads - if you provide undefined, you might get undefined back
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `IDType` | `NId` |
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `urn` | `Urn` |
+
+#### Returns
+
+`IDType`
+
+▸ **getNidFromUrn**<`IDType`\>(`urn`): `undefined` \| `IDType`
+
+two overloads - if you provide undefined, you might get undefined back
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `IDType` | `NId` |
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `urn` | `undefined` \| `Urn` |
+
+#### Returns
+
+`undefined` \| `IDType`
+
+___
+
+### getOrCreateDeviceId
+
+▸ **getOrCreateDeviceId**(): `Promise`<`string`\>
+
+Get or create a unique device ID
+
+The device ID is stored in localStorage for persistence.
+
+#### Returns
+
+`Promise`<`string`\>
+
+___
+
+### getOwnRealVerifications
+
+▸ **getOwnRealVerifications**(`«destructured»`): `Promise`<`RealVer`[]\>
+
+Given a list of verifications and decrypted profile objects, this function
+locally verifies the credibility of the signatures in the verifications.
+
+This function does NOT call the API, except to fetch the public key.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `«destructured»` | `Object` |
+| › `profileObjects` | `ProfileObject`[] |
+| › `userId` | `UId` |
+| › `verifications` | `Verification`[] |
+
+#### Returns
+
+`Promise`<`RealVer`[]\>
+
+a list of authentic RealVer
+
+___
+
+### getPGPPrivateKey
+
+▸ **getPGPPrivateKey**(`userId`): `Promise`<[`StoredPGPPrivateKey`](interfaces/StoredPGPPrivateKey.md) \| ``null``\>
+
+Retrieve an encrypted PGP private key from IndexedDB
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `userId` | `string` | User's Cognito sub |
+
+#### Returns
+
+`Promise`<[`StoredPGPPrivateKey`](interfaces/StoredPGPPrivateKey.md) \| ``null``\>
+
+The encrypted private key record or null if not found
+
+___
+
+### getPOVerification
+
+▸ **getPOVerification**(`«destructured»`): `Object`
+
+Determines the verification status of a profile object, and its individual fields.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `«destructured»` | `Object` |
+| › `PO` | `ProfileObject` \| `ProfileObjectForUpload` |
+| › `realVers` | `RealVer`[] |
+| › `schema` | `Schema` |
+
+#### Returns
+
+`Object`
+
+| Name | Type |
+| :------ | :------ |
+| `details` | [`VerDetails`](#verdetails) |
+| `fieldVerifications` | `Record`<`string`, `FieldVerification`\> |
+| `status` | `POVerification` |
+
+___
+
+### getSomeoneElsesRealVerifications
+
+▸ **getSomeoneElsesRealVerifications**(`«destructured»`): `Promise`<`RealVer`[]\>
+
+Given a list of verifications and decrypted profile objects, this function calls
+the Raytio API to verify the credibility of these verifications, returning only valid
+verifications.
+
+❗ prefer `getOwnRealVerifications` if the data to be verified belongs to the current user.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `«destructured»` | `Props` |
+
+#### Returns
+
+`Promise`<`RealVer`[]\>
+
+a list of fileNames/values that are verified.
+
+___
+
+### hasLocalSecret
+
+▸ **hasLocalSecret**(`userId`): `Promise`<`boolean`\>
+
+Check if a LocalSecret exists for a user
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `userId` | `string` | User's Cognito sub |
+
+#### Returns
+
+`Promise`<`boolean`\>
+
+true if a LocalSecret exists
+
+___
+
+### hasPGPPrivateKey
+
+▸ **hasPGPPrivateKey**(`userId`): `Promise`<`boolean`\>
+
+Check if an encrypted PGP private key exists for a user
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `userId` | `string` | User's Cognito sub |
+
+#### Returns
+
+`Promise`<`boolean`\>
+
+true if a key exists
+
+___
+
+### hashPassword
+
+▸ **hashPassword**(`password`): `Promise`<`string`\>
+
+**`Deprecated`**
+
+legacy feature, see #1252
+
+AWS Cognito never gets the raw password. We send them
+a hashed verison using PBKDF2 with SHA-256 and 10,000
+iterations.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `password` | `string` | The raw password |
+
+#### Returns
+
+`Promise`<`string`\>
+
+Promise resolving to the hashed password
+
+___
+
+### importPrivateKey
+
+▸ **importPrivateKey**(`privateKeyBytes`): `Promise`<`CryptoKey`\>
+
+Import private key bytes as a CryptoKey for RSA-PSS signing
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `privateKeyBytes` | `Uint8Array` | Private key in PKCS8 format |
+
+#### Returns
+
+`Promise`<`CryptoKey`\>
+
+CryptoKey configured for RSA-PSS signing with SHA-256
+
+___
+
+### importPublicKey
+
+▸ **importPublicKey**(`publicKeyPem`): `Promise`<`CryptoKey`\>
+
+Import a PEM-encoded public key as a CryptoKey for RSA-PSS verification
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `publicKeyPem` | `string` | Public key in PEM format (SPKI) |
+
+#### Returns
+
+`Promise`<`CryptoKey`\>
+
+CryptoKey configured for RSA-PSS verification with SHA-256
+
+___
+
+### isArgon2Available
+
+▸ **isArgon2Available**(): `boolean`
+
+Check if Argon2 module is available
+
+#### Returns
+
+`boolean`
+
+___
+
+### isArgon2idConfig
+
+▸ **isArgon2idConfig**(`config`): config is Argon2idConfig
+
+Type guard for Argon2id config
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `config` | [`KdfConfig`](#kdfconfig) |
+
+#### Returns
+
+config is Argon2idConfig
+
+___
+
+### isArmoredPGPKey
+
+▸ **isArmoredPGPKey**(`input`): `boolean`
+
+Check if a string looks like an armored PGP key
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `input` | `string` | String to check |
+
+#### Returns
+
+`boolean`
+
+true if it appears to be armored PGP format
+
+___
+
+### isConditionMet
+
+▸ **isConditionMet**(`condition`, `formValues`): `boolean`
+
+Checks all other form values in case any have a
+trigger value that makes this field required.
+
+**`Example`**
+
+```json
+[
+  { "if": { "age": [17, 18], "city": ["Taupō"] } },
+  { "if": { "age": [19, 20] } }
+]
+```
+
+This means `[(age=17 OR age=18) AND (city=Taupō)] OR [(age=19 OR age=20)]`
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `condition` | `Record`<`string`, `ConditionValue`[]\> |
+| `formValues` | `Record`<`string`, `unknown`\> |
+
+#### Returns
+
+`boolean`
+
+___
+
+### isEncrypted
+
+▸ **isEncrypted**(`value`): value is Encrypted
+
+Determines where the input is an encrypted Raytio object
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `value` | `unknown` | anything |
+
+#### Returns
+
+value is Encrypted
+
+true or false depending on whether the input is an encrypted Raytio object
+
+___
+
+### isEncryptedFile
+
+▸ **isEncryptedFile**(`value`): value is Encrypted
+
+Determines where the input is an encrypted Raytio file
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `value` | `unknown` | anything |
+
+#### Returns
+
+value is Encrypted
+
+true or false depending on whether the input is an encrypted Raytio file
+
+___
+
+### isPbkdf2Config
+
+▸ **isPbkdf2Config**(`config`): config is Pbkdf2Config
+
+Type guard for PBKDF2 config
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `config` | [`KdfConfig`](#kdfconfig) |
+
+#### Returns
+
+config is Pbkdf2Config
+
+___
+
+### isPemFormat
+
+▸ **isPemFormat**(`input`): `boolean`
+
+Check if a string is in valid PEM format
+
+PEM format requires:
+- A BEGIN header with a type (e.g., "-----BEGIN PUBLIC KEY-----")
+- Base64-encoded content
+- An END footer with matching type (e.g., "-----END PUBLIC KEY-----")
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `input` | `string` | String to check |
+
+#### Returns
+
+`boolean`
+
+true if the string is valid PEM format, false otherwise
+
+___
+
+### isScoreConfigValid
+
+▸ **isScoreConfigValid**(`x`): x is ScoreConfig
+
+determines whether a `ScoreConfig` object is valid
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `x` | `unknown` |
+
+#### Returns
+
+x is ScoreConfig
+
+___
+
+### isScoreResultValid
+
+▸ **isScoreResultValid**(`x`): x is ScoreResult
+
+determines whether a `ScoreResult` object is valid
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `x` | `unknown` |
+
+#### Returns
+
+x is ScoreResult
+
+___
+
+### isValidFormattedLocalSecret
+
+▸ **isValidFormattedLocalSecret**(`formatted`): `boolean`
+
+Validate a formatted LocalSecret string
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `formatted` | `string` | The formatted LocalSecret string |
+
+#### Returns
+
+`boolean`
+
+true if valid, false otherwise
+
+___
+
+### isValidLocalSecret
+
+▸ **isValidLocalSecret**(`localSecret`): localSecret is Uint8Array
+
+Verify that a LocalSecret is valid
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `localSecret` | `undefined` \| ``null`` \| `Uint8Array` | The LocalSecret to verify |
+
+#### Returns
+
+localSecret is Uint8Array
+
+true if valid
+
+___
+
+### maskLocalSecret
+
+▸ **maskLocalSecret**(`formatted`): `string`
+
+Mask a LocalSecret for partial display
+
+Shows only the first and last groups, masking the middle.
+Example: A7K2M9-******-******-******-******-V6Z4C1
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `formatted` | `string` | The formatted LocalSecret |
+
+#### Returns
+
+`string`
+
+Masked version for display
+
+___
+
+### normalizePassword
+
+▸ **normalizePassword**(`password`): `string`
+
+Normalize password for key derivation
+
+Applies NFKD normalization and trims whitespace.
+This ensures consistent key derivation across platforms.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `password` | `string` | Raw password input |
+
+#### Returns
+
+`string`
 
-an `ApplicationEncryptor` and the public key of the Access Application
+Normalized password string
 
 ___
 
-### getAAPublicKey
+### parseArmoredPGPKey
 
-▸ **getAAPublicKey**(`«destructured»`): `Promise`<`PublicKeyNode`\>
+▸ **parseArmoredPGPKey**(`armoredKey`, `passphrase?`): `Promise`<[`ParsedPGPKey`](interfaces/ParsedPGPKey.md)\>
 
-Fetches the Public Key Information for an Access Application
+Parse an armored PGP private key
+
+**`Throws`**
+
+PGPKeyImportError if parsing fails
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `«destructured»` | `Object` |
-| › `aId` | `AId` |
-| › `apiToken` | `string` |
-| › `apiUrl` | `string` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `armoredKey` | `string` | Armored PGP private key string |
+| `passphrase?` | `string` | Optional passphrase if key is encrypted |
 
 #### Returns
 
-`Promise`<`PublicKeyNode`\>
+`Promise`<[`ParsedPGPKey`](interfaces/ParsedPGPKey.md)\>
 
-the id and Key information of the Applications Public Key
+Parsed key data
 
 ___
 
-### getMissingDataForInstance
+### parseLocalSecret
 
-▸ **getMissingDataForInstance**(`«destructured»`): `Promise`<`Instance`\>
+▸ **parseLocalSecret**(`formatted`): `Uint8Array`
 
-the new API doesn't return the whole instance at once,
-so we have to make several additional API requests.
+Parse a formatted LocalSecret back to bytes
+
+Handles various input formats:
+- With dashes: A7K2M9-X4P8N3-...
+- Without dashes: A7K2M9X4P8N3...
+- With spaces: A7K2M9 X4P8N3 ...
+- Lowercase: a7k2m9-x4p8n3-...
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `«destructured»` | `Object` |
-| › `apiToken` | `string` |
-| › `apiUrl` | `string` |
-| › `instanceWithoutData` | `InstanceWithoutData` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `formatted` | `string` | The formatted LocalSecret string |
 
 #### Returns
 
-`Promise`<`Instance`\>
+`Uint8Array`
+
+The 32-byte LocalSecret
 
 ___
 
-### getNidFromUrn
+### pemToBytes
 
-▸ **getNidFromUrn**<`IDType`\>(`urn`): `IDType`
+▸ **pemToBytes**(`pem`): `Uint8Array`
 
-two overloads - if you provide undefined, you might get undefined back
+Convert PEM-formatted string to raw bytes
 
-#### Type parameters
+Extracts the base64 content from between the PEM headers and decodes it.
 
-| Name | Type |
-| :------ | :------ |
-| `IDType` | `NId` |
+**`Throws`**
+
+Error if the input is not valid PEM format
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `urn` | `Urn` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `pem` | `string` | PEM-formatted string |
 
 #### Returns
 
-`IDType`
+`Uint8Array`
 
-▸ **getNidFromUrn**<`IDType`\>(`urn`): `undefined` \| `IDType`
+Raw bytes as Uint8Array
 
-two overloads - if you provide undefined, you might get undefined back
+___
 
-#### Type parameters
+### repairDate
 
-| Name | Type |
-| :------ | :------ |
-| `IDType` | `NId` |
+▸ **repairDate**(`date`): `Date`
+
+repairs broken ISO dates into valid JS date objects
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
-| `urn` | `undefined` \| `Urn` |
+| `date` | `string` \| `Date` |
 
 #### Returns
 
-`undefined` \| `IDType`
+`Date`
 
 ___
 
-### getOwnRealVerifications
-
-▸ **getOwnRealVerifications**(`«destructured»`): `Promise`<`RealVer`[]\>
+### requiresLocalSecret
 
-Given a list of verifications and decrypted profile objects, this function
-locally verifies the credibility of the signatures in the verifications.
+▸ **requiresLocalSecret**(`config`): `boolean`
 
-This function does NOT call the API, except to fetch the public key.
+Check if a KDF configuration requires LocalSecret
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `«destructured»` | `Object` |
-| › `profileObjects` | `ProfileObject`[] |
-| › `userId` | `UId` |
-| › `verifications` | `Verification`[] |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `config` | [`KdfConfig`](#kdfconfig) | KDF configuration |
 
 #### Returns
 
-`Promise`<`RealVer`[]\>
+`boolean`
 
-a list of authentic RealVer
+true if LocalSecret is required
 
 ___
 
-### getPOVerification
+### setArgon2Module
 
-▸ **getPOVerification**(`«destructured»`): `Object`
+▸ **setArgon2Module**(`module`): `void`
 
-Determines the verification status of a profile object, and its individual fields.
+Set the Argon2 module reference
+
+This must be called before using deriveArgon2id.
+The module is passed in from packages/client where argon2-browser is imported.
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `«destructured»` | `Object` |
-| › `PO` | `ProfileObject` \| `ProfileObjectForUpload` |
-| › `realVers` | `RealVer`[] |
-| › `schema` | `Schema` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `module` | `Argon2Module` | The argon2-browser module |
 
 #### Returns
 
-`Object`
-
-| Name | Type |
-| :------ | :------ |
-| `details` | [`VerDetails`](#verdetails) |
-| `fieldVerifications` | `Record`<`string`, `FieldVerification`\> |
-| `status` | `POVerification` |
+`void`
 
 ___
 
-### getSomeoneElsesRealVerifications
-
-▸ **getSomeoneElsesRealVerifications**(`«destructured»`): `Promise`<`RealVer`[]\>
+### signData
 
-Given a list of verifications and decrypted profile objects, this function calls
-the Raytio API to verify the credibility of these verifications, returning only valid
-verifications.
+▸ **signData**(`data`, `privateKey`): `Promise`<`Uint8Array`\>
 
-❗ prefer `getOwnRealVerifications` if the data to be verified belongs to the current user.
+Sign raw bytes with an RSA-PSS private key
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `«destructured»` | `Props` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `data` | `Uint8Array` | Data to sign as Uint8Array |
+| `privateKey` | `CryptoKey` | CryptoKey configured for RSA-PSS signing |
 
 #### Returns
 
-`Promise`<`RealVer`[]\>
+`Promise`<`Uint8Array`\>
 
-a list of fileNames/values that are verified.
+Signature bytes (512 bytes for RSA-4096)
 
 ___
 
-### hashPassword
-
-▸ **hashPassword**(`password`): `Promise`<`string`\>
+### signText
 
-**`Deprecated`**
+▸ **signText**(`text`, `privateKey`): `Promise`<`string`\>
 
-legacy feature, see #1252
+Sign text and return base64-encoded signature
 
-AWS Cognito never gets the raw password. We send them
-a hashed verison using PBKDF2 with SHA-256 and 10,000
-iterations.
+Convenience wrapper that encodes text to UTF-8 bytes before signing.
 
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `password` | `string` | The raw password |
+| `text` | `string` | Text to sign |
+| `privateKey` | `CryptoKey` | CryptoKey configured for RSA-PSS signing |
 
 #### Returns
 
 `Promise`<`string`\>
 
-Promise resolving to the hashed password
+Base64-encoded signature string
 
 ___
 
-### isConditionMet
-
-▸ **isConditionMet**(`condition`, `formValues`): `boolean`
+### someEncrypted
 
-Checks all other form values in case any have a
-trigger value that makes this field required.
+▸ **someEncrypted**<`T`\>(`...args`): `number`
 
-**`Example`**
+Given a profile object's properties, returns the number
+of properties that are encryted.
 
-```json
-[
-  { "if": { "age": [17, 18], "city": ["Taupō"] } },
-  { "if": { "age": [19, 20] } }
-]
-```
+#### Type parameters
 
-This means `[(age=17 OR age=18) AND (city=Taupō)] OR [(age=19 OR age=20)]`
+| Name | Type |
+| :------ | :------ |
+| `T` | extends `object` |
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
-| `condition` | `Record`<`string`, `ConditionValue`[]\> |
-| `formValues` | `Record`<`string`, `unknown`\> |
+| `...args` | [obj: T] |
 
 #### Returns
 
-`boolean`
+`number`
 
 ___
 
-### isEncrypted
+### sortSchemaProperties
 
-▸ **isEncrypted**(`value`): value is Encrypted
+▸ **sortSchemaProperties**(`properties`, `groupOrder?`): `Section`[]
 
-Determines where the input is an encrypted Raytio object
+Schema properties are an object, so they need to be converted into an
+array, grouped by the group tag, and then sorted based on the `priority`
+attribute within their group.
 
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `value` | `unknown` | anything |
+| `properties` | `Record`<`string`, `SchemaField`\> | The schema properties to sort |
+| `groupOrder?` | `string`[] | Optional array specifying the order of groups. Groups not in this array will appear after ordered groups. |
 
 #### Returns
 
-value is Encrypted
-
-true or false depending on whether the input is an encrypted Raytio object
+`Section`[]
 
 ___
 
-### isEncryptedFile
+### storeLocalSecret
 
-▸ **isEncryptedFile**(`value`): value is Encrypted
+▸ **storeLocalSecret**(`userId`, `secret`): `Promise`<`void`\>
 
-Determines where the input is an encrypted Raytio file
+Store a LocalSecret in IndexedDB
 
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `value` | `unknown` | anything |
+| `userId` | `string` | User's Cognito sub |
+| `secret` | `Uint8Array` | The 32-byte LocalSecret |
 
 #### Returns
 
-value is Encrypted
-
-true or false depending on whether the input is an encrypted Raytio file
+`Promise`<`void`\>
 
 ___
 
-### isScoreConfigValid
+### storePGPPrivateKey
 
-▸ **isScoreConfigValid**(`x`): x is ScoreConfig
+▸ **storePGPPrivateKey**(`record`): `Promise`<`void`\>
 
-determines whether a `ScoreConfig` object is valid
+Store an encrypted PGP private key in IndexedDB
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `x` | `unknown` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `record` | [`StoredPGPPrivateKey`](interfaces/StoredPGPPrivateKey.md) | The encrypted private key record to store |
 
 #### Returns
 
-x is ScoreConfig
+`Promise`<`void`\>
 
 ___
 
-### isScoreResultValid
+### toCognitoAttributes
 
-▸ **isScoreResultValid**(`x`): x is ScoreResult
+▸ **toCognitoAttributes**(`userDoc`): `Object`
 
-determines whether a `ScoreResult` object is valid
+Given a `UserDoc` from the maxcryptor, this returns an object
+which you can provide to `Auth.updateUserAttributes()`. It is
+an object of stringified Json.
+
+Note: Only includes attributes that exist in userDoc. Missing attributes
+are filtered out to avoid Cognito "Attribute value must not be null" errors.
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
-| `x` | `unknown` |
+| `userDoc` | `UserDoc` |
 
 #### Returns
 
-x is ScoreResult
+`Object`
 
 ___
 
-### repairDate
+### uint8ArrayToBase64
 
-▸ **repairDate**(`date`): `Date`
+▸ **uint8ArrayToBase64**(`bytes`): `string`
 
-repairs broken ISO dates into valid JS date objects
+Convert Uint8Array to base64 string
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
-| `date` | `string` \| `Date` |
+| `bytes` | `Uint8Array` |
 
 #### Returns
 
-`Date`
+`string`
 
 ___
 
-### someEncrypted
+### validateImportedKey
 
-▸ **someEncrypted**<`T`\>(`...args`): `number`
+▸ **validateImportedKey**(`parsedKey`): [`KeyValidationResult`](interfaces/KeyValidationResult.md)
 
-Given a profile object's properties, returns the number
-of properties that are encryted.
+Validate an imported key
 
-#### Type parameters
+#### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `T` | extends `object` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `parsedKey` | [`ParsedPGPKey`](interfaces/ParsedPGPKey.md) | Parsed key to validate |
+
+#### Returns
+
+[`KeyValidationResult`](interfaces/KeyValidationResult.md)
+
+Validation result with any warnings
+
+___
+
+### verifySignature
+
+▸ **verifySignature**(`data`, `signature`, `publicKey`): `Promise`<`boolean`\>
+
+Verify an RSA-PSS signature
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `...args` | [obj: T] |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `data` | `Uint8Array` | Original data that was signed |
+| `signature` | `Uint8Array` | Signature bytes to verify |
+| `publicKey` | `CryptoKey` | CryptoKey configured for RSA-PSS verification |
 
 #### Returns
 
-`number`
+`Promise`<`boolean`\>
+
+True if signature is valid, false otherwise
 
 ___
 
-### sortSchemaProperties
+### verifyTextSignature
 
-▸ **sortSchemaProperties**(`properties`): `Section`[]
+▸ **verifyTextSignature**(`text`, `signatureBase64`, `publicKey`): `Promise`<`boolean`\>
 
-Schema properties are an object, so they need to be converted into an
-array, grouped by the group tag, and then sorted based on the `priority`
-attribute within their group.
+Verify a base64-encoded signature for text
+
+Convenience wrapper that decodes base64 signature and encodes text to UTF-8.
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `properties` | `Record`<`string`, `SchemaField`\> |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `text` | `string` | Original text that was signed |
+| `signatureBase64` | `string` | Base64-encoded signature to verify |
+| `publicKey` | `CryptoKey` | CryptoKey configured for RSA-PSS verification |
 
 #### Returns
 
-`Section`[]
+`Promise`<`boolean`\>
+
+True if signature is valid, false otherwise
 
 ___
 
-### toCognitoAttributes
+### xorBytes
 
-▸ **toCognitoAttributes**(`userDoc`): `Object`
+▸ **xorBytes**(`a`, `b`): `Uint8Array`
 
-Given a `UserDoc` from the maxcryptor, this returns an object
-which you can provide to `Auth.updateUserAttributes()`. It is
-an object of stringified Json.
+XOR two byte arrays of equal length
+
+Used for combining password-derived key with LocalSecret in 2SKD.
+This follows the 1Password approach of XOR combination.
+
+**`Throws`**
+
+Error if arrays are not the same length
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `userDoc` | `UserDoc` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `a` | `Uint8Array` | First byte array |
+| `b` | `Uint8Array` | Second byte array |
 
 #### Returns
 
-`Object`
+`Uint8Array`
+
+XOR result