@consealdev/conseal 0.0.0-stage → 0.5.2

package/README.md

@@ -1,3 +1,193 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/consealdev/conseal/main/docs/assets/logo-dark.svg">
+    <img src="https://raw.githubusercontent.com/consealdev/conseal/main/docs/assets/logo-light.svg" style="width: 4rem; height: 4rem;" alt="Conseal logo">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">Conseal</h1>
+
+<p align="center">
+  Zero-knowledge cryptography and private communication.
+</p>
+
+---
+
+## Install
+
+```bash
+npm install @consealdev/conseal
+```
+
+## Quick start
+
+```ts
+import { seal, unseal, generateAesKey } from '@consealdev/conseal'
+
+// Generate a key and encrypt
+const key = await generateAesKey()
+const plaintext = await file.arrayBuffer()
+const { ciphertext, iv } = await seal(key, plaintext)
+
+// Decrypt
+const result = await unseal(key, ciphertext, iv)
+```
+
+## API
+
+### Symmetric encryption (AES-256-GCM)
+
+| Function | Description |
+|---|---|
+| `seal(key, plaintext, additionalData?)` | Encrypts with a random 96-bit IV. Returns `{ ciphertext, iv }`. |
+| `unseal(key, ciphertext, iv, additionalData?)` | Decrypts. Throws on tampered data or AAD mismatch. |
+| `generateAesKey(extractable?)` | Generates a random AES-256 key. |
+| `importAesKey(raw, extractable?)` | Imports raw key bytes as a CryptoKey. |
+
+### Passphrase key wrapping (PBKDF2 + AES-KW)
+
+| Function | Description |
+|---|---|
+| `wrapKey(passphrase, key)` | Wraps a CryptoKey with a passphrase. Returns `{ wrappedKey, salt }`. |
+| `unwrapKey(passphrase, wrappedKey, salt)` | Unwraps. Throws on wrong passphrase. |
+| `rekey(oldPass, newPass, wrappedKey, salt)` | Changes passphrase without re-encrypting data. |
+
+### Asymmetric encryption (ECDH P-256)
+
+| Function | Description |
+|---|---|
+| `sealMessage(recipientPublicKey, plaintext)` | Encrypts for a recipient using ephemeral ECDH. |
+| `unsealMessage(privateKey, ciphertext, iv, ephemeralPublicKey)` | Decrypts with the recipient's private key. |
+| `generateECDHKeyPair()` | Generates a P-256 ECDH key pair. |
+
+### Digital signatures (ECDSA P-256)
+
+| Function | Description |
+|---|---|
+| `sign(privateKey, data)` | Signs data with ECDSA-SHA256. |
+| `verify(publicKey, signature, data)` | Verifies a signature. Returns `true` or `false`. |
+| `generateECDSAKeyPair()` | Generates a P-256 ECDSA key pair. |
+
+### Envelope encryption (passcode-protected)
+
+| Function | Description |
+|---|---|
+| `sealEnvelope(plaintext, passcode)` | Encrypts for a recipient without a Conseal account. |
+| `unsealEnvelope(envelope, passcode)` | Decrypts with the passcode. |
+| `encodeEnvelope(envelope)` | Serialises a `SealedEnvelope` to JSON. |
+| `decodeEnvelope(json)` | Deserialises JSON back to a `SealedEnvelope`. |
+
+### Multi-device private communication (Circle)
+
+Establishes a bounded group of trusted devices that all hold the same Account Encryption Key (AEK). The mnemonic is the root of trust — the AEK is always derived from it, so any device can recover the AEK from the mnemonic alone if the passphrase or wrapped key is lost.
+
+Account creation flow:
+
+```ts
+const mnemonic = generateMnemonic()          // show to user — write it down, never store it
+const { wrappedAEK, aekCommitment, deviceId } = await initCircle(mnemonic, passphrase, secretKey)
+// store wrappedAEK + aekCommitment server-side
+```
+
+Recovery flow (lost passphrase or wrapped key):
+
+```ts
+const aek = await recoverWithMnemonic(mnemonic, true)  // re-derive AEK from mnemonic
+const { wrappedKey, salt } = await wrapKey(newPassphrase, aek, newSecretKey)
+// upload new wrappedKey to server
+```
+
+Four functions cover the full device-registration ceremony:
+
+| Function | Description |
+|---|---|
+| `initCircle(mnemonic, passphrase, secretKey)` | Founding device derives the shared AEK from the mnemonic, wraps it, and returns `wrappedAEK`, `aekCommitment`, and `deviceId`. |
+| `createJoinRequest(deviceMeta?)` | New device generates an ephemeral ECDH key pair. Returns the join request payload, the ephemeral private key (memory-only), and a `verificationCode` to display to the user. |
+| `authorizeJoin(joinRequest, wrappedAEK, passphrase, secretKey)` | Trusted device unwraps its AEK and seals it for the new device via ECDH. Rejects requests older than 5 minutes. |
+| `finalizeJoin(sealedAEK, ephemeralPrivateKey, passphrase, secretKey, aekCommitment)` | New device unseals the AEK, verifies the commitment, and re-wraps it under its own credentials. Throws on commitment mismatch. |
+| `deriveVerificationCode(ephemeralPublicKey)` | Derives a `XX-XX-XX` hex code from a public key. Both devices must show matching codes before approval to prevent MITM. |
+
+### Device initialisation
+
+| Function | Description |
+|---|---|
+| `init(wrappedKey, salt, passphrase)` | Unwraps the AEK and stores it in IndexedDB. |
+| `AEK_KEY_ID` | The IndexedDB key id for the AEK (`'aek'`). |
+
+### Mnemonic recovery (BIP-39)
+
+| Function | Description |
+|---|---|
+| `generateMnemonic()` | Generates a 24-word recovery phrase (256 bits of entropy). |
+| `recoverWithMnemonic(mnemonic, extractable?)` | Derives the AEK from the mnemonic. Pass `extractable: true` when passing to `initCircle` or `wrapKey`. |
+
+### Key serialisation (JWK)
+
+| Function | Description |
+|---|---|
+| `exportPublicKeyAsJwk(key)` | Exports a public CryptoKey to JWK. |
+| `importPublicKeyFromJwk(jwk, algorithm)` | Imports a JWK as a CryptoKey (`'ECDH'` or `'ECDSA'`). |
+
+### IndexedDB key storage
+
+```ts
+import { saveCryptoKey, loadCryptoKey, deleteCryptoKey } from '@consealdev/conseal'
+```
+
+| Function | Description |
+|---|---|
+| `saveCryptoKey(name, key)` | Persists a CryptoKey to IndexedDB. |
+| `loadCryptoKey(name)` | Loads a CryptoKey. Returns `null` if not found. |
+| `deleteCryptoKey(name)` | Deletes a CryptoKey. |
+
+### Utilities
+
+| Function | Description |
+|---|---|
+| `toBase64(buf)` / `fromBase64(b64)` | Standard base64 encoding/decoding. |
+| `toBase64Url(buf)` / `fromBase64Url(b64)` | URL-safe base64 (no padding). |
+| `digest(data)` | SHA-256 hash. |
+
+## Design
+
+- **Zero runtime secrets on the server.** All encryption and decryption happens in the browser. The server stores only wrapped keys and ciphertext.
+- **SubtleCrypto everywhere.** No OpenSSL, no polyfills, no WASM. The only runtime dependency is [`@scure/bip39`](https://github.com/nicolo-ribaudo/noble-bip39) for mnemonic wordlists (bundled into the output).
+- **Non-extractable keys.** Keys stored in IndexedDB have `extractable: false` — JavaScript cannot read the raw bytes, only use them for encrypt/decrypt.
+- **PBKDF2 at 600,000 iterations.** Passphrase-derived keys use SHA-256 with a 128-bit random salt per wrap. Intentionally slow to resist offline brute-force.
+
+## Requirements
+
+- Browser with [SubtleCrypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) support (all modern browsers)
+- Node.js >= 18 (for testing / SSR with `globalThis.crypto`)
+
+## Development
+
+```bash
+npm install
+npm test           # unit tests (Vitest + happy-dom)
+npm run build      # build to dist/
+```
+
+### Cross-browser tests
+
+SubtleCrypto behaviour is not identical across engines. The browser suite runs the full test suite in real Chromium, Firefox, and WebKit engines via Playwright.
+
+First-time setup — download browser binaries (~300 MB, one-off):
+
+```bash
+npx playwright install
+```
+
+Then run:
+
+```bash
+npm run test:browser
+```
+
+WebKit is the highest-value target: every browser on iOS uses WebKit under the hood regardless of brand, so this provides real Safari/iOS coverage without a device.
+
+Both suites run automatically on CI for every push and pull request to `main`.
+
+## License
+
+Dual-licensed under [AGPL-3.0](LICENSE) and a [commercial license](COMMERCIAL-LICENSE.md).

package/dist/index.d.ts

@@ -0,0 +1,347 @@
+/** Result of a seal() call — ciphertext with auth tag appended, and the IV used. */
+type SealedData = {
+    ciphertext: ArrayBuffer;
+    iv: Uint8Array;
+};
+/** Encrypts plaintext with AES-256-GCM. Returns ciphertext (with auth tag appended) and IV. */
+declare function seal(key: CryptoKey, plaintext: ArrayBuffer, additionalData?: ArrayBuffer | Uint8Array): Promise<SealedData>;
+/** Decrypts AES-256-GCM ciphertext. Throws if the auth tag check fails. */
+declare function unseal(key: CryptoKey, ciphertext: ArrayBuffer, iv: Uint8Array, additionalData?: ArrayBuffer | Uint8Array): Promise<ArrayBuffer>;
+/**
+ * Generates a random AES-256-GCM CryptoKey.
+ * Pass extractable: true when the key must be wrapped before storage (e.g. via wrapKey).
+ */
+declare function generateAesKey(extractable?: boolean): Promise<CryptoKey>;
+/**
+ * Imports raw key bytes as an AES-256-GCM CryptoKey.
+ * Pass extractable: true when the key must be wrapped before storage (e.g. via wrapKey).
+ */
+declare function importAesKey(raw: ArrayBuffer | Uint8Array, extractable?: boolean): Promise<CryptoKey>;
+
+/** Wraps a CryptoKey with a passphrase (and optional Secret Key). The input key must have extractable: true. */
+declare function wrapKey(passphrase: string, key: CryptoKey, secretKey?: Uint8Array): Promise<{
+    wrappedKey: ArrayBuffer;
+    salt: Uint8Array;
+}>;
+/**
+ * Unwraps a CryptoKey. Returns extractable: false by default.
+ * Pass extractable: true only when the raw key bytes are needed for transfer
+ * (e.g. circle join ceremony) — export and discard as quickly as possible.
+ */
+declare function unwrapKey(passphrase: string, wrappedKey: ArrayBuffer, salt: Uint8Array, secretKey?: Uint8Array, extractable?: boolean): Promise<CryptoKey>;
+/**
+ * Changes the passphrase protecting the AEK without re-encrypting any content.
+ * The Secret Key (if any) stays the same — it is used on both the unwrap and re-wrap sides.
+ */
+declare function rekey(oldPassphrase: string, newPassphrase: string, wrappedKey: ArrayBuffer, salt: Uint8Array, secretKey?: Uint8Array): Promise<{
+    wrappedKey: ArrayBuffer;
+    salt: Uint8Array;
+}>;
+/**
+ * Rotates the Secret Key while keeping the passphrase the same.
+ * Use only when the Secret Key is compromised — this is a rare, heavyweight operation.
+ * Unwraps with passphrase + oldSecretKey, re-wraps with passphrase + newSecretKey.
+ *
+ * @param passphrase  - the passphrase (unchanged)
+ * @param oldSecretKey - the current Secret Key (used to unwrap)
+ * @param newSecretKey - the replacement Secret Key (used to re-wrap)
+ * @param wrappedKey   - the currently wrapped AEK
+ * @param salt         - the salt used when the AEK was wrapped
+ */
+declare function rekeySecretKey(passphrase: string, oldSecretKey: Uint8Array, newSecretKey: Uint8Array, wrappedKey: ArrayBuffer, salt: Uint8Array): Promise<{
+    wrappedKey: ArrayBuffer;
+    salt: Uint8Array;
+}>;
+
+/**
+ * 128-bit Secret Key — second factor for AEK wrapping.
+ *
+ * generateSecretKey()              generates a random 128-bit secret key. Call once
+ *                                  at account setup and store device-side (localStorage)
+ *                                  plus an offline copy for recovery.
+ *
+ * combinePassphraseAndSecretKey()  HMAC-SHA-256(key=secretKey, msg=passphrase),
+ *                                  hex-encoded. The secretKey is used as the HMAC key
+ *                                  and the passphrase as the message, which is the
+ *                                  standard construction for combining two inputs.
+ *                                  Neither factor is recoverable from the result.
+ *                                  The output is fed into PBKDF2 as the password.
+ */
+/** Generates a random 128-bit (16-byte) secret key. */
+declare function generateSecretKey(): Uint8Array;
+/**
+ * Combines a passphrase and secret key into a single opaque string for PBKDF2.
+ * HMAC-SHA-256(key=secretKey, msg=passphrase), hex-encoded.
+ *
+ * Using HMAC with the secretKey as the key is the standard construction for
+ * combining two inputs — it avoids length-extension concerns and provides
+ * cryptographic binding of both factors.
+ */
+declare function combinePassphraseAndSecretKey(passphrase: string, secretKey: Uint8Array): Promise<string>;
+
+/** Generates a long-term ECDH P-256 key pair for an account identity. */
+declare function generateECDHKeyPair(): Promise<CryptoKeyPair>;
+/** Encrypts plaintext for a recipient. Only the recipient's private key can decrypt. */
+declare function sealMessage(recipientPublicKey: CryptoKey, plaintext: ArrayBuffer): Promise<{
+    ciphertext: ArrayBuffer;
+    iv: Uint8Array;
+    ephemeralPublicKey: JsonWebKey;
+}>;
+/** Decrypts a message sealed with the recipient's public key. */
+declare function unsealMessage(recipientPrivateKey: CryptoKey, ciphertext: ArrayBuffer, iv: Uint8Array, ephemeralPublicKey: JsonWebKey): Promise<ArrayBuffer>;
+
+/**
+ * ECDSA P-256 signing for sender verification.
+ *
+ * Provides cryptographic proof that a file or message came from the claimed sender.
+ * The sender signs with their private key; any recipient who has the sender's public
+ * key can verify the signature.
+ *
+ * sign()   produces a raw ECDSA signature over arbitrary data.
+ * verify() checks a signature against data using the signer's public key.
+ *          Returns true if valid, false if not — never throws on invalid signatures.
+ *
+ * Hash: SHA-256.
+ */
+/** Generates a long-term ECDSA P-256 key pair for an account identity. */
+declare function generateECDSAKeyPair(): Promise<CryptoKeyPair>;
+/** Signs data with the sender's ECDSA private key. */
+declare function sign(privateKey: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;
+/** Verifies a signature against data using the sender's ECDSA public key. */
+declare function verify(publicKey: CryptoKey, signature: ArrayBuffer, data: ArrayBuffer): Promise<boolean>;
+
+/**
+ * JWK serialisation for public keys.
+ *
+ * exportPublicKeyAsJwk() serialises a CryptoKey to a JSON Web Key — used when
+ * registering a public key with the Conseal identity registry.
+ *
+ * importPublicKeyFromJwk() deserialises a JWK back to a CryptoKey — used when
+ * loading a recipient's public key before encrypting a message.
+ *
+ * Only public keys are exported. Private keys are never extracted.
+ */
+/** Serialises a public CryptoKey to a JSON Web Key object. */
+declare function exportPublicKeyAsJwk(key: CryptoKey): Promise<JsonWebKey>;
+/** Deserialises a JSON Web Key to a CryptoKey for the given algorithm. */
+declare function importPublicKeyFromJwk(jwk: JsonWebKey, algorithm: 'ECDH' | 'ECDSA'): Promise<CryptoKey>;
+
+/** The IndexedDB key id under which the Account Encryption Key is stored after init(). */
+declare const AEK_KEY_ID = "aek";
+/** Persists a CryptoKey to IndexedDB under the given name. Overwrites if name exists. */
+declare function saveCryptoKey(name: string, key: CryptoKey): Promise<void>;
+/** Loads a CryptoKey from IndexedDB. Returns null if the name is not found. */
+declare function loadCryptoKey(name: string): Promise<CryptoKey | null>;
+/** Removes a CryptoKey from IndexedDB. No-op if the name does not exist. */
+declare function deleteCryptoKey(name: string): Promise<void>;
+
+/**
+ * Unwraps the AEK with the given passphrase (and optional Secret Key) and
+ * stores it in IndexedDB. After this completes, the AEK is available via
+ * load(AEK_KEY_ID).
+ */
+declare function init(wrappedKey: ArrayBuffer, salt: Uint8Array, passphrase: string, secretKey?: Uint8Array): Promise<void>;
+
+/** Generates a fresh 24-word BIP-39 mnemonic (256 bits of entropy). */
+declare function generateMnemonic(): string;
+/**
+ * Derives a deterministic AES-256-GCM CryptoKey from a BIP-39 mnemonic.
+ * Throws if the mnemonic is invalid or not in the BIP-39 word list.
+ *
+ * The mnemonic's 32-byte entropy is passed through HKDF-SHA-256 with a
+ * domain-separation label before being imported as key material. This adds
+ * defense-in-depth: if the mnemonic came from a tool with weaker entropy, HKDF
+ * still produces a well-distributed key; it also ensures key-domain separation
+ * if the same entropy is ever used for another purpose.
+ *
+ * Pass extractable: true when the key must be wrapped before storage —
+ * e.g. when passing it to initCircle().
+ */
+declare function recoverWithMnemonic(mnemonic: string, extractable?: boolean): Promise<CryptoKey>;
+
+/** Encrypts plaintext and wraps the key with a passcode, returning a SealedEnvelope. */
+declare function sealEnvelope(plaintext: ArrayBuffer, passcode: string): Promise<SealedEnvelope>;
+/** Decrypts a SealedEnvelope using the passcode. Throws if the passcode is wrong. */
+declare function unsealEnvelope(envelope: SealedEnvelope, passcode: string): Promise<ArrayBuffer>;
+/**
+ * The in-memory representation produced by sealEnvelope().
+ *
+ * **Not directly JSON-serialisable.** ArrayBuffer and Uint8Array fields are
+ * silently lost or corrupted by JSON.stringify. Use encodeEnvelope() to produce
+ * a JSON string and decodeEnvelope() to reconstruct this type from one.
+ */
+interface SealedEnvelope {
+    /** Format version — always 1 for envelopes produced by this library. */
+    version: 1;
+    ciphertext: ArrayBuffer;
+    iv: Uint8Array;
+    wrappedKey: ArrayBuffer;
+    salt: Uint8Array;
+}
+/**
+ * Serialises a SealedEnvelope to a JSON string.
+ * Each binary field is base64-encoded. Safe to store server-side or pass over text channels.
+ */
+declare function encodeEnvelope(envelope: SealedEnvelope): string;
+/**
+ * Deserialises a JSON string produced by encodeEnvelope() back to a SealedEnvelope.
+ * Throws SyntaxError if the string is not valid JSON.
+ * Throws TypeError if required fields are missing, the wrong type, or the version is unsupported.
+ */
+declare function decodeEnvelope(json: string): SealedEnvelope;
+
+/**
+ * Base64 encoding and decoding utilities.
+ *
+ * Helper functions for converting between binary data (ArrayBuffer / Uint8Array)
+ * and standard base64 strings — used when serialising encrypted payloads for
+ * storage or transmission over text-based channels.
+ *
+ * Two variants are provided:
+ *   toBase64 / fromBase64       — standard base64 (uses +, /, = padding)
+ *   toBase64Url / fromBase64Url — base64url (uses -, _, no padding; safe in URLs and JWKs)
+ */
+/**
+ * Encodes an ArrayBuffer or Uint8Array to a standard base64 string.
+ * Uses a loop instead of spread to avoid stack overflow on large buffers.
+ */
+declare function toBase64(buf: ArrayBuffer | Uint8Array): string;
+/** Decodes a standard base64 string to a Uint8Array. */
+declare function fromBase64(b64: string): Uint8Array;
+/**
+ * Encodes an ArrayBuffer or Uint8Array to a base64url string.
+ * Replaces + with -, / with _, and strips = padding.
+ * Used for JWK coordinates and URL-safe contexts.
+ */
+declare function toBase64Url(buf: ArrayBuffer | Uint8Array): string;
+/** Decodes a base64url string to a Uint8Array. */
+declare function fromBase64Url(b64url: string): Uint8Array;
+
+/**
+ * SHA-256 digest.
+ *
+ * Thin wrapper around SubtleCrypto.digest for the hash function used throughout
+ * this library — key fingerprinting, content hashing, and integrity checks.
+ */
+/** Returns the SHA-256 hash of the input data as an ArrayBuffer. */
+declare function digest(data: ArrayBuffer | Uint8Array): Promise<ArrayBuffer>;
+
+/** Wrapped AEK — opaque blob stored server-side per device. */
+interface WrappedAEK {
+    wrappedKey: ArrayBuffer;
+    salt: Uint8Array;
+}
+/** Serializable join request payload sent by a new device to the backend. */
+interface JoinRequest {
+    deviceId: string;
+    ephemeralPublicKey: JsonWebKey;
+    /**
+     * ISO 8601 timestamp set by the joining device. `authorizeJoin` uses this to
+     * reject stale requests, but the check is only as trustworthy as the device
+     * that set the value. Callers should independently validate request freshness
+     * server-side (e.g. record when the backend first received the request and
+     * reject if that server-stamped age exceeds the TTL).
+     */
+    createdAt: string;
+    deviceMeta?: {
+        name?: string;
+        platform?: string;
+    };
+}
+/** AEK sealed for a specific device's ephemeral public key via ECDH. */
+interface SealedAEK {
+    ciphertext: ArrayBuffer;
+    iv: Uint8Array;
+    ephemeralPublicKey: JsonWebKey;
+}
+/**
+ * Derives a human-readable verification code from an ECDH public key JWK.
+ *
+ * Exports the key as its uncompressed point bytes (65 bytes for P-256),
+ * SHA-256 hashes them, and formats the first 4 bytes as uppercase hex pairs
+ * separated by dashes: e.g. "A3-4F-9C-12" (32 bits / ~4 billion possible codes).
+ *
+ * Both the new device (createJoinRequest) and the authorizing device
+ * (authorizeJoin) call this with the same JWK and must get the same code.
+ * The user confirms the codes match out-of-band before approval proceeds.
+ *
+ * 32-bit space makes brute-force injection of a matching fake key pair
+ * infeasible within the 5-minute TTL window.
+ */
+declare function deriveVerificationCode(ephemeralPublicKey: JsonWebKey): Promise<string>;
+/**
+ * Called once by the founding device when creating a new account.
+ *
+ * Derives the shared AEK from the mnemonic (so it can always be recovered),
+ * publishes its SHA-256 commitment (so joining devices can verify the AEK was
+ * not substituted), and wraps the AEK under the founding device's own
+ * passphrase + secretKey.
+ *
+ * The mnemonic is the root of trust — it must be shown to the user at account
+ * creation and never stored. The app stores wrappedAEK and aekCommitment on
+ * the server.
+ */
+declare function initCircle(mnemonic: string, passphrase: string, secretKey: Uint8Array): Promise<{
+    wrappedAEK: WrappedAEK;
+    aekCommitment: ArrayBuffer;
+    deviceId: string;
+}>;
+/**
+ * Called by a new device that wants to join the circle.
+ *
+ * Generates an ephemeral ECDH P-256 key pair for the one-time ceremony.
+ * The ephemeral private key is returned to the caller and must be held in
+ * memory only — never persisted — until finalizeJoin completes.
+ *
+ * The verification code is derived from the ephemeral public key and must
+ * be displayed prominently so the user can confirm it matches the code shown
+ * on the authorizing device.
+ */
+declare function createJoinRequest(deviceMeta?: {
+    name?: string;
+    platform?: string;
+}): Promise<{
+    request: JoinRequest;
+    ephemeralPrivateKey: CryptoKey;
+    verificationCode: string;
+}>;
+/**
+ * Called by a trusted device to approve a new device joining the circle.
+ *
+ * Rejects stale join requests based on `serverReceivedAt` — the Unix-ms
+ * timestamp recorded by the server when the join request first arrived.
+ * Callers MUST pass the server-stamped time, not `joinRequest.createdAt`,
+ * which is set by the joining device and can be forged.
+ *
+ * The caller must present the verification code from
+ * joinRequest.ephemeralPublicKey and require explicit user confirmation that
+ * it matches the code on the new device before calling this function —
+ * calling without confirmation bypasses the primary MITM defence.
+ *
+ * Unwraps the AEK and seals its raw bytes for the new device's ephemeral
+ * public key via ECDH. Only the ephemeral private key held by the new device
+ * can open it.
+ *
+ * @param serverReceivedAt  Unix milliseconds — when the server first received
+ *   this join request. Use `Date.now()` at receipt time on the server, NOT
+ *   `new Date(joinRequest.createdAt).getTime()`. Passing the client-supplied
+ *   timestamp defeats TTL enforcement.
+ */
+declare function authorizeJoin(joinRequest: JoinRequest, wrappedAEK: WrappedAEK, passphrase: string, secretKey: Uint8Array, serverReceivedAt: number): Promise<SealedAEK>;
+/**
+ * Called by the new device after authorization.
+ *
+ * Unseals the AEK using the ephemeral private key generated in
+ * createJoinRequest, verifies it against aekCommitment (SHA-256 of the raw
+ * AEK published by initCircle), then re-wraps it under the new device's own
+ * passphrase + secretKey. The ephemeral private key is not needed after this
+ * call and should be discarded.
+ *
+ * Throws if the commitment check fails — the AEK was substituted or tampered
+ * with in transit. Do not use the returned wrappedAEK if this throws.
+ */
+declare function finalizeJoin(sealedAEK: SealedAEK, ephemeralPrivateKey: CryptoKey, passphrase: string, secretKey: Uint8Array, aekCommitment: ArrayBuffer): Promise<{
+    wrappedAEK: WrappedAEK;
+}>;
+
+export { AEK_KEY_ID, type JoinRequest, type SealedAEK, type SealedEnvelope, type WrappedAEK, authorizeJoin, combinePassphraseAndSecretKey, createJoinRequest, decodeEnvelope, deleteCryptoKey, deriveVerificationCode, digest, encodeEnvelope, exportPublicKeyAsJwk, finalizeJoin, fromBase64, fromBase64Url, generateAesKey, generateECDHKeyPair, generateECDSAKeyPair, generateMnemonic, generateSecretKey, importAesKey, importPublicKeyFromJwk, init, initCircle, loadCryptoKey, recoverWithMnemonic, rekey, rekeySecretKey, saveCryptoKey, seal, sealEnvelope, sealMessage, sign, toBase64, toBase64Url, unseal, unsealEnvelope, unsealMessage, unwrapKey, verify, wrapKey };