createSecretVaultWithExistingPasskey

Evaluates an existing passkey and encrypts one secret into a vault. Runs one assertion ceremony.

Import

import { 
function createSecretVaultWithExistingPasskey({ credential, secret, ...passkeyOptions }: CreateSecretVaultWithExistingPasskeyOptions): Promise<PasskeySecretVault>
Evaluates an existing passkey and encrypts one secret into a vault.
@param ― options - Passkey assertion inputs and secret bytes.
@returns ― A JSON-safe secret vault containing the selected credential metadata.
@remarks ― 
Runs one assertion ceremony and shows one user-verification prompt.
A fresh random PRF salt is generated internally and stored in the returned
vault.
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not return a usable 32-byte PRF output.
@throws ― MeraError with code INPUT_INVALID when secret is empty, or credential.credentialId is empty or not canonical base64url.
@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.
createSecretVaultWithExistingPasskey } from "@category-labs/mera";

Usage

import {
  
function createSecretVaultWithExistingPasskey({ credential, secret, ...passkeyOptions }: CreateSecretVaultWithExistingPasskeyOptions): Promise<PasskeySecretVault>
Evaluates an existing passkey and encrypts one secret into a vault.
@param ― options - Passkey assertion inputs and secret bytes.
@returns ― A JSON-safe secret vault containing the selected credential metadata.
@remarks ― 
Runs one assertion ceremony and shows one user-verification prompt.
A fresh random PRF salt is generated internally and stored in the returned
vault.
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not return a usable 32-byte PRF output.
@throws ― MeraError with code INPUT_INVALID when secret is empty, or credential.credentialId is empty or not canonical base64url.
@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.
createSecretVaultWithExistingPasskey,
  
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 existing: PasskeySecretVault
existing = 
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 = new 
var TextEncoder: new () => TextEncoder
The TextEncoder interface takes a stream of code points as input and emits a stream of UTF-8 bytes.
MDN Reference
TextEncoder class is a global reference for import { TextEncoder } from 'node:util'
https://nodejs.org/api/globals.html#textencoder
@since ― v11.0.0
TextEncoder().
TextEncoder.encode(input?: string): Uint8Array<ArrayBuffer>
The TextEncoder.encode() method takes a string as input, and returns a Global_Objects/Uint8Array containing the text given in parameters encoded with the specific method for that TextEncoder object.
MDN Reference
encode("another secret");
try {
  const 
const vault: PasskeySecretVault
vault = await 
function createSecretVaultWithExistingPasskey({ credential, secret, ...passkeyOptions }: CreateSecretVaultWithExistingPasskeyOptions): Promise<PasskeySecretVault>
Evaluates an existing passkey and encrypts one secret into a vault.
@param ― options - Passkey assertion inputs and secret bytes.
@returns ― A JSON-safe secret vault containing the selected credential metadata.
@remarks ― 
Runs one assertion ceremony and shows one user-verification prompt.
A fresh random PRF salt is generated internally and stored in the returned
vault.
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not return a usable 32-byte PRF output.
@throws ― MeraError with code INPUT_INVALID when secret is empty, or credential.credentialId is empty or not canonical base64url.
@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.
createSecretVaultWithExistingPasskey({
    
rpId: string
Relying party ID for the WebAuthn assertion.
rpId: "account.example.com",
    
credential?: PasskeyCredentialMetadata | undefined
Credential metadata to restrict the assertion to one passkey. When
omitted, WebAuthn may choose any discoverable credential for the relying
party.
credential: 
const existing: PasskeySecretVault
existing.
credential: PasskeyCredentialMetadata
Passkey credential that unlocks this secret.
credential,
    
secret: Uint8Array<ArrayBufferLike>
Secret bytes to encrypt. Any non-empty length.
secret,
  });
  
var localStorage: Storage
MDN Reference
localStorage.
Storage.setItem(key: string, value: string): void
The setItem() method of the Storage interface, when passed a key name and value, will add that key to the given Storage object, or update that key's value if it already exists.
MDN Reference
setItem("second-vault", 
var JSON: JSON
An intrinsic object that provides functions to convert JavaScript values to and from the JavaScript Object Notation (JSON) format.
JSON.
JSON.stringify(value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string (+1 overload)
Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
@param ― value A JavaScript value, usually an object or array, to be converted.
@param ― replacer A function that transforms the results.
@param ― space Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.
@throws ― {TypeError} If a circular reference or a BigInt value is found.
stringify(
const vault: PasskeySecretVault
vault));
} 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 passkey was created.

options.credential

Type: PasskeyCredentialMetadata
Optional; when omitted, WebAuthn may choose any discoverable credential for the relying party

Credential metadata that restricts the assertion to one passkey. Reported transports are retained in the new vault when the selected credential matches.

options.secret

Type: Uint8Array
Required

Secret bytes to encrypt. Any non-empty length.

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

import type { 
type PasskeySecretVault = {
    readonly version: 1;
    readonly credential: PasskeyCredentialMetadata;
    readonly prfSalt: string;
    readonly nonce: string;
    readonly ciphertext: string;
}
Versioned JSON-safe vault holding one secret encrypted behind a passkey.
The secret bytes are opaque to the library.
PasskeySecretVault } from "@category-labs/mera";

type 
type ReturnType = Promise<PasskeySecretVault>
ReturnType = 
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
type PasskeySecretVault = {
    readonly version: 1;
    readonly credential: PasskeyCredentialMetadata;
    readonly prfSalt: string;
    readonly nonce: string;
    readonly ciphertext: string;
}
Versioned JSON-safe vault holding one secret encrypted behind a passkey.
The secret bytes are opaque to the library.
PasskeySecretVault>;

A JSON-safe vault with version, credential, prfSalt, nonce, and ciphertext. It contains the selected credential’s metadata and a fresh random 32-byte PRF salt. The secret vault format page documents every field.

Errors

PRF_UNAVAILABLE: the authenticator did not return a usable 32-byte PRF output.
INPUT_INVALID: secret is empty, or credential.credentialId is empty or not canonical base64url.
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