react-cheminfo 0.52.0 → 0.53.0

package/src/share/core/index.ts

@@ -52,6 +52,16 @@ export {
 } from './preferences.ts';
 export type { SharePreset } from './presets.ts';
 export { applySharePreset, findSharePreset } from './presets.ts';
+export type { SealProblem, UnsealResult } from './seal.ts';
+export {
+  SEAL_PARAM,
+  sealQuery,
+  sealShareUrl,
+  sealedToken,
+  unsealQuery,
+} from './seal.ts';
+export type { SealedAddress } from './sealedAddress.ts';
+export { canOpenSealedAddresses, openSealedAddress } from './sealedAddress.ts';
 export type { EmbedCodeOptions, ShareUrlOptions } from './url.ts';
 export { buildEmbedCode, buildShareUrl } from './url.ts';
 export type {

package/src/share/core/preferences.ts

@@ -1,3 +1,5 @@
+import { pageHistory, pageLocation } from '../../router/core/pageAddress.ts';
+
 import { EMBED_PARAM, HIDE_PARAM } from './config.ts';
 import type { ShareParamCodec } from './params.ts';
 import type { QueryEntry } from './query.ts';
@@ -56,12 +58,12 @@ export interface SyncPreferencesOptions {
   subscribe: (listener: () => void) => () => void;
   /**
    * The address to read and keep up to date.
-   * @default globalThis.location
+   * @default pageLocation()
    */
   location?: PreferenceLocation;
   /**
    * The history to rewrite.
-   * @default globalThis.history
+   * @default pageHistory()
    */
   history?: PreferenceHistory;
 }
@@ -157,16 +159,14 @@ export function writePreferencesToSearch(
 export function syncPreferencesWithUrl(
   options: SyncPreferencesOptions,
 ): () => void {
-  const {
-    preferences,
-    subscribe,
-    location = globalThis.location,
-    history = globalThis.history,
-  } = options;
+  const { preferences, subscribe } = options;
+  const location = options.location ?? pageLocation();
+  const history = options.history ?? pageHistory();
   assertPreferenceNames(preferences);
+  if (location === undefined || history === undefined) return () => undefined;
   applyPreferencesFromSearch(location.search, preferences);
   let active = true;
-  function write(): void {
+  const write = (): void => {
     if (!active) return;
     const current = location.search;
     const next = writePreferencesToSearch(current, preferences);
@@ -177,7 +177,7 @@ export function syncPreferencesWithUrl(
       '',
       `${location.pathname}${query}${location.hash}`,
     );
-  }
+  };
   const unsubscribe = subscribe(write);
   write();
   return () => {

package/src/share/core/seal.ts

@@ -0,0 +1,233 @@
+import { EMBED_PARAM } from './config.ts';
+import { firstValues, parseQuery, serializeQuery } from './query.ts';
+
+/** The query parameter a sealed link carries, and the only one it carries. */
+export const SEAL_PARAM = 's';
+
+/** Why a sealed link could not be opened. */
+export type SealProblem = 'malformed' | 'tampered' | 'unsupported';
+
+/** What opening a sealed link gave. */
+export type UnsealResult =
+  { ok: true; query: string } | { ok: false; problem: SealProblem };
+
+// The key is in every page that opens a sealed link, so it is not a secret: the
+// seal keeps a class from reading or editing a link, not someone who digs the
+// key out of the bundle. The version prefix of a token picks its key, so a new
+// key ships under a new version and every older link keeps opening.
+const KEYRING: Readonly<Record<string, string>> = {
+  e1: 'MOCyEX25cEtWf2QJ6Ux_2lFxN_4oCwjtqyOkOC4tCXA',
+};
+const CURRENT_VERSION = 'e1';
+
+// The tag is an HMAC of the message, and also the counter the message is
+// encrypted under: the synthetic-IV construction. One 8-byte value both refuses
+// an edited link and makes sealing deterministic, so the same query always
+// gives the same link.
+const TAG_LENGTH = 8;
+const COUNTER_BITS = 64;
+const COMPRESSED = 1;
+
+interface SealKeys {
+  cipher: CryptoKey;
+  mac: CryptoKey;
+}
+
+const keys = new Map<string, Promise<SealKeys>>();
+
+/**
+ * Seal a query string: compressed when that makes it shorter, then encrypted
+ * under a tag computed from it, so the token can be neither read nor edited
+ * without the key, and the same query always gives the same token.
+ * @param query - The query string the page is to read, without its leading `?`.
+ * @returns The token, `e1.` followed by base64url.
+ */
+export async function sealQuery(query: string): Promise<string> {
+  const plain = new TextEncoder().encode(query);
+  const packed = await transform(plain, new CompressionStream('deflate-raw'));
+  const compressed = packed.length < plain.length;
+  const body = compressed ? packed : plain;
+  const message = new Uint8Array(1 + body.length);
+  message[0] = compressed ? COMPRESSED : 0;
+  message.set(body, 1);
+
+  const { cipher, mac } = await keysOf(CURRENT_VERSION);
+  const tag = await tagOf(mac, CURRENT_VERSION, message);
+  const encrypted = await crypto.subtle.encrypt(ctr(tag), cipher, message);
+  const sealed = new Uint8Array(TAG_LENGTH + encrypted.byteLength);
+  sealed.set(tag);
+  sealed.set(new Uint8Array(encrypted), TAG_LENGTH);
+  return `${CURRENT_VERSION}.${toBase64Url(sealed)}`;
+}
+
+/**
+ * Open a token written by {@link sealQuery}. Never throws: a token that was
+ * edited, cut, or minted by a newer key is answered with the reason.
+ * @param token - The value of the `s` parameter.
+ * @returns The query string it carries, or why it cannot be opened.
+ */
+export async function unsealQuery(token: string): Promise<UnsealResult> {
+  const dot = token.indexOf('.');
+  if (dot === -1) return { ok: false, problem: 'malformed' };
+  const version = token.slice(0, dot);
+  if (!Object.hasOwn(KEYRING, version)) {
+    return { ok: false, problem: 'unsupported' };
+  }
+  const sealed = fromBase64Url(token.slice(dot + 1));
+  if (sealed === null || sealed.length <= TAG_LENGTH) {
+    return { ok: false, problem: 'malformed' };
+  }
+
+  const { cipher, mac } = await keysOf(version);
+  const tag = sealed.subarray(0, TAG_LENGTH);
+  const message = new Uint8Array(
+    await crypto.subtle.decrypt(ctr(tag), cipher, sealed.subarray(TAG_LENGTH)),
+  );
+  if (!sameBytes(tag, await tagOf(mac, version, message))) {
+    return { ok: false, problem: 'tampered' };
+  }
+
+  const flags = message[0] ?? 0;
+  if (flags > COMPRESSED) return { ok: false, problem: 'unsupported' };
+  const body = message.subarray(1);
+  try {
+    const plain =
+      flags === COMPRESSED
+        ? await transform(body, new DecompressionStream('deflate-raw'))
+        : body;
+    const query = new TextDecoder('utf-8', { fatal: true }).decode(plain);
+    return { ok: true, query };
+  } catch {
+    return { ok: false, problem: 'malformed' };
+  }
+}
+
+/**
+ * The sealed token a query string carries.
+ * @param search - The query string, with or without its leading `?`.
+ * @returns The value of `s`, or `null` when the address is not sealed.
+ */
+export function sealedToken(search: string): string | null {
+  return firstValues(parseQuery(search)).get(SEAL_PARAM) ?? null;
+}
+
+/**
+ * Turn a share link into its sealed form: the same page, with everything its
+ * query string said moved into one `s` token. A sealed page is always
+ * embedded, so the token says `embed=1` whatever the link said.
+ * @param url - The absolute share link.
+ * @returns The sealed link.
+ */
+export async function sealShareUrl(url: string): Promise<string> {
+  const address = new URL(url);
+  const entries = parseQuery(address.search).filter(
+    ([key]) => key !== EMBED_PARAM && key !== SEAL_PARAM,
+  );
+  entries.push([EMBED_PARAM, '1']);
+  const token = await sealQuery(serializeQuery(entries));
+  address.search = `?${SEAL_PARAM}=${token}`;
+  return address.href;
+}
+
+function keysOf(version: string): Promise<SealKeys> {
+  let pair = keys.get(version);
+  if (pair === undefined) {
+    pair = deriveKeys(version);
+    keys.set(version, pair);
+  }
+  return pair;
+}
+
+// One key per purpose, both derived from the version's key, since a key is
+// never used for two algorithms.
+async function deriveKeys(version: string): Promise<SealKeys> {
+  const raw = fromBase64Url(KEYRING[version] ?? '') ?? new Uint8Array();
+  const base = await crypto.subtle.importKey('raw', raw, 'HKDF', false, [
+    'deriveKey',
+  ]);
+  function derive(
+    purpose: string,
+    algorithm: AesKeyGenParams | HmacImportParams,
+    usages: KeyUsage[],
+  ): Promise<CryptoKey> {
+    const info = new TextEncoder().encode(
+      `cheminfo seal ${version} ${purpose}`,
+    );
+    return crypto.subtle.deriveKey(
+      { name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(), info },
+      base,
+      algorithm,
+      false,
+      usages,
+    );
+  }
+  const [cipher, mac] = await Promise.all([
+    derive('cipher', { name: 'AES-CTR', length: 256 }, ['encrypt', 'decrypt']),
+    derive('mac', { name: 'HMAC', hash: 'SHA-256', length: 256 }, ['sign']),
+  ]);
+  return { cipher, mac };
+}
+
+// The version is signed with the message, so a token cannot be moved under
+// another version's key.
+async function tagOf(
+  mac: CryptoKey,
+  version: string,
+  message: Uint8Array<ArrayBuffer>,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const prefix = new TextEncoder().encode(`${version}.`);
+  const signed = new Uint8Array(prefix.length + message.length);
+  signed.set(prefix);
+  signed.set(message, prefix.length);
+  const digest = await crypto.subtle.sign('HMAC', mac, signed);
+  return new Uint8Array(digest, 0, TAG_LENGTH);
+}
+
+function ctr(tag: Uint8Array<ArrayBuffer>): AesCtrParams {
+  const counter = new Uint8Array(16);
+  counter.set(tag);
+  return { name: 'AES-CTR', counter, length: COUNTER_BITS };
+}
+
+function sameBytes(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.length !== right.length) return false;
+  let difference = 0;
+  for (let index = 0; index < left.length; index++) {
+    difference |= (left[index] ?? 0) ^ (right[index] ?? 0);
+  }
+  return difference === 0;
+}
+
+async function transform(
+  bytes: Uint8Array<ArrayBuffer>,
+  stream: CompressionStream | DecompressionStream,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const source = new ReadableStream<Uint8Array<ArrayBuffer>>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+  const output = await new Response(source.pipeThrough(stream)).arrayBuffer();
+  return new Uint8Array(output);
+}
+
+function toBase64Url(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCodePoint(byte);
+  return btoa(binary)
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/[=]+$/, '');
+}
+
+function fromBase64Url(text: string): Uint8Array<ArrayBuffer> | null {
+  if (!/^[\w-]*$/.test(text) || text.length % 4 === 1) return null;
+  const base64 = text.replaceAll('-', '+').replaceAll('_', '/');
+  const binary = atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, '='));
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) {
+    bytes[index] = binary.codePointAt(index) ?? 0;
+  }
+  return bytes;
+}

