npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@hippius/hcfs-client-wasm

v0.14.0

Published

HCFS cryptographic primitives compiled to WebAssembly for browser use

Readme

hcfs-client-wasm

wasm-pack build of the HCFS client crypto surface, published as @hippius/hcfs-client-wasm.

The native cargo test -p hcfs-client-wasm suite (tests/cross_crate_equivalence.rs) is the drift guard against hcfs-client / hcfs-shared. The file cipher and hashes are not a copy: they are hcfs-crypto's, the code the native client and server run, and tests/known_answers.rs checks the bindings against libsodium vectors on the host and, under wasm-pack test --node, on wasm32. tests/secret_hygiene.rs and tests/allocation_profile.rs install a scanning / counting global allocator to check that key material is wiped before it is freed and that the bulk data paths do not copy. wasm-pack test --node runs tests/wasm_smoke.rs on wasm32 (the wasm_js getrandom backend, JsError paths, linear-memory growth). All of them run in .github/workflows/wasm.yml.

# Host-side equivalence, hygiene and allocation tests (not a wasm32 target)
cargo test -p hcfs-client-wasm

# Browser-shaped smoke tests
cd hcfs-client-wasm
wasm-pack test --node
wasm-pack build --target web --release --scope hippius

Secret hygiene: prefer handles

Key material lives in opaque handles, SecretBytes and SecretString, whose buffers stay in wasm memory and are wiped when the handle is dropped or free()d. Anything that crosses into JS as a string or Uint8Array is out of reach: JS strings are immutable and cannot be wiped, and a Uint8Array is only wiped if you fill(0) it yourself.

wasm-bindgen adds a second, unavoidable leak: every string or Uint8Array argument is copied into linear memory for the call and that copy is freed without being wiped by the generated glue, and so is every Vec/String a function returns. Rust cannot reach those copies. The only mitigation is not to pass secrets as plain arguments at all, which is what the handle variants are for.

So pass the account mnemonic around as a SecretString, never as a JS string. Every function that takes a mnemonic has a handle-taking twin with identical output:

| Takes a JS string | Prefer (takes a SecretString) | |---|---| | mnemonic_to_seed(phrase) | mnemonic_to_seed_from_handle(phrase) | | derive_folder_mnemonic(master, label) | derive_folder_mnemonic_from_handle(master, label) (returns a SecretString) | | derive_file_key(master, label) | derive_file_key_from_handle(master, label) | | derive_signing_key(mnemonic) | derive_signing_key_from_handle(mnemonic) | | seal_owner_secret(master, ss58, row_key, secret, is_private, folder_token) | seal_owner_secret_from_handle(...), same arguments | | open_owner_secret(master, ss58, row_key, wrap) | open_owner_secret_from_handle(...), same arguments | | seal_folder_link_owner_secret(master, ss58, token, secret, is_private) | seal_folder_link_owner_secret_from_handle(...), same arguments | | open_folder_link_owner_secret(master, ss58, row_key, wrap) | open_folder_link_owner_secret_from_handle(...), same arguments | | seal_file_link_owner_secret(master, ss58, token, secret, is_private) | seal_file_link_owner_secret_from_handle(...), same arguments | | open_file_link_owner_secret(master, ss58, token, wrap) | open_file_link_owner_secret_from_handle(...), same arguments |

Getting a handle:

// Unlock: open_mnemonic_blob already returns a SecretString.
const master = open_mnemonic_blob(blobJson, passphrase, ss58);

// A typed-in or pasted mnemonic: hand over bytes, then wipe your copy.
const bytes = new TextEncoder().encode(phraseFromInput);
const master2 = SecretString.from_utf8_bytes(bytes);
bytes.fill(0);

const fileKey = derive_file_key_from_handle(master, label);   // SecretBytes
const signingKey = derive_signing_key_from_handle(master);    // SecretBytes
// ...use the handles, then:
fileKey.free(); signingKey.free(); master.free();

Call expose() / expose_bytes() only when a value genuinely has to leave wasm, and prefer expose_bytes() so the result can be fill(0)ed.

Unlock in a dedicated Worker

open_mnemonic_blob runs Argon2id at the blob's parameters: 128 MiB, t=3 for a production blob. That blocks the calling thread for the whole derivation, and it grows the module's linear memory to ~129 MiB, which never shrinks for the life of the instance (the block array itself is wiped after use, but the pages stay mapped).

Run the unlock in a dedicated Web Worker with its own instance of this module, keep the resulting handles and all key-using calls (derivations, chunk encrypt/decrypt, owner wraps) in that worker, and terminate() the worker on lock or logout. Terminating is the only way to give the memory back. Handles cannot be moved between workers; each is tied to the wasm instance that created it.

