@raytio/core

@raytio/core is a collection of low-level functions for using the Raytio API. It works in both the browser and a nodejs environment, although nodejs requires several polyfills (see below).

For a high-level and easy-to-use API, consider using @raytio/decrypt-helper.

Usage in nodejs

Nodejs does not support fetch, WebCrypto, or atob/btoa, so these will need to be polyfilled. Older versions of nodejs (<14.0.0) also do not support TextEncoder or Intl.DateTimeFormat.

If you use the high-level @raytio/decrypt-helper module, you don't need to worry about this.

If you wish to use @raytio/core directly, an example of configuring polyfills for nodejs is availble here

API

Table of contents

Classes

• LocalSecretRequiredError
• PGPKeyExportError
• PGPKeyImportError
• UnknownKdfAlgorithmError

Interfaces

• Argon2idConfig
• EncryptedPrivateKey
• ExportPGPKeyOptions
• ExportedPGPKey
• FormattedLocalSecret
• KdfResult
• KeyValidationResult
• LocalSecretStorage
• PGPKeyPair
• PGPKeyStorage
• PGPPublicKeyProperties
• ParsedPGPKey
• Pbkdf2Config
• StoredLocalSecret
• StoredPGPPrivateKey

Type Aliases

• BadgeDefinition
• BadgeResult
• BadgeState
• BadgeStateDisplay
• KdfConfig
• PGPKeyAlgorithm
• SafeHarbourObj
• SafeHarbourResult
• ServerAA
• ServerRelationship
• VerDetails

Variables

• AES_GCM_IV_SIZE
• DEFAULT_ARGON2ID_PARAMS
• KEY_FINGERPRINT_LENGTH
• LOCAL_SECRET_CHARSET
• LOCAL_SECRET_DB_CONFIG
• LOCAL_SECRET_GROUP_SIZE
• LOCAL_SECRET_SIZE
• PGP_KEY_DB_CONFIG
• TAG_DENYLIST

Functions

• base64ToUint8Array
• bytesToPem
• calcSafeHarbourScore
• calculateScore
• canonicalJsonify
• checkJsonSignature
• computeKeyFingerprint
• constantTimeEqual
• convertInstanceToRuleInput
• convertServerRelationship
• createAA
• createArgon2idConfig
• createHashedNId
• createIndexedDBPGPKeyStorage
• createIndexedDBStorage
• decryptPrivateKey
• decryptSharedData
• deleteLocalSecret
• deletePGPPrivateKey
• deriveArgon2id
• deriveKey
• derivePbkdf2
• deriveTwoSecretKdf
• encryptPrivateKey
• evaluateBadge
• evaluateRule
• evaluateUserBadges
• expandSchema
• exportPGPKeyToArmored
• extractPemType
• findSchemaLabel
• findSuitableLocale
• formatFingerprint
• formatLocalSecret
• fromCognitoAttributes
• generateDeviceId
• generateLocalSecret
• generatePGPKeyPair
• generateRandomBytes
• generateSalt
• getAADecryptor
• getAAPublicKey
• getKdfVersion
• getLocalSecret
• getLocalSecretRecord
• getMissingDataForInstance
• getNidFromUrn
• getOrCreateDeviceId
• getOwnRealVerifications
• getPGPPrivateKey
• getPOVerification
• getSomeoneElsesRealVerifications
• hasLocalSecret
• hasPGPPrivateKey
• hashPassword
• importPrivateKey
• importPublicKey
• isArgon2Available
• isArgon2idConfig
• isArmoredPGPKey
• isConditionMet
• isEncrypted
• isEncryptedFile
• isPbkdf2Config
• isPemFormat
• isScoreConfigValid
• isScoreResultValid
• isValidFormattedLocalSecret
• isValidLocalSecret
• maskLocalSecret
• normalizePassword
• parseArmoredPGPKey
• parseLocalSecret
• pemToBytes
• repairDate
• requiresLocalSecret
• resolveSchemaExtensions
• setArgon2Module
• signData
• signText
• someEncrypted
• sortSchemaProperties
• storeLocalSecret
• storePGPPrivateKey
• toCognitoAttributes
• uint8ArrayToBase64
• validateImportedKey
• verifySignature
• verifyTextSignature
• xorBytes

