Browser (WASM)

Generated from capsule-wasm/wasm-surface.d.ts, the public half of the capsule_wasm.d.ts wasm-bindgen emits for capsule-wasm, which mise run wasm-surface-check keeps current in the web gate. To change a description on this page, change the Rust doc comment it comes from and regenerate; this file is build output. Classes have no public constructor: a caller gets one from the function that returns it, and calls free() when done with it. Errors are thrown as an Error whose message is the stable code each description names. Which SDK serves which platform is the SDK overview.

Functions

shareIsPassphraseProtected

export function shareIsPassphraseProtected(wrapped_scope_b64: string): boolean;

Whether the fetched wrapped material is protected by an Argon2id passphrase layer.

The viewer calls this on the material from /s/{opaque-id}/wrapped-secret (or the passphrase_protected flag on the metadata response) to decide whether to prompt for a passphrase before calling open_share. The server holds only the opaque bytes and so cannot answer this — it is a pure client-side inspection.

openShare

export function openShare(wrapped_scope_b64: string, opaque_id_hex: string, fragment_hex: string, passphrase?: string | null): ShareScope;

Open a share link’s encapsulated scope material entirely in the browser.

• wrapped_scope_b64 — the opaque WrappedScope (base64 canonical CBOR) fetched from /s/{opaque-id}/wrapped-secret.
• opaque_id_hex — the {opaque-id} URL path component (lowercase hex; the HKDF salt).
• fragment_hex — the #{secret} URL fragment (lowercase hex; never sent to the server).
• passphrase — supplied only when the link is passphrase-protected; unwrapped here via Argon2id and never transmitted.

Throws (as Error.message): passphrase_required, wrong_secret (wrong passphrase or wrong fragment/opaque — indistinguishable), or malformed.

openShareMetadata

export function openShareMetadata(blob: Uint8Array, opaque_id_hex: string, fragment_hex: string): ShareMetadataView;

Open the sealed share metadata record entirely in the browser.

• blob — the octets of /s/{opaque-id}/blob/{metadata_hash}.
• opaque_id_hex / fragment_hex — the URL’s path id and #{secret}, as for open_share.

Throws (as Error.message): wrong_secret (the blob does not open under this URL — a wrong fragment, a wrong opaque id, or a tampered blob, indistinguishable) or malformed (bad hex, or a record this reader does not understand).

sealDrop

export function sealDrop(plaintext: Uint8Array, drop_pubkey: Uint8Array, content_type: string): WasmSealedDrop;

Seal one selected asset for a guest drop, entirely in the browser.

• plaintext — the asset bytes read from the file picker.
• drop_pubkey — the link’s Drop Key public half, decoded from the URL #{drop_pubkey} fragment (which never reaches the server).
• content_type — the asset’s media type (validated server-side against the link’s closed enum; here it is carried verbatim into the descriptor).

Draws a fresh K, STREAM-encrypts under it, and KEM-encapsulates K to the Drop Key. Throws seal_failed (as Error.message) if the Drop Key is malformed.

sealDropDerand

export function sealDropDerand(plaintext: Uint8Array, drop_pubkey: Uint8Array, content_type: string, k_hex: string, nonce_prefix_hex: string, eseed_hex: string, blob_nonce_hex: string): WasmSealedDrop;

Derandomized seal_drop_wasm — exposed for the cross-language known-answer test only.

Every value the production seal draws from the CSPRNG is supplied explicitly (k, nonce_prefix, eseed, blob_nonce, all lowercase hex) so the browser seal is byte-for-byte reproducible and can be proven identical to capsule_core::drop::seal_drop_derand — the Rust adopter then consumes those exact bytes (the cross-language KAT). Web app code uses seal_drop_wasm, never this. Throws malformed on a bad-length hex field, seal_failed on a malformed Drop Key.

dropPassphraseProof

export function dropPassphraseProof(passphrase: string, salt_hex: string, mem_kib: number, t_cost: number, p_cost: number): string;

Derive the Argon2id proof a passphrase-gated upload link requires at drop-session creation.

The link’s salt + Argon2id parameters travel in the URL fragment beside the Drop Key; the passphrase is entered by the guest and never leaves the browser. The returned lowercase-hex proof equals the server’s stored verifier byte-for-byte (both are Argon2id(passphrase, salt, params)), so submitting it proves possession without transmitting the passphrase (SSoT: Web Upload — the optional-passphrase abuse gate). Throws malformed on a bad salt hex, seal_failed if the KDF parameters are invalid.

decodeLqip

export function decodeLqip(format_version: number, chromahash: Uint8Array, dominant_color: Uint8Array, max_width: number, max_height: number): WasmLqipImage;

Render a sidecar lqip record to a paintable placeholder, band-limited to the box being painted.

• format_version — the record’s lqip.format_version.
• chromahash — the record’s lqip.chromahash payload (32 bytes at the committed tier).
• dominant_color — the record’s lqip.dominant_color, exactly 3 bytes (opaque RGB).
• max_width / max_height — the box the caller is about to paint. Decoding to the box rather than to a fixed size is the point of decode_capped: a grid cell never scales down a larger decode.

Infallible. An unrecognised format_version, a payload the parser rejects, and a dominant_color that is not three bytes all yield a solid fallback fill rather than a throw.

A placeholder is cosmetic: it never damages a library and its absence never loses data, so failing a viewer over one trades a blurry square for a broken gallery. The earlier version threw on a malformed dominant_color while the native FFI painted black for the same input — one record, two behaviours, decided by which client opened it. That is exactly the client-dependent divergence capsule-core::lqip exists to prevent, so both surfaces now paint the same fallback fill (black, the conventional empty cell) and say so.

Classes

ShareMetadataView

