createSecretVaultWithNewPasskey

Creates a passkey and encrypts one secret into a vault. Runs one navigator.credentials.create() ceremony and may run a fallback navigator.credentials.get() ceremony, so it shows one or two user-verification prompts.

Import

import { createSecretVaultWithNewPasskey } from "@category-labs/mera";

Usage

const secret = new TextEncoder().encode("the secret to protect");
try {
  const vault = await createSecretVaultWithNewPasskey({
    rp: { id: "account.example.com", name: "Example" },
    user: { name: "account@example.com", displayName: "Example account" },
    secret,
  });
  localStorage.setItem("vault", JSON.stringify(vault));
} finally {
  secret.fill(0);
}

Parameters

options is a CreateSecretVaultWithNewPasskeyOptions.

options.rp

Type: PublicKeyCredentialRpEntity & { id: string }
Required, including rp.id

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

options.user

Type: { id?: Uint8Array; name: string; displayName: string }
Required

User identity passed to WebAuthn. id must be 1 to 64 bytes when provided. A fresh random 32-byte user handle is generated when it is omitted.

options.secret

Type: Uint8Array
Required

Secret bytes to encrypt. Any non-empty length.

options.timeout

Type: number
Optional; browser defaults apply when omitted

WebAuthn timeout in milliseconds, applied to each ceremony.

Returns

Promise<PasskeySecretVault>: a JSON-safe vault with 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, or the provided user.id length is outside 1 to 64 bytes.
CRYPTO_UNAVAILABLE: the page is not in a secure context, or the runtime lacks Web Crypto.
PASSKEY_OPERATION_FAILED: WebAuthn is unavailable, cancelled, or returns an unexpected credential.

Notes

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