package/src/share/core/sealedAddress.ts

@@ -0,0 +1,48 @@
+import type { PageLocation } from '../../router/core/pageAddress.ts';
+import { holdPageAddress } from '../../router/core/pageAddress.ts';
+
+import type { SealProblem } from './seal.ts';
+import { sealedToken, unsealQuery } from './seal.ts';
+
+/** How the page was opened. */
+export type SealedAddress =
+  | { status: 'plain' }
+  | { status: 'sealed' }
+  | { status: 'refused'; problem: SealProblem };
+
+let opensSealedAddresses = false;
+
+/**
+ * Open the page's address before anything reads it. A plain address is left
+ * as it is. A sealed one is unsealed and held in memory, so the page reads
+ * what the token carries through `pageLocation` while the address bar keeps
+ * showing the link that was handed out, whatever the page does next.
+ *
+ * Call it once at startup, and import every module that reads the address
+ * only once it has resolved. Calling it is also what lets the share dialog
+ * offer to protect a link: a site that never opens a sealed address must not
+ * hand one out.
+ * @param location - The address the page was opened at.
+ * @returns How the page was opened; on `refused` nothing is held.
+ */
+export async function openSealedAddress(
+  location: PageLocation | undefined = globalThis.location,
+): Promise<SealedAddress> {
+  opensSealedAddresses = true;
+  if (location === undefined) return { status: 'plain' };
+  const token = sealedToken(location.search);
+  if (token === null) return { status: 'plain' };
+  const result = await unsealQuery(token);
+  if (!result.ok) return { status: 'refused', problem: result.problem };
+  const query = result.query === '' ? '' : `?${result.query}`;
+  holdPageAddress(`${location.pathname}${query}${location.hash}`);
+  return { status: 'sealed' };
+}
+
+/**
+ * Whether this page opens sealed links, so may hand them out.
+ * @returns True once {@link openSealedAddress} has been called.
+ */
+export function canOpenSealedAddresses(): boolean {
+  return opensSealedAddresses;
+}

