decryptSecretVaultWithPasskey

Performs the passkey assertion for a parsed vault and decrypts its secret. Runs one assertion ceremony.

Import

import { 
function decryptSecretVaultWithPasskey({ vault, ...passkeyOptions }: DecryptSecretVaultWithPasskeyOptions): Promise<Uint8Array<ArrayBuffer>>
Performs the passkey assertion for a vault and decrypts its secret.
@param ― options - Relying party ID and vault.
@returns ― The decrypted secret bytes in a fresh allocation.
@remarks ― Runs one assertion ceremony and shows one user-verification prompt. The
assertion is restricted to the credential stored in the vault.
@throws ― MeraError with code VAULT_FORMAT_INVALID when the vault's required structure, version, or encoded data is invalid.
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not return a usable 32-byte PRF output.
@throws ― MeraError with code DECRYPT_FAILED when AES-GCM authentication fails.
@throws ― MeraError with code CRYPTO_UNAVAILABLE when crypto.getRandomValues or crypto.subtle is unavailable, or crypto.subtle lacks the HKDF or AES-GCM support the vault needs.
@throws ― MeraError with code PASSKEY_CANCELLED when the person dismisses the prompt, it times out, or no passkey answers.
@throws ― MeraError with code PASSKEY_OPERATION_FAILED when WebAuthn is unavailable, fails for another reason, or returns an unexpected credential.
decryptSecretVaultWithPasskey } from "@category-labs/mera";

Usage

import {
  
function decryptSecretVaultWithPasskey({ vault, ...passkeyOptions }: DecryptSecretVaultWithPasskeyOptions): Promise<Uint8Array<ArrayBuffer>>
Performs the passkey assertion for a vault and decrypts its secret.
@param ― options - Relying party ID and vault.
@returns ― The decrypted secret bytes in a fresh allocation.
@remarks ― Runs one assertion ceremony and shows one user-verification prompt. The
assertion is restricted to the credential stored in the vault.
@throws ― MeraError with code VAULT_FORMAT_INVALID when the vault's required structure, version, or encoded data is invalid.
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not return a usable 32-byte PRF output.
@throws ― MeraError with code DECRYPT_FAILED when AES-GCM authentication fails.
@throws ― MeraError with code CRYPTO_UNAVAILABLE when crypto.getRandomValues or crypto.subtle is unavailable, or crypto.subtle lacks the HKDF or AES-GCM support the vault needs.
@throws ― MeraError with code PASSKEY_CANCELLED when the person dismisses the prompt, it times out, or no passkey answers.
@throws ― MeraError with code PASSKEY_OPERATION_FAILED when WebAuthn is unavailable, fails for another reason, or returns an unexpected credential.
decryptSecretVaultWithPasskey,
  
function parseSecretVault(value: unknown): PasskeySecretVault
Parses and validates untrusted secret-vault JSON or objects.
Only version 1 vaults are accepted. The credential ID, PRF salt, nonce, and
ciphertext are validated as canonical base64url and length-checked. Unknown
fields are dropped from the returned vault.
@param ― value - Secret vault as JSON text or an untrusted object.
@returns ― A validated secret vault.
@throws ― MeraError with code VAULT_FORMAT_INVALID when required structure, version, or encoded data is invalid.
parseSecretVault,
} from "@category-labs/mera";