Large files: stream, don't buffer

encrypt_for_upload(key, plaintext) takes the whole file and returns the whole ciphertext, so linear memory has to hold both (about 2x the file, permanently, since it never shrinks). Reading EncryptedUpload.ciphertext copies straight to a new JS Uint8Array without a further copy inside wasm. For anything large, stream instead:

// Same wire format as encrypt_for_upload:
//   base_nonce(24) | chunk_count(u32 LE) | (len(u32 LE) | ct+tag)*chunk_count
// Hash exactly the bytes you send.
const CHUNK = encryption_chunk_size();          // 256 KiB; larger chunks are refused
const chunkCount = Math.max(1, Math.ceil(file.size / CHUNK));  // an empty file is ONE empty chunk
const baseNonce = crypto.getRandomValues(new Uint8Array(24));  // fresh per upload, never reused

const hash = new Blake3Hasher();                 // Manifest.ciphertext_hash
const salted = Blake3Hasher.salted(ss58);        // Manifest.salted_hash
const header = concat(baseNonce, u32le(chunkCount));
hash.update(header); send(header);
for (let i = 0; i < chunkCount; i++) {
  // For an empty file this is the single chunk i = 0 with 0 bytes, whose
  // ciphertext is just the 16-byte tag (frame length 16).
  const chunk = await readSlice(file, i * CHUNK, Math.min(file.size, (i + 1) * CHUNK));
  salted.update(chunk);
  const ct = encrypt_file_chunk(key, baseNonce, i, chunk);
  const len = u32le(ct.length);
  hash.update(len); hash.update(ct);
  send(len); send(ct);
}
const ciphertextHash = hash.finalize_hex();   // == blake3_hex(wholeCiphertext)
const saltedHash = salted.finalize_bytes();   // == compute_salted_hash(ss58, wholePlaintext)
hash.free(); salted.free();

Blake3Hasher gives the same digest however the input is split. decrypt_file_chunk refuses any chunk longer than max_ciphertext_chunk_size() (262,160 bytes = 256 KiB + 16), the same ceiling as the native client, and encrypt_file_chunk refuses plaintext longer than encryption_chunk_size() (262,144 bytes).

Password-protected links

wrap_share_key refuses a password shorter than share_password_min_len() characters (the rule validate_share_password checks) with share_wrap_failed. unwrap_share_key accepts any length, so links minted before the floor still open.

Invite links without the drive key (0.12.0)