package/src/share/ui/SealedLinkRefused.tsx

@@ -0,0 +1,43 @@
+import { AnchorButton, NonIdealState } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+
+// A grid, because the card's own `height: 100%` keeps a flex row from
+// stretching it, and it would sit at the top of the page.
+const PAGE_STYLE: CSSProperties = {
+  display: 'grid',
+  minHeight: '100vh',
+  placeItems: 'center',
+};
+
+export interface SealedLinkRefusedProps {
+  /**
+   * Where the tool opens without the link.
+   * @default the path the link was opened at
+   */
+  href?: string;
+}
+
+/**
+ * What a page shows instead of itself when its sealed link cannot be opened —
+ * edited, cut, or minted by a newer key — so it never opens something the link
+ * did not say, and never a blank page.
+ * @param props - Where the tool opens without the link.
+ * @returns The whole page.
+ */
+export function SealedLinkRefused(props: SealedLinkRefusedProps): ReactElement {
+  const { href = globalThis.location?.pathname ?? '/' } = props;
+  const t = useChromeT();
+
+  return (
+    <div style={PAGE_STYLE}>
+      <NonIdealState
+        icon="lock"
+        title={t('seal.refusedTitle')}
+        description={t('seal.refusedBody')}
+        action={<AnchorButton href={href} text={t('seal.openWithout')} />}
+      />
+    </div>
+  );
+}