Type Aliases

BadgeDefinition

Ƭ BadgeDefinition: CommonFields<BId> & { display: { states: Record<BadgeState, 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 | | state | 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 | Argon2idConfig

Union type for all KDF configurations

PGPKeyAlgorithm

Ƭ PGPKeyAlgorithm: "RSA-4096" | "RSA-2048"

Supported PGP key algorithms

SafeHarbourObj

Ƭ SafeHarbourObj: Partial<Record<SafeHarbourCode, string[]>>

an object listing the xIds for each SafeHarbourCode

SafeHarbourResult

Ƭ SafeHarbourResult: Object

the response from calcSafeHarbourScore

Type declaration

| Name | Type | | :------ | :------ | | flags | SafeHarbourObj | | isSafe | boolean |

ServerAA

Ƭ ServerAA: Omit<AA, "a_id"> & { id: AId }

ServerRelationship

Ƭ 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

VerDetails

Ƭ VerDetails: Object

Type declaration

| Name | Type | Description | | :------ | :------ | :------ | | expiryDate? | Date | field only present for expired verifications | | sourceNId? | NId | - | | verifiers | VerificationProvider[] | - |

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>

The Safe Harbour Score indidicates whether a person's identity has been verified to the extent requried for Safe Harbour Compliance. This requires multiple verifications from different sources. For information, refer to the Raytio Documentation.

Parameters

| Name | Type | | :------ | :------ | | data | Object | | data.person | ProfileObject | | data.profileObjects | ProfileObject[] | | data.realVers | RealVer[] | | data.getSchema | (schemaName: SchemaName) => Promise<Schema> |

Returns

Promise<SafeHarbourResult>

calculateScore

▸ calculateScore(ruleConfig, ruleInput): Promise<ScoreResult>

the main function to calculate a score and category. Might throw an error.

Parameters

| Name | Type | | :------ | :------ | | ruleConfig | ScoreConfig | | ruleInput | RuleData |

Returns

Promise<ScoreResult>

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>

checks that a json object was signed by the provided signature. Unless you're dealing with bundled verifications, you should use getOwnRealVerifications or getSomeoneElsesRealVerifications instead.

Parameters

| Name | Type | | :------ | :------ | | data | unknown | | signature | string | | keyId | undefined | string |

Returns

Promise<boolean>

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>

Parameters

| Name | Type | | :------ | :------ | | POs | ProfileObject[] | | realVers | RealVer[] | | getSchema | (schemaName: SchemaName) => Promise<Schema> |

Returns

Promise<RuleData>

convertServerRelationship

▸ convertServerRelationship(serverRelationship): Relationship

Converts relationship type used by the server into the (Urn format) type used by the client

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | serverRelationship | ServerRelationship | relationship type used in the server |

Returns

Relationship

a Relationship (client-side type) that is equivalent to the inputted serverRelationship value

createAA

▸ createAA(«destructured»): Promise<AA>

Creates an Access Application and associated public+private keys.

The user must be part of an organization, and you need to include the orgId.

You must also supply an apiToken and an instance of the maxcryptor for that user, as well as the userDoc data which is stored in the user's cognito attributes.

Parameters

| Name | Type | | :------ | :------ | | «destructured» | Object | | › apiToken | string | | › apiUrl | string | | › application | Omit<AA, "a_id"> | | › maxcryptor | DataEncryptorI | | › userDoc | UserDoc |

Returns

Promise<AA>

createArgon2idConfig

▸ createArgon2idConfig(salt, params?): Argon2idConfig

Create a new Argon2id configuration

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | salt | string | Base64 encoded salt (optional, will generate if not provided) | | params? | Partial<Pick<Argon2idConfig, "iterations" | "memory" | "parallelism">> | Optional custom parameters |

Returns

Argon2idConfig

Argon2idConfig ready for storage

createHashedNId

▸ createHashedNId(nId, aId): NId

the API returns hashed NIds in a separate field, which breaks the whole app. So, we move the hashed ID into the normal n_id field, and use a different format.

This was first introduced in #1048

Parameters

| Name | Type | | :------ | :------ | | nId | NId | | aId | AId |

Returns

NId

createIndexedDBPGPKeyStorage

▸ createIndexedDBPGPKeyStorage(): PGPKeyStorage

Create a PGPKeyStorage implementation using IndexedDB

Returns

PGPKeyStorage

createIndexedDBStorage

▸ createIndexedDBStorage(): LocalSecretStorage

Create a LocalSecretStorage implementation using IndexedDB

Returns

LocalSecretStorage

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 }>

Decrypts any encrypted properties included in the supplied instanceData. If nothing is encrypted the supplied instanceData is returned.

It will reject if there are keys missing for any encrypted properties, or if the encrypted data is invalid. If you don't want it to reject, you can supply a onCorruptedData function which returns a value to use instead.

Parameters

| Name | Type | | :------ | :------ | | «destructured» | Object | | › apiToken | string | | › apiUrl | string | | › instanceData | Instance | | › maxcryptor | DataEncryptorI | | › onCorruptedData? | (fieldName: string, fieldValue: Encrypted, error: Error) => any |

Returns

Promise<{ applicationDecryptor: ApplicationDataEncryptorI ; instance: Instance }>

a copy of instanceData with all properties decrypted.

deleteLocalSecret

▸ deleteLocalSecret(userId): Promise<void>

Delete a LocalSecret from IndexedDB

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | userId | string | User's Cognito sub |

Returns

Promise<void>

deletePGPPrivateKey

▸ deletePGPPrivateKey(userId): Promise<void>

Delete an encrypted PGP private key from IndexedDB

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | userId | string | User's Cognito sub |

Returns

Promise<void>

deriveArgon2id

▸ deriveArgon2id(password, config): Promise<KdfResult>

Derive a key using Argon2id

Throws

Error if argon2 module is not available

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | password | string | User's password (will be normalized) | | config | Argon2idConfig | Argon2id configuration from Cognito attributes |

Returns

Promise<KdfResult>

KdfResult containing the derived 32-byte key

deriveKey

▸ deriveKey(password, config, localSecret?): Promise<KdfResult>

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 | KDF configuration from Cognito attributes | | localSecret? | null | Uint8Array | Optional LocalSecret for 2SKD (required for Argon2id with requires_local_secret) |

Returns

Promise<KdfResult>

KdfResult containing the derived key

derivePbkdf2

▸ derivePbkdf2(password, config): Promise<KdfResult>

Derive a key using PBKDF2

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | password | string | User's password | | config | Pbkdf2Config | PBKDF2 configuration from Cognito attributes |

Returns

Promise<KdfResult>

KdfResult containing the derived 32-byte key

deriveTwoSecretKdf

▸ deriveTwoSecretKdf(password, config, localSecret): Promise<KdfResult>

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 | Argon2id configuration | | localSecret | undefined | null | Uint8Array | Device-bound LocalSecret (32 bytes) |

Returns

Promise<KdfResult>

KdfResult containing the derived KEK

encryptPrivateKey

▸ encryptPrivateKey(privateKeyBytes, kek): Promise<EncryptedPrivateKey>

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>

Encrypted private key and IV

evaluateBadge

▸ evaluateBadge(badge, ruleData): Promise<BadgeResult>

Evaluate a single badge definition against user data. Thin wrapper around calculateScore() -- threshold names map to badge states.

Parameters

| Name | Type | | :------ | :------ | | badge | BadgeDefinition | | ruleData | RuleData |

Returns

Promise<BadgeResult>

evaluateRule

▸ evaluateRule(rule, data): Object

evaluates an individual rule, normally you should use calculateScore

Parameters

| Name | Type | | :------ | :------ | | rule | ScoreRule | | data | RuleData |

Returns

Object

| Name | Type | | :------ | :------ | | passed | boolean | | score | number |

evaluateUserBadges

▸ evaluateUserBadges(badges, ruleData): Promise<BadgeResult[]>

Evaluate all active badge definitions against user data.

Parameters

| Name | Type | | :------ | :------ | | badges | BadgeDefinition[] | | ruleData | RuleData |

Returns

Promise<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>

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 | Export options (passphrase, userIds, date) |

Returns

Promise<ExportedPGPKey>

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.

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

| Name | Type | | :------ | :------ | | options | string[] | | langs | readonly string[] |

Returns

undefined | string

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

Format a LocalSecret for human-readable display

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | secret | Uint8Array | The 32-byte LocalSecret |

Returns

FormattedLocalSecret

Formatted LocalSecret with grouped characters

fromCognitoAttributes

▸ fromCognitoAttributes(attributes): UserDoc

This function converts Cognito's userAttributes into a maxcryptor UserDoc. The userAttributes come from const attributes = await Auth.userAttributes(user)

Parameters

| Name | Type | | :------ | :------ | | attributes | ICognitoUserAttributeData[] |

Returns

UserDoc

generateDeviceId

▸ generateDeviceId(): string

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>

Generate an RSA 4096-bit key pair for digital signatures

Returns

Promise<PGPKeyPair>

Generated key pair with PEM public key and raw private key bytes

generateRandomBytes

▸ generateRandomBytes(length): Uint8Array

Generate cryptographically secure random bytes

Parameters

| 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's ApplicationEncryptor.

Parameters

| Name | Type | | :------ | :------ | | «destructured» | Object | | › aId | AId | | › apiToken | string | | › apiUrl | string | | › maxcryptor | DataEncryptorI |

Returns

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 | 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 | null>

Get the stored LocalSecret record (including metadata)

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | userId | string | User's Cognito sub |

Returns

Promise<StoredLocalSecret | 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 | null>

Retrieve an encrypted PGP private key from IndexedDB

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | userId | string | User's Cognito sub |

Returns

Promise<StoredPGPPrivateKey | 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 | | 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 |

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

[
  { "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 |

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

Normalized password string

parseArmoredPGPKey

▸ parseArmoredPGPKey(armoredKey, passphrase?): Promise<ParsedPGPKey>

Parse an armored PGP private key

Throws

PGPKeyImportError if parsing fails

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | armoredKey | string | Armored PGP private key string | | passphrase? | string | Optional passphrase if key is encrypted |

Returns

Promise<ParsedPGPKey>

Parsed key data

parseLocalSecret

▸ parseLocalSecret(formatted): Uint8Array

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 | Description | | :------ | :------ | :------ | | formatted | string | The formatted LocalSecret string |

Returns

Uint8Array

The 32-byte LocalSecret

pemToBytes

▸ pemToBytes(pem): Uint8Array

Convert PEM-formatted string to raw bytes

Extracts the base64 content from between the PEM headers and decodes it.

Throws

Error if the input is not valid PEM format

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | pem | string | PEM-formatted string |

Returns

Uint8Array

Raw bytes as Uint8Array

repairDate

▸ repairDate(date): Date

repairs broken ISO dates into valid JS date objects

Parameters

| Name | Type | | :------ | :------ | | date | string | Date |

Returns

Date

requiresLocalSecret

▸ requiresLocalSecret(config): boolean

Check if a KDF configuration requires LocalSecret

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | config | KdfConfig | KDF configuration |

Returns

boolean

true if LocalSecret is required

resolveSchemaExtensions

▸ resolveSchemaExtensions(schemas): WrappedSchema[]

Resolves schema extensions by deep-merging base schemas into extension schemas.

When a schema has extends_schema_name set, the base schema is looked up from the already-fetched schemas and deep-merged with the extension. The extension wins on conflict.

Design constraints:

• Single-level only: a base schema must not itself be an extension
• Same tenant only: enforced at DB level
• extends_schema_version: if set, matches against schema_version; if null, the base's version_current entry is used (already in the list)

Parameters

| Name | Type | | :------ | :------ | | schemas | WrappedSchema[] |

Returns

WrappedSchema[]

setArgon2Module

▸ setArgon2Module(module): void

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 | Description | | :------ | :------ | :------ | | module | Argon2Module | The argon2-browser module |

Returns

void

signData

▸ signData(data, privateKey): Promise<Uint8Array>

Sign raw bytes with an RSA-PSS private key

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | data | Uint8Array | Data to sign as Uint8Array | | privateKey | CryptoKey | CryptoKey configured for RSA-PSS signing |

Returns

Promise<Uint8Array>

Signature bytes (512 bytes for RSA-4096)

signText

▸ signText(text, privateKey): Promise<string>

Sign text and return base64-encoded signature

Convenience wrapper that encodes text to UTF-8 bytes before signing.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | text | string | Text to sign | | privateKey | CryptoKey | CryptoKey configured for RSA-PSS signing |

Returns

Promise<string>

Base64-encoded signature string

someEncrypted

▸ someEncrypted<T>(...args): number

Given a profile object's properties, returns the number of properties that are encryted.

Type parameters

| Name | Type | | :------ | :------ | | T | extends object |

Parameters

| Name | Type | | :------ | :------ | | ...args | [obj: T] |

Returns

number

sortSchemaProperties

▸ sortSchemaProperties(properties, groupOrder?): Section[]

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 | | :------ | :------ | :------ | | 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

Section[]

storeLocalSecret

▸ storeLocalSecret(userId, secret): Promise<void>

Store a LocalSecret in IndexedDB

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | userId | string | User's Cognito sub | | secret | Uint8Array | The 32-byte LocalSecret |

Returns

Promise<void>

storePGPPrivateKey

▸ storePGPPrivateKey(record): Promise<void>

Store an encrypted PGP private key in IndexedDB

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | record | StoredPGPPrivateKey | The encrypted private key record to store |

Returns

Promise<void>

toCognitoAttributes

▸ toCognitoAttributes(userDoc): Object

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 | | :------ | :------ | | userDoc | UserDoc |

Returns

Object

uint8ArrayToBase64

▸ uint8ArrayToBase64(bytes): string

Convert Uint8Array to base64 string

Parameters

| Name | Type | | :------ | :------ | | bytes | Uint8Array |

Returns

string

validateImportedKey

▸ validateImportedKey(parsedKey): KeyValidationResult

Validate an imported key

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | parsedKey | ParsedPGPKey | Parsed key to validate |

Returns

KeyValidationResult

Validation result with any warnings

verifySignature

▸ verifySignature(data, signature, publicKey): Promise<boolean>

Verify an RSA-PSS signature

Parameters

| 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

Promise<boolean>

True if signature is valid, false otherwise

verifyTextSignature

▸ verifyTextSignature(text, signatureBase64, publicKey): Promise<boolean>

Verify a base64-encoded signature for text

Convenience wrapper that decodes base64 signature and encodes text to UTF-8.

Parameters

| 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

Promise<boolean>

True if signature is valid, false otherwise

xorBytes

▸ xorBytes(a, b): Uint8Array

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 | Description | | :------ | :------ | :------ | | a | Uint8Array | First byte array | | b | Uint8Array | Second byte array |

Returns

Uint8Array

XOR result