const 
const vault: PasskeySecretVault
vault = 
function parseSecretVault(value: unknown): PasskeySecretVault
Parses and validates untrusted secret-vault JSON or objects.
Only version 1 vaults are accepted. The credential ID, PRF salt, nonce, and
ciphertext are validated as canonical base64url and length-checked. Unknown
fields are dropped from the returned vault.
@param ― value - Secret vault as JSON text or an untrusted object.
@returns ― A validated secret vault.
@throws ― MeraError with code VAULT_FORMAT_INVALID when required structure, version, or encoded data is invalid.
parseSecretVault(
var localStorage: Storage
MDN Reference
localStorage.
Storage.getItem(key: string): string | null
The getItem() method of the Storage interface, when passed a key name, will return that key's value, or null if the key does not exist, in the given Storage object.
MDN Reference
getItem("vault"));
const 
const secret: Uint8Array<ArrayBuffer>
secret = await 
function decryptSecretVaultWithPasskey({ vault, ...passkeyOptions }: DecryptSecretVaultWithPasskeyOptions): Promise<Uint8Array<ArrayBuffer>>
Performs the passkey assertion for a vault and decrypts its secret.
@param ― options - Relying party ID and vault.
@returns ― The decrypted secret bytes in a fresh allocation.
@remarks ― Runs one assertion ceremony and shows one user-verification prompt. The
assertion is restricted to the credential stored in the vault.
@throws ― MeraError with code VAULT_FORMAT_INVALID when the vault's required structure, version, or encoded data is invalid.
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not return a usable 32-byte PRF output.
@throws ― MeraError with code DECRYPT_FAILED when AES-GCM authentication fails.
@throws ― MeraError with code CRYPTO_UNAVAILABLE when crypto.getRandomValues or crypto.subtle is unavailable, or crypto.subtle lacks the HKDF or AES-GCM support the vault needs.
@throws ― MeraError with code PASSKEY_CANCELLED when the person dismisses the prompt, it times out, or no passkey answers.
@throws ― MeraError with code PASSKEY_OPERATION_FAILED when WebAuthn is unavailable, fails for another reason, or returns an unexpected credential.
decryptSecretVaultWithPasskey({
  
rpId: string
Relying party ID for the WebAuthn assertion.
rpId: "account.example.com",
  
vault: PasskeySecretVault
Secret vault to decrypt.
vault,
});
try {
  // use the secret bytes
} finally {
  
const secret: Uint8Array<ArrayBuffer>
secret.
Uint8Array<ArrayBuffer>.fill(value: number, start?: number, end?: number): Uint8Array<ArrayBuffer>
Changes all array elements from start to end index to a static value and returns the modified array
@param ― value value to fill array section with
@param ― start index to start filling the array at. If start is negative, it is treated as
length+start where length is the length of the array.
@param ― end index to stop filling the array at. If end is negative, it is treated as
length+end.
fill(0);
}

Parameters

options.rpId

Type: string
Required

Relying party ID for the WebAuthn assertion. It must match the ID under which the vault’s passkey was created.

options.vault

Type: PasskeySecretVault
Required

A parsed secret vault; parseSecretVault produces one from untrusted stored data. The assertion is restricted to the credential stored in the vault.

options.timeout

Type: number
Optional; platform defaults apply when omitted

WebAuthn timeout in milliseconds.

options.webAuthnClient

Type: WebAuthnClient
Optional; defaults to the built-in browser client

Client that runs the ceremony. WebAuthnClient covers supplying one for a runtime without navigator.credentials.

Returns

type 
type ReturnType = Promise<Uint8Array<ArrayBuffer>>
ReturnType = 
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
interface Uint8Array<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike>
A typed array of 8-bit unsigned integer values. The contents are initialized to 0. If the
requested number of bytes could not be allocated an exception is raised.
Uint8Array<
interface ArrayBuffer
Represents a raw buffer of binary data, which is used to store data for the
different typed arrays. ArrayBuffers cannot be read from or written to directly,
but can be passed to a typed array or DataView Object to interpret the raw
buffer as needed.
ArrayBuffer>>;

The decrypted secret bytes as a fresh allocation.

Errors

VAULT_FORMAT_INVALID
PRF_UNAVAILABLE: the authenticator did not return a usable 32-byte PRF output.
DECRYPT_FAILED
CRYPTO_UNAVAILABLE: the runtime provides no crypto.getRandomValues or crypto.subtle, or its crypto.subtle lacks the HKDF or AES-GCM support the vault needs.
PASSKEY_CANCELLED
PASSKEY_OPERATION_FAILED

Notes

The WebAuthn challenge is generated internally.