package/src/share/ui/ShareConfigOptions.tsx

@@ -21,6 +21,16 @@ export interface ShareConfigOptionsProps {
   descriptions: SharePartDescriptions;
   /** Called when the layout is switched. */
   onEmbedChange: (embed: boolean) => void;
+  /**
+   * Whether the link is handed out sealed.
+   * @default false
+   */
+  sealed?: boolean;
+  /**
+   * Called when sealing is switched. Without it the switch is not offered.
+   * @default undefined
+   */
+  onSealedChange?: (sealed: boolean) => void;
   /** Called with the part and whether the link should switch it off. */
   onPartChange: (part: string, hidden: boolean) => void;
   /** Called with the part the pointer is on, or `null` when it leaves. */
@@ -28,7 +38,8 @@ export interface ShareConfigOptionsProps {
 }
 
 /**
- * The switches of the share dialog: the layout, then one per part of the page.
+ * The switches of the share dialog: the layout — embedded, and sealed where the
+ * site opens sealed links — then one per part of the page.
  * @param props - The draft's layout and parts, and how to change them.
  * @returns The two sections.
  */
@@ -41,6 +52,8 @@ export function ShareConfigOptions(
     hidden,
     descriptions,
     onEmbedChange,
+    sealed = false,
+    onSealedChange,
     onPartChange,
     onPartPointed,
   } = props;
@@ -57,6 +70,15 @@ export function ShareConfigOptions(
           descriptions={descriptions}
           onChange={onEmbedChange}
         />
+        {onSealedChange === undefined ? null : (
+          <SharePartRow
+            label={t('share.protect')}
+            description={t('share.protectHint')}
+            on={sealed}
+            descriptions={descriptions}
+            onChange={onSealedChange}
+          />
+        )}
       </section>
 
       {parts.length > 0 ? (

package/src/share/ui/ShareDialogContent.tsx

@@ -15,6 +15,7 @@ import {
   applySharePreset,
   buildEmbedCode,
   buildShareUrl,
+  canOpenSealedAddresses,
   findSharePreset,
   isShareConfigured,
   parseShareConfig,
@@ -29,6 +30,7 @@ import { SharePanes } from './SharePanes.tsx';
 import { SharePresetTabs } from './SharePresetTabs.tsx';
 import { SharePreview } from './SharePreview.tsx';
 import { withPart } from './draft.ts';
+import { useSealedUrl } from './useSealedUrl.ts';
 
 const NO_PRESETS: readonly never[] = [];
 
@@ -73,6 +75,7 @@ export function ShareDialogContent<
   const [config, setConfig] = useState<ShareConfig<Codecs>>(() =>
     initialDraft(query, vocabulary, findPreset(presets, defaultPreset ?? null)),
   );
+  const [sealed, setSealed] = useState(false);
   const [pointed, setPointed] = useState<string | null>(null);
   const [presetKey, setPresetKey] = useState<string | null>(
     () => findSharePreset(config, presets, vocabulary)?.key ?? null,
@@ -86,6 +89,8 @@ export function ShareDialogContent<
 
   function setEmbed(embed: boolean): void {
     setConfig((previous) => ({ ...previous, embed }));
+    // A sealed page is always embedded, so leaving the frame drops the seal.
+    setSealed((previous) => previous && embed);
   }
 
   function setPartHidden(part: string, hidden: boolean): void {
@@ -118,19 +123,23 @@ export function ShareDialogContent<
     setPartHidden,
     setParam,
   };
-  const url = buildShareUrl({ base, search: query, config, vocabulary });
+  const shown = embeddedWhenSealed(config, sealed);
+  const url = buildShareUrl({ base, search: query, config: shown, vocabulary });
+  const { link, ready } = useSealedUrl(url, sealed);
   const frame = buildEmbedCode({
-    url,
+    url: link,
     title: frameTitle ?? title,
     height: frameHeight,
   });
   const options = (
     <ShareConfigOptions
-      embed={config.embed}
-      parts={visibleShareParts(vocabulary.parts, config.embed)}
+      embed={shown.embed}
+      parts={visibleShareParts(vocabulary.parts, shown.embed)}
       hidden={config.hidden}
       descriptions={partDescriptions}
       onEmbedChange={setEmbed}
+      sealed={sealed}
+      onSealedChange={offeredWhenOpened(setSealed)}
       onPartChange={setPartHidden}
       onPartPointed={setPointed}
     />
@@ -155,7 +164,7 @@ export function ShareDialogContent<
 
   const previewPane = preview ? (
     <SharePreview
-      url={url}
+      url={link}
       title={frameTitle ?? title}
       highlight={highlightOf(vocabulary.parts, pointed)}
     />
@@ -181,12 +190,34 @@ export function ShareDialogContent<
         />
       </div>
       <DialogFooter
-        actions={<ShareLinkBar url={url} frame={frame} onCopied={onClose} />}
+        actions={
+          <ShareLinkBar
+            url={link}
+            frame={frame}
+            disabled={!ready}
+            onCopied={onClose}
+          />
+        }
       />
     </>
   );
 }
 
+// A sealed page is always embedded, whatever a preset said.
+function embeddedWhenSealed<Codecs extends ShareParamCodecs>(
+  config: ShareConfig<Codecs>,
+  sealed: boolean,
+): ShareConfig<Codecs> {
+  return sealed ? { ...config, embed: true } : config;
+}
+
+// A site that never opens a sealed address must not hand one out.
+function offeredWhenOpened(
+  setSealed: (sealed: boolean) => void,
+): ((sealed: boolean) => void) | undefined {
+  return canOpenSealedAddresses() ? setSealed : undefined;
+}
+
 function initialDraft<Codecs extends ShareParamCodecs>(
   search: string,
   vocabulary: ShareVocabulary<Codecs>,

package/src/share/ui/ShareLinkBar.tsx

@@ -15,6 +15,11 @@ export interface ShareLinkBarProps {
    * @default undefined
    */
   onCopied?: () => void;
+  /**
+   * Whether the link is not ready to hand out yet, as while it is being sealed.
+   * @default false
+   */
+  disabled?: boolean;
 }
 
 /**
@@ -31,7 +36,7 @@ export interface ShareLinkBarProps {
  * @returns The bar.
  */
 export function ShareLinkBar(props: ShareLinkBarProps): ReactElement {
-  const { url, frame, onCopied } = props;
+  const { url, frame, onCopied, disabled = false } = props;
   const t = useChromeT();
 
   return (
@@ -46,6 +51,7 @@ export function ShareLinkBar(props: ShareLinkBarProps): ReactElement {
           content={url}
           label={t('share.copyLink')}
           title=""
+          disabled={disabled}
           onCopied={onCopied}
         />
       </HelpTooltip>
@@ -59,6 +65,7 @@ export function ShareLinkBar(props: ShareLinkBarProps): ReactElement {
           icon="share"
           text={t('share.openInNewTab')}
           href={url}
+          disabled={disabled}
           target="_blank"
           rel="noopener noreferrer"
         />
@@ -74,6 +81,7 @@ export function ShareLinkBar(props: ShareLinkBarProps): ReactElement {
           icon="code"
           label={t('share.copyIframe')}
           title=""
+          disabled={disabled}
           onCopied={onCopied}
         />
       </HelpTooltip>

package/src/share/ui/index.ts

@@ -3,6 +3,8 @@ export { HiddenPartsProvider } from './HiddenPartsProvider.tsx';
 export { useIsHidden } from './hiddenParts.ts';
 export type { PagePartProps } from './PagePart.tsx';
 export { PagePart } from './PagePart.tsx';
+export type { SealedLinkRefusedProps } from './SealedLinkRefused.tsx';
+export { SealedLinkRefused } from './SealedLinkRefused.tsx';
 export type { ShareButtonProps, ShareButtonVariant } from './ShareButton.tsx';
 export { ShareButton } from './ShareButton.tsx';
 export type { ShareDialogProps } from './ShareDialog.tsx';

package/src/share/ui/useSealedUrl.ts

@@ -0,0 +1,40 @@
+import { useEffect, useState } from 'react';
+
+import { sealShareUrl } from '../core/index.ts';
+
+/** The link the dialog hands out, and whether it may be handed out yet. */
+export interface SealedUrl {
+  /** The link: sealed when asked and ready, else the share link itself. */
+  link: string;
+  /** False while the link is being sealed, when only the plain one exists. */
+  ready: boolean;
+}
+
+/**
+ * The link the dialog hands out: the share link itself, or its sealed form.
+ * Sealing is asynchronous, so a sealed link is not ready at once, and a link
+ * sealed for an older draft is never answered for the current one.
+ * @param url - The share link.
+ * @param sealed - Whether to hand out its sealed form.
+ * @returns The link, and whether it is ready.
+ */
+export function useSealedUrl(url: string, sealed: boolean): SealedUrl {
+  const [result, setResult] = useState<{ from: string; to: string } | null>(
+    null,
+  );
+
+  useEffect(() => {
+    if (!sealed) return;
+    let current = true;
+    void sealShareUrl(url).then((to) => {
+      if (current) setResult({ from: url, to });
+    });
+    return () => {
+      current = false;
+    };
+  }, [url, sealed]);
+
+  if (!sealed) return { link: url, ready: true };
+  if (result?.from === url) return { link: result.to, ready: true };
+  return { link: url, ready: false };
+}