export class ShareMetadataView

The opened share metadata record — what the viewer starts from, recovered client-side from the blob at the link’s metadata_hash with the URL’s opaque id and fragment.

free

free(): void;

expiresAt

expiresAt(): string | undefined;

The issuer’s RFC 3339 expiry, for display; undefined when the link does not expire.

linkScopeB64

linkScopeB64(): string | undefined;

The link-only scope, base64 canonical CBOR — exactly what open_share takes. Present iff the link has no passphrase; a passphrase link’s scope is fetched from /s/{opaque-id}/wrapped-secret instead.

assets

assets(): SharedAssetView[];

Every covered asset, in the issuer’s order.

ShareScope

export class ShareScope

The opened scope of a share link — the decryption material recovered client-side from the URL fragment secret (and passphrase, if any). Hold it to decrypt_blob the covered ciphertext blobs the serve path returns.

free

free(): void;

scopeKind

scopeKind(): string;

"asset" or "album" — what the opened scope grants, for the viewer’s read-only header.

decryptBlob

decryptBlob(file_id: string, amk_version: number, nonce_prefix_hex: string, ciphertext: Uint8Array, wrapped_file_key_hex?: string | null): Uint8Array;

Derive the covered asset’s per-file key and STREAM-decrypt ciphertext to plaintext.

• file_id — the asset/file UUID (the served asset_id).
• amk_version / nonce_prefix_hex — the asset’s crypto-manifest parameters. For an asset-scoped grant the file key is carried directly and both are unused; for an album-scoped grant the key is derived from the epoch AMK with the nonce prefix folded in.
• ciphertext — the octets from /s/{opaque-id}/blob/{hash}.
• wrapped_file_key_hex — lowercase hex of the asset’s AMK-sealed wrapped_file_key, passed only when its key_mode is wrapped (an adopted web-upload drop, whose key a guest chose and no AMK derives). Omitted (or null) means key_mode = derived. A trailing optional argument, so an existing three-plus-ciphertext call is unchanged.

Throws: scope_unavailable (the scope does not cover this asset/epoch), tampered (the AEAD tag failed — tamper/truncation/wrong key — or the wrapped key did not open), or malformed (bad file_id/prefix/wrapped-key hex or length).

SharedAssetView

export class SharedAssetView

One covered asset of an opened ShareMetadataView, in the shapes ShareScope::decrypt_blob and /s/{opaque-id}/blob/{hash} take.

Member	Declaration	Description
amkVersion	readonly amkVersion: number;	The AMK epoch — decryptBlob’s amk_version.
contentHash	readonly contentHash: string;	The ciphertext’s content address, lowercase hex — the {hash} to fetch.
contentType	readonly contentType: string;	The plaintext media type.
noncePrefixHex	readonly noncePrefixHex: string;	The STREAM nonce prefix, lowercase hex — decryptBlob’s nonce_prefix_hex.
wrappedFileKeyHex	readonly wrappedFileKeyHex: string | undefined;	The AMK-sealed file key, lowercase hex; present iff the key mode is wrapped.
size	readonly size: number;	The plaintext byte length, as a JS number.
assetId	readonly assetId: string;	The asset’s file UUID — decryptBlob’s file_id.
keyMode	readonly keyMode: string;	"derived" or "wrapped".

free

free(): void;

WasmLqipImage

export class WasmLqipImage

A decoded LQIP placeholder: packed RGBA8, ready for putImageData.

A struct rather than a bare Vec<u8> because the caller cannot know the dimensions in advance: decode_capped returns the largest frame that fits inside the requested box while preserving the source aspect ratio, so the answer is (width, height, rgba) or nothing.

Member	Declaration	Description
rgba	readonly rgba: Uint8Array;	Packed RGBA8 samples, width * height * 4 bytes — the exact layout new ImageData(rgba, width, height) takes.
width	readonly width: number;	Frame width in pixels — at most the maxWidth that was requested.
height	readonly height: number;	Frame height in pixels — at most the maxHeight that was requested.

free

free(): void;

WasmSealedDrop

export class WasmSealedDrop

A sealed guest drop, ready for the uploader to open a drop session and stream its chunks.

Holds the STREAM ciphertext plus the unsigned descriptor’s fields, projected across the JS boundary in exactly the wire shapes the drop endpoints expect (hex nonce prefix / ciphertext hash, base64 kem_ct) so the TypeScript uploader builds the request body without re-encoding crypto. Contribute-only: it exposes no way to recover K or decrypt — only a native adopter, holding the Drop Key private half, can do that.

free

free(): void;

chunkSize

chunkSize(): number;

The STREAM plaintext chunk size.

ciphertext

ciphertext(): Uint8Array;

The STREAM ciphertext octets the uploader streams to the drop endpoint (a copy).

kemCtB64

kemCtB64(): string;

K encapsulated to the Drop Key (KEM-DEM), base64 — the descriptor wire field. Opaque to the server; only the Drop Key private half opens it.

contentType

contentType(): string;

The declared content type (the closed-enum value passed into seal_drop_wasm).

ciphertextLen

ciphertextLen(): number;

Total ciphertext byte length — the drop session’s declared size and the cumulative upload target, as a JS number.

plaintextSize

plaintextSize(): number;

Total plaintext byte length (plaintext_size), as a JS number — the drop descriptor wire field. A guest asset never approaches the 2^53 exact-integer ceiling.

noncePrefixHex

noncePrefixHex(): string;

The 7-byte STREAM nonce prefix, lowercase hex (14 chars) — the descriptor wire field.

ciphertextHashHex

ciphertextHashHex(): string;

The ciphertext content-address digest, lowercase hex (64 chars) — the descriptor wire field and the per-chunk / finalization checksum the uploader sends.