@majikah/majik-universal-id-client 0.0.1

package/dist/majik-universal-id-client.d.ts

@@ -0,0 +1,757 @@
+/**
+ * MajikUniversalIdClient.ts
+ *
+ */
+import { MajikKey } from "@majikah/majik-key";
+import { MajikContact, type MajikContactMeta, type SerializedMajikContact } from "./core/contacts/majik-contact";
+import { MajikSignature } from "@majikah/majik-signature";
+import type { MajikSignatureJSON, MajikSignerPublicKeys, SignOptions, VerificationResult } from "@majikah/majik-signature";
+import { MajikContactDirectory, MajikContactDirectoryData } from "./core/contacts/majik-contact-directory";
+import { MAJIK_API_RESPONSE } from "./core/types";
+import { ImageSignatureStub, ImageSignOptions, ImageVerificationResult } from "@majikah/majik-signature/dist/core/stamp";
+import { CreateUniversalIDOptions, MajikUniversalID } from "@majikah/majik-universal-id";
+import { MajikUser } from "@thezelijah/majik-user";
+type MajikUniversalIdClientEvents = "create-id" | "sign" | "verify" | "unlock" | "lock" | "new-account" | "new-contact" | "removed-account" | "removed-contact" | "active-account-change" | "error";
+interface MajikUniversalIdClientStatic<T extends MajikUniversalIdClient> {
+    new (config: MajikUniversalIdClientConfig, id?: string): T;
+    fromJSON(json: MajikUniversalIdClientJSON): Promise<T>;
+}
+type EventCallback = (...args: any[]) => void;
+export interface MajikUniversalIdClientConfig {
+    /**
+     * Shared contact directory. Pass the same instance used by MajikMessage
+     * so that contacts stay in sync between both clients automatically.
+     */
+    contactDirectory?: MajikContactDirectory;
+    user?: MajikUser;
+}
+export interface SignResult {
+    signature: MajikSignature;
+    signerId: string;
+    contentHash: string;
+    timestamp: string;
+    contentType?: string;
+}
+export interface VerifyResult extends VerificationResult {
+    signerLabel?: string;
+}
+export interface MajikUniversalIdClientJSON {
+    id: string;
+    contacts: MajikContactDirectoryData;
+    ownAccounts?: {
+        accounts: SerializedMajikContact[];
+        order: string[];
+    };
+}
+export declare class MajikUniversalIdClient {
+    private userProfile;
+    private readonly _id;
+    private _contactDirectory;
+    private _ownAccounts;
+    private _ownAccountsOrder;
+    private _listeners;
+    private autosaveTimer;
+    private autosaveIntervalId;
+    private readonly autosaveIntervalMs;
+    private readonly autosaveDebounceMs;
+    private user_data;
+    constructor(config: MajikUniversalIdClientConfig);
+    get user(): MajikUser | null;
+    set user(user: MajikUser);
+    clearUser(): void;
+    get id(): string;
+    /**
+     * Generate a new BIP-39 mnemonic phrase.
+     */
+    generateMnemonic(strength?: 128 | 256): string;
+    /**
+     * Create a new account from a mnemonic and register it.
+     * The account is immediately unlocked after creation.
+     */
+    createAccount(mnemonic: string, passphrase: string, label?: string): Promise<{
+        id: string;
+        fingerprint: string;
+        backup: string;
+    }>;
+    /**
+     * Import an account from a mnemonic-encrypted backup.
+     * Fully upgrades to Argon2id + ML-KEM + signing keys in one step.
+     */
+    importAccountFromMnemonicBackup(backupBase64: string, mnemonic: string, passphrase: string, label?: string): Promise<{
+        id: string;
+        fingerprint: string;
+    }>;
+    /**
+     * Export a mnemonic-encrypted backup for an account.
+     * The account must be unlocked.
+     */
+    exportAccountMnemonicBackup(id: string, mnemonic: string): Promise<string>;
+    /**
+     * Register an already-existing MajikContact as one of this client's own
+     * accounts. Useful when bootstrapping from a persisted MajikMessage state.
+     */
+    addOwnAccount(account: MajikContact): void;
+    /**
+     * Remove an own account from the instance.
+     * Does NOT delete it from MajikKeyStore — call MajikKeyStore.deleteIdentity()
+     * separately if permanent deletion is needed.
+     */
+    removeOwnAccount(id: string): boolean;
+    getOwnAccountById(id: string): MajikContact | undefined;
+    getActiveAccount(): MajikContact | null;
+    isAccountActive(id: string): boolean;
+    setActiveAccount(id: string): boolean;
+    listOwnAccounts(): MajikContact[];
+    /**
+     * Unlock an account with its passphrase.
+     * Required before signing. Not required for verification.
+     */
+    unlockAccount(id: string, passphrase: string): Promise<void>;
+    /**
+     * Lock an account — clears signing keys from memory.
+     */
+    lockAccount(id: string): void;
+    /**
+     * Lock all loaded accounts.
+     */
+    lockAllAccounts(): void;
+    /**
+     * Check whether an account's passphrase is correct without unlocking it.
+     */
+    verifyPassphrase(id: string, passphrase: string): Promise<boolean>;
+    /**
+     * Update the passphrase for an account. Re-encrypts all keys.
+     */
+    updatePassphrase(id: string, currentPassphrase: string, newPassphrase: string): Promise<void>;
+    /**
+     * Check whether an account has signing keys (Ed25519 + ML-DSA-87).
+     * Accounts created before the signing key upgrade need to be re-imported
+     * via importAccountFromMnemonicBackup() to gain signing capability.
+     */
+    accountHasSigningKeys(id: string): boolean;
+    /**
+     * Load all accounts persisted in MajikKeyStore into this instance.
+     * Call this on startup to hydrate from IDB.
+     */
+    loadAccountsFromStore(): Promise<void>;
+    getContactByID(id: string): MajikContact | null;
+    getContactByPublicKey(publicKeyBase64: string): Promise<MajikContact | null>;
+    exportContactAsJSON(contactId: string): Promise<string | null>;
+    exportContactAsString(contactId: string): Promise<string | null>;
+    importContactFromJSON(jsonStr: string): Promise<MAJIK_API_RESPONSE>;
+    importContactFromString(base64Str: string): Promise<MAJIK_API_RESPONSE>;
+    exportContactCompressed(contact: MajikContact): Promise<string>;
+    importContactCompressed(base64Str: string): Promise<MajikContact>;
+    addContact(contact: MajikContact): void;
+    removeContact(id: string): void;
+    getContactById(id: string): MajikContact | null;
+    listContacts(includeOwnAccounts?: boolean): MajikContact[];
+    updateContactMeta(id: string, meta: Partial<MajikContactMeta>): void;
+    /**
+     * Resolve a human-readable label for a signer ID.
+     * Checks own accounts first, then the contact directory.
+     * Returns the fingerprint truncated to 16 chars if no label is found.
+     */
+    resolveSignerLabel(signerId: string): string;
+    /**
+     * Sign content with the active account.
+     *
+     * The active account must be unlocked and have signing keys.
+     * Use unlockAccount() first if needed.
+     *
+     * @param content     - Raw bytes or UTF-8 string to sign
+     * @param options     - Optional content type and timestamp override
+     * @param accountId   - Override which account signs. Defaults to active account.
+     */
+    sign(content: Uint8Array | string, options?: SignOptions, accountId?: string): Promise<SignResult>;
+    /**
+     * Sign content and immediately serialize to a base64 string.
+     * Convenience wrapper around sign() + serialize().
+     */
+    signAndSerialize(content: Uint8Array | string, options?: SignOptions, accountId?: string): Promise<string>;
+    /**
+     * Sign content and return the full JSON envelope.
+     * Convenience wrapper around sign() + toJSON().
+     */
+    signToJSON(content: Uint8Array | string, options?: SignOptions, accountId?: string): Promise<MajikSignatureJSON>;
+    /**
+     * Verify a signature against content.
+     *
+     * Public keys can be supplied directly, extracted from the envelope itself,
+     * or resolved from a known MajikKey account or contact in the directory.
+     *
+     * No private key is needed. Safe to call on locked accounts.
+     *
+     * @param content     - The original content that was signed
+     * @param signature   - MajikSignature instance, JSON object, or base64 string
+     * @param publicKeys  - Optional. If omitted, public keys are extracted from
+     *                      the envelope (self-reported — cross-check signerId
+     *                      against a trusted source for full security).
+     */
+    verify(content: Uint8Array | string, signature: MajikSignature | MajikSignatureJSON | string, publicKeys?: MajikSignerPublicKeys): VerifyResult;
+    /**
+     * Verify against a specific known MajikKey account.
+     * Automatically extracts public keys from the key client.
+     * Works on locked accounts — only public key fields are used.
+     */
+    verifyWithAccount(content: Uint8Array | string, signature: MajikSignature | MajikSignatureJSON | string, accountId: string): VerifyResult;
+    /**
+     * Verify against a contact from the directory by their ID.
+     * Useful when you have the signer's contact card stored locally.
+     */
+    verifyWithContact(content: Uint8Array | string, signature: MajikSignature | MajikSignatureJSON | string, contactId: string): Promise<VerifyResult>;
+    /**
+     * Batch verify multiple signatures against the same content.
+     * Returns one VerifyResult per signature in the same order.
+     */
+    verifyBatch(content: Uint8Array | string, signatures: Array<MajikSignature | MajikSignatureJSON | string>, publicKeys?: MajikSignerPublicKeys): VerifyResult[];
+    /**
+     * Convenience alias for signing a plain string.
+     *
+     * Identical to signContent() but accepts only strings — makes call-sites
+     * that deal exclusively with text cleaner (no Uint8Array overload noise).
+     *
+     * @example
+     *   const sig = await majik.signText("Hello world", { contentType: "text/plain" });
+     *   const b64 = sig.serialize(); // store alongside the text
+     */
+    signText(text: string, options?: {
+        contentType?: string;
+        timestamp?: string;
+        accountId?: string;
+    }): Promise<MajikSignature>;
+    /**
+     * Sign content and return both the MajikSignature instance and a portable
+     * base64-serialized string in one call.
+     *
+     * The serialized string is safe to store in a database column, embed in a
+     * JSON field, pass in an HTTP header, or encode in a QR code alongside the
+     * original content. Pass it back to verifyDetached() to verify.
+     *
+     * @example — sign a document and store the detached signature
+     *   const { serialized } = await majik.signAndDetach(docBytes, {
+     *     contentType: "application/pdf",
+     *   });
+     *   await db.insert({ doc_id, signature: serialized });
+     *
+     * @example — sign a text message
+     *   const { signature, serialized } = await majik.signAndDetach("Hello!", {
+     *     contentType: "text/plain",
+     *   });
+     */
+    signAndDetach(content: Uint8Array | string, options?: {
+        contentType?: string;
+        timestamp?: string;
+        accountId?: string;
+    }): Promise<{
+        signature: MajikSignature;
+        serialized: string;
+    }>;
+    /**
+     * Verify a plain string against a MajikSignature.
+     *
+     * Accepts the signature as a MajikSignature instance, a MajikSignatureJSON
+     * object, or a base64-serialized string — whichever form is easiest at the
+     * call-site.
+     *
+     * The signer can be identified by contact ID, raw public key base64, or a
+     * MajikKey client. If none is provided the public keys embedded in the
+     * signature envelope are used (self-reported — cross-check result.signerId
+     * against a known contact fingerprint before trusting).
+     *
+     * @example
+     *   const result = await majik.verifyText("Hello world", sig, {
+     *     contactId: "contact_abc",
+     *   });
+     *   if (result.valid) console.log("Authentic");
+     */
+    verifyText(text: string, signature: MajikSignature | MajikSignatureJSON | string, options?: {
+        contactId?: string;
+        publicKeyBase64?: string;
+        key?: MajikKey;
+        expectedSignerId?: string;
+    }): Promise<VerificationResult>;
+    /**
+     * Verify content against a base64-serialized detached signature string.
+     *
+     * This is the pair to signAndDetach() — designed for call-sites that retrieve
+     * a stored base64 signature from a database or API and want to verify without
+     * importing MajikSignature themselves.
+     *
+     * The signer can be identified by contact ID, raw public key base64, or a
+     * MajikKey. If none is provided, self-reported keys from the envelope are used
+     * (see security note on verifyContent).
+     *
+     * @example
+     *   const row = await db.findOne({ doc_id });
+     *   const result = await majik.verifyDetached(docBytes, row.signature, {
+     *     contactId: row.signer_contact_id,
+     *   });
+     *   if (result.valid) console.log("Signed by", result.signerId);
+     */
+    verifyDetached(content: Uint8Array | string, serializedSignature: string, options?: {
+        contactId?: string;
+        publicKeyBase64?: string;
+        key?: MajikKey;
+        expectedSignerId?: string;
+    }): Promise<VerificationResult>;
+    /**
+     * Deserialize a base64 signature string into a MajikSignature client.
+     *
+     * Round-trip partner for MajikSignature.serialize() / sig.toString().
+     * Use when you have a stored base64 string and need to inspect or pass
+     * the instance to another method.
+     *
+     * Throws MajikSignatureSerializationError on malformed input.
+     *
+     * @example
+     *   const sig = majik.deserializeSignature(storedBase64);
+     *   console.log(sig.signerId, sig.timestamp);
+     */
+    deserializeSignature(serialized: string): MajikSignature;
+    /**
+     * Extract lightweight metadata from a base64 or JSON signature string
+     * without performing cryptographic verification.
+     *
+     * Useful for displaying "Signed by X at Y" in a UI before the user
+     * explicitly triggers a verification step.
+     *
+     * Returns null if the string cannot be parsed as a MajikSignature.
+     *
+     * @example
+     *   const meta = majik.getSignatureMetadata(storedSig);
+     *   if (meta) {
+     *     const contact = majik.getContactByID(meta.signerId);
+     *     console.log(`Signed by ${contact?.meta?.label ?? meta.signerId} at ${meta.timestamp}`);
+     *   }
+     */
+    getSignatureMetadata(serialized: string): {
+        signerId: string;
+        timestamp: string;
+        contentType: string | undefined;
+        contentHash: string;
+        version: number;
+    } | null;
+    /**
+     * Check whether an account has signing keys without throwing.
+     *
+     * Use this as a fast boolean guard before showing signing UI or before
+     * calling any sign* method — those methods throw if signing keys are absent,
+     * so checking first lets you degrade gracefully (e.g. hide a "Sign" button).
+     *
+     * Checks the in-memory keystore cache only — the account must be loaded.
+     * Returns false for unknown accounts rather than throwing.
+     *
+     * @example
+     *   if (!majik.hasSigningCapability()) {
+     *     showUpgradePrompt("Re-import your account to enable signing");
+     *     return;
+     *   }
+     *   const sig = await majik.signText(message);
+     */
+    hasSigningCapability(accountId?: string): boolean;
+    /**
+     * Sign raw bytes or a string using the active account.
+     *
+     * The active account is unlocked automatically if needed.
+     * This is the MajikMessage equivalent of MajikSignature.sign() — it resolves
+     * the signing key from the keystore so you don't have to manage it yourself.
+     *
+     * @example
+     *   const sig = await majik.signContent(documentBytes, { contentType: "application/pdf" });
+     *   const b64 = sig.serialize(); // store alongside the document
+     */
+    signContent(content: Uint8Array | string, options?: {
+        contentType?: string;
+        timestamp?: string;
+        accountId?: string;
+    }): Promise<MajikSignature>;
+    /**
+     * Sign a file and embed the signature directly into it using the active account.
+     *
+     * Format is auto-detected from magic bytes — PDF stays PDF, WAV stays WAV, etc.
+     * Strips any existing signature before signing (idempotent re-signing).
+     * The active account is unlocked automatically if needed.
+     *
+     * @example
+     *   const { blob: signedPdf } = await majik.signFile(pdfBlob);
+     *   // signedPdf is a valid PDF with the signature embedded in its metadata
+     *
+     * @example — non-active account
+     *   const { blob } = await majik.signFile(wavBlob, { accountId: "acc_xyz" });
+     */
+    signFile(file: Blob, options?: {
+        contentType?: string;
+        timestamp?: string;
+        mimeType?: string;
+        accountId?: string;
+    }): Promise<{
+        blob: Blob;
+        signature: MajikSignature;
+        handler: string;
+        mimeType: string;
+    }>;
+    /**
+     * Sign multiple file blobs with the active (or specified) account in one call.
+     *
+     * Each file is signed independently — a failure on one does not abort the
+     * others. Check result.error on each item to handle partial failures.
+     *
+     * The hasSigningKeys check is done once upfront before any signing begins,
+     * so the whole batch fails fast if the account can't sign rather than
+     * discovering it mid-batch.
+     *
+     * @example
+     *   const results = await majik.batchSignFiles([
+     *     { file: pdfBlob, contentType: "application/pdf" },
+     *     { file: wavBlob, contentType: "audio/wav" },
+     *     { file: mp4Blob, contentType: "video/mp4" },
+     *   ]);
+     *   for (const r of results) {
+     *     if (r.error) console.error("Failed:", r.error.message);
+     *     else await r2.put(key, await r.blob!.arrayBuffer());
+     *   }
+     */
+    batchSignFiles(files: Array<{
+        file: Blob;
+        contentType?: string;
+        timestamp?: string;
+        mimeType?: string;
+    }>, options?: {
+        accountId?: string;
+    }): Promise<Array<{
+        blob: Blob | null;
+        signature: MajikSignature | null;
+        serialized: string | null;
+        handler: string | null;
+        mimeType: string | null;
+        error: Error | null;
+    }>>;
+    /**
+     * Verify raw bytes or a string against a MajikSignature.
+     *
+     * The signer can be identified by:
+     *   - A contact ID from the contact directory
+     *   - A raw base64 public key string (same format used in contacts)
+     *   - A MajikKey instance directly
+     *
+     * If no signer is provided, the public keys embedded in the signature
+     * envelope are used (self-reported — see security note below).
+     *
+     * > ⚠️ When no signer is provided, the extracted public keys are self-reported
+     * > by whoever created the signature. Always cross-check `result.signerId`
+     * > against a known contact fingerprint before trusting the result.
+     *
+     * @example — verify against a known contact
+     *   const result = await majik.verifyContent(docBytes, sig, { contactId: "contact_abc" });
+     *   if (result.valid) console.log("Authentic, signed by:", result.signerId);
+     *
+     * @example — verify using embedded keys (self-reported)
+     *   const result = await majik.verifyContent(docBytes, sig);
+     *   // always check result.signerId matches a known fingerprint
+     */
+    verifyContent(content: Uint8Array | string, signature: MajikSignature | MajikSignatureJSON, options?: {
+        contactId?: string;
+        publicKeyBase64?: string;
+        key?: MajikKey;
+        expectedSignerId?: string;
+    }): Promise<VerificationResult>;
+    /**
+     * Verify a file's embedded signature.
+     *
+     * The signer can be identified by:
+     *   - A contact ID from the contact directory
+     *   - A raw base64 public key string
+     *   - A MajikKey instance directly
+     *
+     * If no signer is provided, the public keys embedded in the signature
+     * envelope are used (self-reported — see security note on verifyContent).
+     *
+     * @example — verify a signed PDF against a known contact
+     *   const result = await majik.verifyFile(signedPdf, { contactId: "contact_abc" });
+     *   if (result.valid) console.log("Verified:", result.signerId, result.timestamp);
+     *
+     * @example — check own signed file using active account
+     *   const result = await majik.verifyFile(signedWav, {
+     *     contactId: majik.getActiveAccount()?.id,
+     *   });
+     */
+    verifyFile(file: Blob, options?: {
+        contactId?: string;
+        publicKeyBase64?: string;
+        key?: MajikKey;
+        expectedSignerId?: string;
+        mimeType?: string;
+    }): Promise<VerificationResult & {
+        handler?: string;
+        reason?: string;
+    }>;
+    /**
+     * Verify multiple files' embedded signatures against the same signer in
+     * one call.
+     *
+     * Each file is verified independently — a failed verification sets
+     * result.valid = false and populates result.error, it does not throw.
+     *
+     * @example
+     *   const results = await majik.batchVerifyFiles(
+     *     [pdfBlob, wavBlob, mp4Blob],
+     *     { contactId: "contact_abc" },
+     *   );
+     *   const allValid = results.every(r => r.valid);
+     */
+    batchVerifyFiles(files: Array<Blob | {
+        file: Blob;
+        mimeType?: string;
+        expectedSignerId?: string;
+    }>, options?: {
+        contactId?: string;
+        publicKeyBase64?: string;
+        key?: MajikKey;
+        expectedSignerId?: string;
+    }): Promise<Array<VerificationResult & {
+        handler: string | null;
+        mimeType: string | null;
+        error: Error | null;
+    }>>;
+    /**
+     * Extract the embedded MajikSignature from a file.
+     * Returns a fully typed MajikSignature instance, or null if not found.
+     *
+     * Does not verify — use verifyFile() to verify.
+     *
+     * @example
+     *   const sig = await majik.extractSignature(file);
+     *   if (sig) console.log("Signed by:", sig.signerId, "at", sig.timestamp);
+     */
+    extractSignature(file: Blob, options?: {
+        mimeType?: string;
+    }): Promise<MajikSignature | null>;
+    /**
+     * Return a clean copy of the file with any embedded signature removed.
+     * The returned bytes are exactly what was originally signed.
+     *
+     * Useful before re-processing or re-encrypting a signed file.
+     *
+     * @example
+     *   const originalBlob = await majik.stripSignature(signedMp4);
+     */
+    stripSignature(file: Blob, options?: {
+        mimeType?: string;
+    }): Promise<Blob>;
+    /**
+     * Check whether a file contains an embedded MajikSignature.
+     * Does not verify — purely a structural presence check.
+     *
+     * @example
+     *   if (await majik.isFileSigned(file)) {
+     *     const result = await majik.verifyFile(file, { contactId });
+     *   }
+     */
+    isFileSigned(file: Blob, options?: {
+        mimeType?: string;
+    }): Promise<boolean>;
+    /**
+     * Get the public keys for the active account, ready for use with
+     * MajikSignature.verify() or for sharing with another party.
+     *
+     * Works on locked keys — only reads public fields.
+     *
+     * @example
+     *   const myKeys = await majik.getSigningPublicKeys();
+     *   // share myKeys with someone so they can verify your signatures
+     */
+    getSigningPublicKeys(accountId?: string): Promise<MajikSignerPublicKeys>;
+    /**
+     * Re-sign a file blob — strips any existing embedded signature, signs
+     * with the active (or specified) account, and returns the newly signed blob.
+     *
+     * Use after key rotation or when the signing account changes. The returned
+     * blob is the same format as the input — PDF stays PDF, WAV stays WAV.
+     *
+     * Distinct from resignMajikFile() which operates on a MajikFile instance
+     * (the encrypted .mjkb container). This operates on a plain file Blob.
+     *
+     * @example
+     *   const { blob } = await majik.resignFile(oldSignedPdf);
+     *   await r2.put(key, await blob.arrayBuffer());
+     */
+    resignFile(file: Blob, options?: {
+        contentType?: string;
+        timestamp?: string;
+        mimeType?: string;
+        accountId?: string;
+    }): Promise<{
+        blob: Blob;
+        signature: MajikSignature;
+        handler: string;
+        mimeType: string;
+    }>;
+    /**
+     * Extract metadata from a file's embedded signature without verifying it.
+     *
+     * Useful for rendering "Signed by X at Y" in a UI before the user
+     * explicitly triggers a verify step, or for routing to the correct
+     * contact record before calling verifyFile().
+     *
+     * Returns null if the file has no embedded signature or the JSON is
+     * structurally malformed.
+     *
+     * @example
+     *   const info = await majik.getFileSignatureInfo(pdfBlob);
+     *   if (info) {
+     *     const contact = majik.getContactByID(info.signerId);
+     *     console.log(`Signed by ${contact?.meta?.label ?? info.signerId}`);
+     *     console.log(`Format handled by: ${info.handler}`);
+     *   }
+     */
+    getFileSignatureInfo(file: Blob, options?: {
+        mimeType?: string;
+    }): Promise<MajikSignature | null>;
+    /**
+     * Sign an image with dual-layer embedding.
+     *
+     * Every signed image carries two independent proofs:
+     *
+     *   Layer 1 — Pixel rows appended at the bottom (+~6px height)
+     *     Full MajikSignature: Ed25519 + ML-DSA-87 (post-quantum)
+     *     Survives: direct sharing, email attachments, Slack, internal tools
+     *     Stripped by: platforms that crop/resize (Gmail, LinkedIn, Facebook)
+     *
+     *   Layer 2 — DCT coefficient steganography (invisible, no size change)
+     *     Ed25519-only stub + Reed-Solomon ECC (205 bytes)
+     *     Survives: Q70+ JPEG recompression, WebP conversion, platform uploads
+     *     Does not survive: screenshots, heavy crop, below-Q70 recompression
+     *
+     * Output is PNG by default. When uploaded to a platform, Layer 1 may be
+     * stripped but Layer 2 survives — verifyStamp() handles both automatically.
+     *
+     * Minimum image size: 600×600px (smaller images are padded with white).
+     *
+     * @param image    Any image format the browser supports (JPEG, PNG, WebP…)
+     * @param key      Unlocked MajikKey with signing keys
+     * @param options  Output MIME type, JPEG quality, timestamp override
+     * @returns        blob (signed image), stub (DCT layer metadata),
+     *                 fullEnvelope (complete MajikSignatureJSON for Layer 1)
+     *
+     * @example
+     *   const { blob, stub } = await MajikSignature.stampImage(imageBlob, key);
+     *   // blob  → upload or attach; visually identical to the original
+     *   // stub  → signerId, timestamp, pHash for display
+     */
+    static stampImage(image: Blob, key: MajikKey, options?: ImageSignOptions): Promise<{
+        blob: Blob;
+        stub: ImageSignatureStub;
+        fullEnvelope: MajikSignatureJSON;
+    }>;
+    /**
+     * Verify a stamped image's embedded MajikImageSignature.
+     *
+     * Tries both layers automatically:
+     *   - Both present → both must pass (maximum integrity, post-quantum proof)
+     *   - Pixel row only → pixel row must pass (full Ed25519 + ML-DSA-87)
+     *   - DCT only → DCT must pass (Ed25519 fallback, typical after platform upload)
+     *   - Neither → invalid
+     *
+     * The `layer` field in the result communicates the trust level so callers
+     * can surface it in UI: 'both' > 'pixel-row' > 'dct-only'.
+     *
+     * @param image    The image to verify — may be platform-compressed
+     * @param options  hammingThreshold override (default 8 — strict)
+     *
+     * @example
+     *   const result = await MajikSignature.verifyStamp(imageBlob);
+     *   if (result.valid) {
+     *     console.log(`✓ Signed by ${result.signerId}`);
+     *     console.log(`  Verified via: ${result.layer}`);
+     *     // result.layer: 'both' | 'pixel-row' | 'dct-only'
+     *   }
+     */
+    static verifyStamp(image: Blob, options?: {
+        hammingThreshold?: number;
+    }): Promise<ImageVerificationResult>;
+    /**
+     * Inspect which stamp layers are present without verifying.
+     *
+     * Fast — useful for rendering a "Signed by X on Y" badge in a UI before
+     * committing to a full cryptographic verify call.
+     *
+     * Does NOT confirm the signatures are valid — call verifyStamp() for that.
+     *
+     * @example
+     *   const info = await MajikSignature.inspectStamp(imageBlob);
+     *   if (info.hasPixelRow) console.log('Full post-quantum proof present');
+     *   if (info.hasDct)      console.log('Compression-resistant stub present');
+     *   info.dctMeta?.signerId        // signer ID (unverified — display only)
+     *   info.pixelRowMeta?.timestamp  // timestamp (unverified — display only)
+     */
+    static inspectStamp(image: Blob): Promise<{
+        hasPixelRow: boolean;
+        hasDct: boolean;
+        pixelRowMeta?: {
+            signerId: string;
+            timestamp: string;
+        };
+        dctMeta?: {
+            signerId: string;
+            timestamp: string;
+            pHash: string;
+        };
+    }>;
+    /**
+     * Returns true if the image contains any MajikImageSignature layer.
+     *
+     * Does not verify — structural presence check only.
+     * Use verifyStamp() to confirm the signature is cryptographically valid.
+     *
+     * @example
+     *   if (await MajikSignature.isStamped(imageBlob)) { ... }
+     */
+    static isStamped(image: Blob): Promise<boolean>;
+    /**
+     * Ensure an identity is unlocked.
+     * Delegates entirely to MajikKeyStore.ensureUnlocked() — passphrase prompting
+     * is handled there via onUnlockRequested or the optional promptFn.
+     */
+    ensureIdentityUnlocked(id: string, promptFn?: (id: string) => string | Promise<string>): Promise<CryptoKey | {
+        raw: Uint8Array;
+    }>;
+    isPassphraseValid(passphrase: string, id?: string): Promise<boolean>;
+    /**
+     * Resolve MajikSignerPublicKeys from whichever signer hint was provided.
+     * Returns null if no hint was given (caller should fall back to self-reported keys).
+     *
+     * Mirrors the _resolveRecipients / _resolveFileIdentity pattern used
+     * throughout MajikMessage — consistent account/contact resolution in one place.
+     */
+    private _resolveSignerPublicKeys;
+    toJSON(): Promise<MajikUniversalIdClientJSON>;
+    static fromJSON<T extends MajikUniversalIdClient>(this: new (config: MajikUniversalIdClientConfig, id?: string) => T, json: MajikUniversalIdClientJSON, config?: MajikUniversalIdClientConfig): Promise<T>;
+    on(event: MajikUniversalIdClientEvents, callback: EventCallback): void;
+    off(event: MajikUniversalIdClientEvents, callback?: EventCallback): void;
+    private _registerOwnAccount;
+    private _emit;
+    private attachAutosaveHandlers;
+    startAutosave(): void;
+    stopAutosave(): void;
+    private scheduleAutosave;
+    saveState(): Promise<void>;
+    loadState(): Promise<void>;
+    static loadOrCreate<T extends MajikUniversalIdClient>(this: MajikUniversalIdClientStatic<T>, config: MajikUniversalIdClientConfig, userProfile?: string): Promise<T>;
+    resetData(userProfile?: string): Promise<void>;
+    /**
+     * Create a new MajikUniversalID from a MajikUser and an unlocked MajikKey.
+     *
+     * The key must be unlocked and have all key fields: edPublicKey, mlDsaPublicKey,
+     * mlKemPublicKey (for encryption), and mlKemSecretKey is not needed here —
+     * only the public key is used during creation.
+     *
+     * Private personal info is immediately encrypted with the bound key's
+     * ML-KEM-768 public key. The rehydrated value is kept in-memory so
+     * privateInfo is accessible right after create() without a separate call.
+     *
+     * The identity starts at IDTier.UNVERIFIED.
+     */
+    createUniversalID(user: MajikUser, key: MajikKey, options: CreateUniversalIDOptions): Promise<MajikUniversalID>;
+}
+export {};