@shhnote/client
v0.7.0
Published
shhnote client: the protocol, the API client and the reference page controllers for building secret-sharing frontends against a shhnote instance
Maintainers
Readme
@shhnote/client
The client side of shhnote: secrets are encrypted in the browser, the server only ever sees ciphertext. This package is what the built-in website and other frontends are made of.
Three entry points, take the layer you need:
@shhnote/client/crypto— the protocol (SPEC §2): fragments, key derivation, the blob format, padding, chunked AES-GCM, the streaming decoder. Nofetch, no DOM; pinned by the conformance vectors.@shhnote/client— the protocol plus theApiclient,getConfig/invalidateConfig,createSecret/revealSecret/burnSecret, the protocol check (checkProtocol,SUPPORTED_FRAGMENT_VERSIONS), the Argon2 loader,sanitiseFileName,isUserActivationand the wipe helpers. No DOM; runs in browsers, Node and workers.@shhnote/client/ui— the reference page controllers (wireCreate,wireReveal,wireBurn,wireReport, …),createTand the helpers the reference pages use (formatDuration,ttlChoices,fillTtl,COPIED_MS). They bind todata-shh-*attributes inside a root element you give them and take their strings from you; they ship no CSS, and any markup they generate is either yours (a<template>) or plain elements withdata-shh-*hooks only.
@shhnote/client/argon2.wasm is the Argon2id module (the same Rust crate the server uses),
to serve from your own origin; passphrase secrets need it. @shhnote/client/package.json is
exported too.
Scripts, bots and other clients
import { createSecret, revealSecret, Argon2 } from "@shhnote/client";
// The versioned API base: "/api/v1" on the site's host, or "/v1" on an `api.` host.
const api = { apiBase: "https://secrets.example.com/api/v1" };
const { fragment, burnFragment } = await createSecret({
...api,
payload: { text: "the password is hunter2", files: [] },
lifetime: "single_view",
ttlSeconds: 86400,
});
// Links: `https://secrets.example.com/s#${fragment}` and `…/burn#${burnFragment}`.
const { payload } = await revealSecret(`#${fragment}`, api);- Passphrases need the Argon2 module:
argon2: await Argon2.load(wasmBytes)(in Node, the bytes of@shhnote/client/argon2.wasm). A passphrase is a non-empty string;""is refused (empty_passphrase), and omitting it is the only way to mean "none". /configcomes first.createSecretandrevealSecretread the instance'sGET /config(once per API base and fetch implementation, throughgetConfig) and throwShhError("unsupported_protocol")if itsfragment_versionis not one this package supports, before anything is uploaded or claimed.revealSecretdoes not reveal without it./configis checked, not trusted. Every field must have the right shape and range (whole numbers where numbers are expected, a well-formed padding policy, the twoweb_modevalues, and so on); anything else isApiError(0, "invalid_config"), naming the field, and nothing is revealed or uploaded.max_blob_bytesis clamped to the 4 GiB any instance can store at most. An instance older than this package (noserver_versionorweb_mode) is refused the same way; the two are versioned together.max_blob_bytesis a bucket. It is the largest padded size (SPEC §6.2) the instance accepts, not a byte count of the blob: the blob for that bucket isblobLen(bucket)bytes, the bucket plus a 95-byte header and a 16-byte tag per 64 KiB chunk.createSecretcompares the padded size with it;revealSecretcaps the body atblobLen(max_blob_bytes), or atmaxBlobBytes(a byte count) when you pass a smaller one, both as announced inContent-Lengthand as received, and bounds the decoder by the announced length so a blob whose manifest claims more than it holds reserves nothing.- Single-view secrets are consumed by
revealSecret, and confirmed (destroyed) right away unless you passconfirm: false. Any failure after the claim (a wrong passphrase, a dropped connection, a failed confirm) carries aclaimToken; pass it back asclaimTokenwithin the claim window and the secret is downloaded again instead of being lost. If only the confirm failed, theApiErroralso carries the decryptedpayload. - Errors are
ShhError(the protocol;codeis stable) orApiError(statusand the server'scode; status0withnetworkortoo_largewhen no complete answer arrived). getConfig(apiBase, fetch?)is exported: the same cached/configthe functions use. A failed fetch is not kept; a successful one is kept for the life of the page or process.invalidateConfig(apiBase, fetch?)drops it, so the next call fetches again.createSecretdoes that itself once when the instance answers400 invalid_blob_lengthorfiles_disabled(its padding policy or file setting changed since/configwas read) and pads again with the fresh answer;isStalePolicyError(e)is the test it uses, exported for callers that driveApithemselves. Other changes (lifetimes, limits) are picked up only after an invalidation or a restart.
The reference controllers (/ui)
import { createT, wireReveal } from "@shhnote/client/ui";
wireReveal(document.querySelector("[data-shh-page=reveal]"), {
t: createT(), // or your own (key, vars) => string
apiBase: "https://api.secrets.example.com/v1",
argon2Url: "/argon2.wasm",
});Strings. Every controller takes { t }, a function (key, vars?) => string over the keys
listed below (UiKey). createT(root?) builds one from a
<script type="application/json" data-shh-i18n>{"key": "text", …}</script> block (inside
root, else in the document), filling {name} from vars and falling back to the key.
Options. wireCreate and wireReveal also take apiBase, argon2Url and maxBlobBytes.
An option wins; otherwise the controller reads data-shh-api, data-shh-asset-version and
data-shh-max-blob-bytes from the root, an ancestor or <body> (pageSettings resolves
this, if you want to see the result):
apiBase: required one way or the other.argon2Url:/static/argon2.wasm?v=<version>when the page names an asset version (the instance's own pages), otherwise/argon2.wasmat the page's origin. It must be on the page's own origin:loadArgon2refuses any other withargon2_unavailable, since a module from elsewhere could hand every passphrase secret a constant key (SPEC §10).maxBlobBytes: a byte count, only ever a tighter cap than the instance's own. The reveal page caps the body at the smaller of this option andblobLen(max_blob_bytes)from/config, read after the press; it ignores thedata-shh-max-blob-bytesattribute, which was rendered when the page loaded and could be staler than/config(a cap below the real size would cost a single-view secret, since the claim comes before the body). The create page uses the attribute as an early hint and/configas the instance's word, comparing the padded size, not the blob length.
Both pages read /config (once, shared through getConfig, and checked as described above)
and check its fragment_version with checkProtocol: the create page before it encrypts,
the reveal page after the press and before the reveal request, so a single-view secret is
never used up by a page that cannot open it. If /config cannot be read, the reveal page
stays armed with reveal-error-network; an unsupported version shows
error-unsupported-protocol. The create page retries once with a fresh /config when the
instance refuses the blob's size (its policy changed), reading the files again for the second
attempt. Both pages reload themselves when restored from the back-forward cache, since their
secret material was wiped when they were left.
wireBurn and wireReport take only t and apiBase (Pick<PageOptions, "t" | "apiBase">):
passing argon2Url or maxBlobBytes to them is a type error, since neither would do anything
there.
States. Inside a controller's root, every [data-shh-state="<name>"] element is hidden
except the one for the current state. Elements the markup below calls "shown" start with
hidden and are revealed by the controller once it has checked the page, so nothing works
before the script runs.
Templates. Where a controller renders a list item it uses your
<template data-shh-template="<name>"> when the page has one (its first element is cloned,
looked up inside the root, then in the document), else a plain <li> with the same hooks.
Text is always set with textContent, never as HTML. A template that lacks a required hook
is refused when the controller is wired (wireReveal throws for a file-card without its
download anchor), not when a secret is on screen, so a mistake in your markup can never
consume a single-view secret.
wireCreate(root, options)
[data-shh-create-wrapper], shown on start, hidden after a create. Inside it[data-shh-form=create]with a[data-shh-status]and abutton[type=submit], and the fieldsnote(text),passphrase,burn(a checkbox: checked means single view) and the lifetime: aselect[data-shh-ttl], which is filled from the instance'sttl_presetsanddefault_ttl_secs, labelled by the browser in the page's language, or else any field namedexpiryholding seconds.- Optional
[data-shh-dropzone]around aninput[type=file], with a[data-shh-file-list]next to it (same parent); hidden when the instance has files off. Items: templatedropzone-itemwith[data-shh-file-name],[data-shh-file-meta](the size) andbutton[data-shh-file-remove]. While files are dragged over it, the zone hasdata-shh-dragging="true". [data-shh-create-result], shown after a create, holding[data-shh-share-link],[data-shh-burn-link](the links as text),a[data-shh-open-link],[data-shh-chip=lifetime],[data-shh-chip=expiry],[data-shh-passphrase-reminder](shown when a passphrase was set),[data-shh-copy=share],[data-shh-copy=burn],[data-shh-destroy]and a[data-shh-status].- The links are
<page origin>/s#…and<page origin>/burn#…: the frontend must serve those paths (seedocs/deploy/own-frontend.md). - The note is refused when its UTF-8 length exceeds the instance's
text_max_bytes, with the limit shown. - The Argon2 module at
argon2Urlis fetched as soon as the form is wired, passphrase or not (D-22), so a page's own<link rel="prefetch">for the same URL is harmless and not needed. - Strings:
create-encrypting,create-uploading,create-error-empty,create-error-too-large,create-error-text-too-long({max}),create-error-network,create-error-failed,create-error-wasm,error-unsupported-protocol,result-chip-single,result-chip-multi,result-chip-expires({period}),result-destroyed,form-files-remove.
wireReveal(root, options)
- States
armed(the initial one),working,passphrase,revealed,notfound. [data-shh-form=reveal], shown once the fragment is valid, with its button and a[data-shh-status]. No API request is sent until that button gets a real click or key press (isUserActivation); scripted clicks and submits do nothing. The Argon2 module is fetched on load either way, so its request says nothing about passphrases.[data-shh-status=working]for progress.[data-shh-form=passphrase]withinput[name=passphrase], a button and a[data-shh-status].- Inside
[data-shh-state=revealed]:[data-shh-lifetime]with[data-shh-lifetime-text](for a single-view secretreveal-single-viewonce shown, thenreveal-single-view-destroyedonce the confirm has succeeded; hidden for a TTL secret),[data-shh-text-block](shown when there is text) with[data-shh-text]and[data-shh-copy=text], and the list[data-shh-files]. Items: templatefile-cardwith[data-shh-file-name](the sanitised name, in a<bdi>),[data-shh-file-meta](the sender's type with controls and bidi characters removed, and the size, in a<bdi>) and the requireda[data-shh-file-download](anapplication/octet-streamblob URL; keeps its own label or getsreveal-download). - What a failed reveal says:
reveal-error-corruptonly when decryption failed (the link is incomplete or the data is not a secret);reveal-error-networkwhen no answer arrived;reveal-error-busyfor a rate limit, a restart or an instance that is not set up (the link is fine, try again);reveal-error-too-largefor a body over the cap.revealErrorKey(e)is exported, for a page that renders its own status. - Strings:
reveal-fetching,reveal-decrypting,reveal-wrong-passphrase,reveal-single-view,reveal-single-view-destroyed,reveal-download,reveal-error-network,reveal-error-busy,reveal-error-too-large,reveal-error-corrupt,reveal-error-wasm,error-unsupported-protocol.
wireBurn(root, options) and wireReport(root, options)
- Burn: states
armed,done,notfound;[data-shh-form=burn], shown once the fragment is a burn fragment, with its button and a[data-shh-status]. Only a trusted submit burns. Strings:burn-working,reveal-error-network. - Report: state
done;[data-shh-form=report], shown on start, withinput[name=link], a button and a[data-shh-status]; a/report#…URL pre-fills the field. Strings:report-working,report-error-invalid,reveal-error-network.
Smaller pieces
wireCopy(button, getText): copies, then setsdata-shh-copied="true"on the button for 1.5 seconds. The button's content is never touched; show "copied" with your own CSS. (A third argument is accepted and ignored, for 0.3.0 callers.)wireDropzone(zone, { t }, root?)returns aDropzone(files,hide(),reset()). Thedropzone-itemtemplate is looked up inroot(the zone's parent when none is given), then in the document;wireCreatepasses its own root.wirePasswordToggles(root?):[data-shh-pwd-input]wrapping aninputand a[data-shh-pwd-toggle]button; setsaria-pressedanddata-shown.wireTheme(root?): buttons[data-shh-theme-choice=light|dark|light-hc|dark-hc|auto]setdata-themeon<html>andaria-checked, remembered inlocalStorage(shhnote-theme) when the browser allows.wireMenus(root?): closesdetails[data-shh-menu]on outside click, focus loss or Escape.wireTabs(root?):[data-shh-tabs]with a[role=tablist]of[role=tab][aria-controls]and optional[data-shh-tab-link]links. Shows the tab list and setsdata-shh-ready="true"on the container once wired, so your CSS can hide what only makes sense without tabs.formatDuration(seconds, locale?): a lifetime in its largest whole unit, worded by the browser (Intl), e.g. "15 minutes", "3 days".ttlChoices(config)gives the lifetimeswireCreateoffers ({ seconds, selected }), andfillTtl(select, config, locale?)fills a<select>with them.COPIED_MSis how longwireCopykeepsdata-shh-copied.
What is stored and what is wiped
The reveal controller keeps one thing in browser storage: the claim token of a single-view
secret, in sessionStorage under SHA-256(lookup), as {claimToken, expiresAt}, until the
claim window closes, the secret is confirmed or a reveal finds nothing. A reload within the
window then downloads the claimed secret again rather than finding it gone. The entry is
useless without the seed, which is never stored. Browsers persist sessionStorage to disk
for session restore, so for the length of the window it can sit in the recipient's browser
profile, next to the share URL the browser keeps in its history anyway. The theme choice is
the only other value, in localStorage.
Secret bytes are overwritten when they are done with and when the page is left (SPEC §10
lists exactly what; on the reveal page that includes the lookup value and the claim token once
no confirm is still retrying, and the Argon2 wrapper wipes its copy of the passphrase bytes).
For your own state use wipeBytes(...buffers) and wipePayload(payload); the latter
overwrites file bytes but cannot touch payload.text: JavaScript strings cannot be
overwritten.
Served bundles, conformance, versions
Every instance also serves the root and /ui entries as /static/shh.js and
/static/shh-ui.js, with /static/argon2.wasm, for frontends without a build step on the
same origin as the instance (module scripts load with CORS, which /static/* does not send).
A frontend built on this package should meet the frontend conformance checklist in the
repository (docs/frontend-conformance.md).
The package is versioned in lockstep with the server: @shhnote/client x.y.z is released
together with shhnote x.y.z. Compatibility with an instance is by fragment_version in
GET /config, which the package checks itself. AGPL-3.0-only.
