createSecretVaultWithNewPasskey

Creates a passkey and encrypts one secret into a vault. Runs one creation ceremony and may run a fallback assertion, so it shows one or two user-verification prompts.

Import

import { 
function createSecretVaultWithNewPasskey({ secret, ...passkeyOptions }: CreateSecretVaultWithNewPasskeyOptions): Promise<PasskeySecretVault>
Creates a passkey and encrypts one secret into a vault.
@param ― options - Passkey creation inputs and secret bytes.
@returns ― A JSON-safe secret vault containing the new credential metadata.
@remarks ― 
Runs one creation ceremony and shows one user-verification prompt. On
authenticators that do not evaluate PRF during creation, also runs an
assertion, which shows a second.
A fresh random PRF salt is generated internally and stored in the returned
vault.
A fresh random user handle (user.id) is generated for the new credential,
so each call adds a passkey instead of replacing one.
If the fallback ceremony or vault encryption fails, the passkey from the
completed creation ceremony still exists on the authenticator, but the
thrown error does not carry its metadata.
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not enable PRF or return a usable 32-byte PRF output.
@throws ― MeraError with code INPUT_INVALID when secret is empty.
@throws ― MeraError with code CRYPTO_UNAVAILABLE when crypto.getRandomValues or crypto.subtle is unavailable.
@throws ― MeraError with code PASSKEY_OPERATION_FAILED when WebAuthn is unavailable, cancelled, or returns an unexpected credential.
createSecretVaultWithNewPasskey } from "@category-labs/mera";

Usage

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("the secret to protect");
try {
  const 
const vault: PasskeySecretVault
vault = await 
function createSecretVaultWithNewPasskey({ secret, ...passkeyOptions }: CreateSecretVaultWithNewPasskeyOptions): Promise<PasskeySecretVault>
Creates a passkey and encrypts one secret into a vault.
@param ― options - Passkey creation inputs and secret bytes.
@returns ― A JSON-safe secret vault containing the new credential metadata.
@remarks ― 
Runs one creation ceremony and shows one user-verification prompt. On
authenticators that do not evaluate PRF during creation, also runs an
assertion, which shows a second.
A fresh random PRF salt is generated internally and stored in the returned
vault.
A fresh random user handle (user.id) is generated for the new credential,
so each call adds a passkey instead of replacing one.
If the fallback ceremony or vault encryption fails, the passkey from the
completed creation ceremony still exists on the authenticator, but the
thrown error does not carry its metadata.
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not enable PRF or return a usable 32-byte PRF output.
@throws ― MeraError with code INPUT_INVALID when secret is empty.
@throws ― MeraError with code CRYPTO_UNAVAILABLE when crypto.getRandomValues or crypto.subtle is unavailable.
@throws ― MeraError with code PASSKEY_OPERATION_FAILED when WebAuthn is unavailable, cancelled, or returns an unexpected credential.
createSecretVaultWithNewPasskey({
    
rp: PasskeyRelyingParty
Relying party identity passed to WebAuthn. id is required so the
fallback assertion can target the same relying party.
rp: { 
id: string
Relying party ID: the host the passkey is scoped to.
id: "account.example.com", 
name: string
Relying party name the authenticator may show.
name: "Example" },
    
user: {
    name: string;
    displayName: string;
}
User identity passed to WebAuthn.
user: { 
name: string
User name displayed or stored by the authenticator.
name: "account@example.com", 
displayName: string
Human-readable display name for the authenticator UI.
displayName: "Example account" },
    
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("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 is a CreateSecretVaultWithNewPasskeyOptions.

options.rp

Type: { id: string; name: string }
Required, including rp.id

Relying party identity passed to WebAuthn. The required ID is reused by the fallback assertion.

options.user.name

Type: string
Required

User name displayed or stored by the authenticator.

options.user.displayName

Type: string
Required

Human-readable display name for the authenticator UI.

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, applied to each ceremony.

options.webAuthnClient

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

Client that runs the ceremonies. 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 new 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 enable PRF or return a usable 32-byte output.
INPUT_INVALID: secret is empty.
CRYPTO_UNAVAILABLE: the runtime provides no crypto.getRandomValues or crypto.subtle.
PASSKEY_OPERATION_FAILED: WebAuthn is unavailable, cancelled, or returns an unexpected credential.

Notes

The credential’s user handle (user.id) is 32 random bytes, generated per call, so each call adds a passkey and never overwrites one.

If the fallback ceremony or vault encryption fails after creation, the passkey remains on the authenticator and the error does not contain its metadata.