A legacy copy-link invite (/invite/{token}#k=) carries the drive entropy, or a folder invite's file key (#686). When GET /v1/capabilities has drive_invite_link_envelopes: true, mint #i= links instead. Their link secret derives from the drive entropy and the invite id, so the access panel rebuilds a link with nothing new stored.

Minting, after POST /v1/drive-invites returned token:

const inviteId = invite_id_for_token(token);                            // Uint8Array, 32 bytes
const linkSecret = derive_invite_link_secret(driveEntropy, inviteId);   // SecretBytes
// kind "drive" seals the drive entropy; "folder" seals the derived file key.
const envelope = seal_invite_link_envelope(driveEntropy, linkSecret, "drive");  // 73 bytes
const digest = invite_link_fetch_digest_for_secret(linkSecret);         // 32 bytes
// PUT /v1/drives/{folder_hash}/invites/{hex(inviteId)}/link-envelope[?owner=]
//   { link_envelope, link_fetch_digest } (standard base64). If it fails, revoke the invite.
const url = build_invite_link_url(base, token, linkSecret);             // #i=

Joining, on the invite page, signed in:

const fragment = parse_invite_fragment(location.hash);  // throws bad_invite_link
// fragment.kind: "legacy_key" (#k=, the key itself) | "link_secret" (#i=)
if (fragment.is_link_secret) {
  // GET /v1/drive-invites/{token}/link-key with the user bearer and
  // x-hcfs-link-proof: invite_link_fetch_proof(fragment.payload())
  // -> { envelope, kind: "drive" | "folder" }; 404 for a dead link or wrong
  // proof; the accept's own 403 drive_member_limit_reached / 502
  // billing_unavailable for a live invite that must wait.
  const key = open_invite_link_envelope(fragment.payload(), base64Decode(body.envelope), body.kind);
}

Check body.kind against the invite you showed the user; the envelope's AAD binds it, so a folder key never opens as drive entropy. open_invite_link_envelope throws invite_link_open_failed for a wrong secret, the other kind or tampering, and bad_invite_kind for an unknown kind; the other new exports throw invite_link_failed for a handle of the wrong length.

Viewer emails in Insights (0.14.0)

On a gated link, each viewer in GET /v1/shares/{token}/insights (and .../group-insights) carries emails, an array of { email_check, email_ct, email_nonce } (standard base64). The viewer's page sealed email_ct as the comments' encryption says, with additional data <token>:viewer-email. Decrypt it there (WebCrypto AES-GCM, as for names) and show it only when the check matches:

for (const proven of viewer.emails) {
  if (!proven.email_ct) continue; // proven, but the page sealed no copy
  const plain = await openViewerEmail(viewer.share_token, proven.email_ct, proven.email_nonce);
  const email = new TextDecoder().decode(plain); // a string: an ArrayBuffer here never matches
  if (share_email_matches(viewer.share_token, email, proven.email_check)) show(email);
}

Use the entry's share_token, not the token you asked with: on group insights the entry may come from another link of the group, and each check is per link. A server that predates the field omits it; use the token you asked with then. On the share page, seal the canonical email that POST .../gate/verify answers (not what the viewer typed) as the views body's email_ct / email_nonce, so the owner's check matches.

File links without the share key (0.13.0)

A file link can carry a link secret instead of the share key, as a folder link does (#1253). The envelope is the folder link envelope over the share key, so the same exports seal and open it; the API is in shares.md. A server without envelopes ignores the pair and answers without link_envelope: true, so the pair can go with every create.

Minting:

const linkSecret = generate_folder_link_secret();                  // SecretBytes, fresh per link
const envelope = seal_folder_link_envelope(shareKey, linkSecret);  // Uint8Array, 73 bytes
const digest = folder_link_fetch_digest_for_secret(linkSecret);    // Uint8Array, 32 bytes
// POST /v1/shares (or /v1/shares/init) with link_envelope and link_fetch_digest (standard base64).
// Hand out the link only when the response's link_envelope is true; otherwise the share still
// opens with a #k= / #p= link built from shareKey.
const url = password
  ? build_file_link_url_private(base, token, wrap_share_key(password, linkSecret))  // #sp=
  : build_file_link_url(base, token, linkSecret);                                   // #s=

For the cross-device copy, seal_file_link_owner_secret seals the link secret (or its wrapped blob) under the share token, and open_file_link_owner_secret opens both kinds of file wrap, reporting is_link_secret. open_owner_secret refuses link-secret wraps, and neither folder export takes a file one.

Opening, on the recipient page: parse_folder_share_fragment(location.hash) reads the fragment (the /share/ path, not /share/folder/, says it is a file link). For a link secret, GET /v1/shares/{token}/link-key with x-hcfs-link-proof: folder_link_fetch_proof(secret), then open_folder_link_envelope(secret, base64Decode(body.envelope)) returns the share key.

Folder links without the drive key (0.11.0)

A legacy folder link (#k=, or #p= with a password) carries the drive file key, so it opens the whole drive (#665). Mint links that carry a random link secret instead: the server refuses a drive link without an envelope (link_envelope_required, #685). The server stores the file key sealed under it and gives it only to a caller that proves the secret. The API is in folder-shares.md.

Minting:

const linkSecret = generate_folder_link_secret();                 // SecretBytes
const envelope = seal_folder_link_envelope(fileKey, linkSecret);  // Uint8Array, 73 bytes
const digest = folder_link_fetch_digest_for_secret(linkSecret); // Uint8Array, 32 bytes
// POST /v1/folder-shares with link_envelope and link_fetch_digest (standard base64).
// Check the response's link_envelope is true; if not, revoke the share: it can never open.
const url = password
  ? build_folder_link_url_private(base, token, wrap_share_key(password, linkSecret))  // #sp=
  : build_folder_link_url(base, token, linkSecret);                                   // #s=

Keep what the URL carries (the link secret, or the wrapped blob) in the keystore under its own tag. Never pass it to build_folder_share_url / build_folder_share_url_private: a recipient would read it as a drive key. For the cross-device copy, seal_folder_link_owner_secret seals it, and open_folder_link_owner_secret opens both kinds of folder wrap, reporting is_link_secret. open_owner_secret refuses link-secret wraps, so code that predates them cannot rebuild a #k= link from one.

Opening, on the recipient page:

const fragment = parse_folder_share_fragment(location.hash);  // throws bad_folder_link
// fragment.kind: "legacy_key" | "legacy_wrapped" | "link_secret" | "link_secret_wrapped"
let secret = fragment.payload();
if (fragment.is_wrapped) secret = unwrap_share_key(password, secret.expose());
if (fragment.is_link_secret) {
  // GET /v1/folder-shares/{token}/link-key, header x-hcfs-link-proof: folder_link_fetch_proof(secret)
  // 404 for every refusal: unknown, revoked, expired, legacy, or a wrong proof.
  secret = open_folder_link_envelope(secret, base64Decode(body.envelope));  // the file key
}
// `secret` now decrypts the link's files exactly as a #k= key does.

open_folder_link_envelope throws folder_link_open_failed for a wrong secret or a tampered envelope; the other new exports throw folder_link_failed for a handle of the wrong length.

Folder rename (0.10.0)

POST /rename_folder moves a folder and everything in it in one transaction (API page). The request needs each file's new id and its new path sealed with the drive key, so the planning runs here:

// `listed`: every file under oldPrefix, at any depth, as /browse returns them.
const files = plan_folder_rename(JSON.stringify(listed), oldPrefix, newPrefix, driveKey);
const signed = sign_rename_folder(signingKey, oldPrefix, newPrefix, files);
const body = `{"ss58_address":${JSON.stringify(ss58)},"folder_hash":${JSON.stringify(folderHash)},`
  + `"old_prefix":${JSON.stringify(oldPrefix)},"new_prefix":${JSON.stringify(newPrefix)},`
  + `"files":${files},"signature":[${signed.signature}],"signing_key":[${signed.verifying_key}]}`;
signed.free();

Each new id keeps the hash form of the old one (as stored, NFD, or \-separated), as the native client does. rename_folder_signing_text returns the text sign_rename_folder signs.

How to read the answer:

  • 5xx, 408, or a 2xx whose body does not parse: the rename may have applied (a 408 usually means a proxy resent the request without its body after a 5xx). Send the same body again, unchanged: a request that already applied answers 200 with replayed: true. Do not list and plan again first; after an applied rename the old folder is gone, and a freshly planned request can get 404 not_found.
  • Any other non-2xx: a refusal, and nothing moved. The code is at Error.error ({"Error":{"error":"folder_changed","message":"..."}}); a few refusals (account suspension, for one) are a bare {"error":"...","message":"..."}. A 413 may have no JSON body at all.
    • rename_folder_is_retryable(code): the folder changed since it was listed (folder_changed, revision_mismatch). List it again and retry.
    • rename_folder_needs_batches(status, code): the folder is too large for one rename (any 413, or the planner's folder_too_large error, for which pass undefined as the status and the error message as the code). Fall back to /rename_files batches.

The planner checks only the shape of the prefixes (/-separated, no empty segment, different, the new one not inside the old one); the server checks the rest (400 invalid_prefix). Planner errors: invalid_prefix, key_length_invalid, files_json_invalid, folder_too_large (more than 2,000 files, the server's cap), file_path_missing, file_outside_folder.

Behaviour changes in 0.9.0

For the console team. Existing export names, argument types and return types are unchanged; what changes is which inputs now throw, plus new exports.

Existing exports that now throw where they used to succeed:

| Export | Now throws | Error message | |---|---|---| | wrap_share_key(password, key) | password shorter than 8 characters (share_password_min_len()), including "" | share_wrap_failed | | build_share_url, build_folder_share_url | base that is empty, whitespace-only or slash-only ("", " ", "/", " /// "); these used to return a relative /share/... link | console_base_url must not be empty | | build_share_url_private, build_folder_share_url_private | slash-only base (empty/blank already threw) | console_base_url must not be empty | | decrypt_file_chunk | ciphertext longer than 262,160 bytes (max_ciphertext_chunk_size()) | chunk_decrypt_failed | | encrypt_file_chunk | plaintext longer than 262,144 bytes (encryption_chunk_size()) | chunk_encrypt_failed |

Other visible changes: all four URL builders trim surrounding whitespace from the base (the #k= ones used not to), and EncryptedUpload.ciphertext still returns a Uint8Array but no longer clones the ciphertext inside wasm memory first.

New exports:

  • mnemonic_to_seed_from_handle, derive_folder_mnemonic_from_handle, derive_file_key_from_handle, derive_signing_key_from_handle, seal_owner_secret_from_handle, open_owner_secret_from_handle (see "Secret hygiene")
  • SecretString.from_utf8_bytes(bytes)
  • Blake3Hasher (new Blake3Hasher(), Blake3Hasher.salted(ss58), update, finalize_hex, finalize_bytes)
  • encryption_chunk_size(), max_ciphertext_chunk_size()