@tinvar/react 0.0.0-stage → 0.4.1

package/src/remember-store.js

@@ -0,0 +1,486 @@
+// Where remembered state is kept: per tab, per history entry, per session.
+//
+// tinvar-spec.md, "Client-held data": it "is bound to (user, tenant). It is
+// cleared, with a full page load, on logout ... and session revocation ...
+// Any mismatch between stored and current user or tenant also purges it."
+//
+// history.state cannot: the router can only write the entry it is on, so a
+// value left in any other entry's state outlives the session in plaintext,
+// for as long as the tab keeps its history -- merely unread. So the values
+// live here instead, in sessionStorage -- which survives a reload and back
+// and forward into the document, and dies with the tab -- under one key, as
+// one map bound to one session. Entries are found by the key the router
+// writes into each history entry's state; the state itself holds no values.
+//
+// The whole map belongs to one binding. Reading under another one wipes it,
+// and so does the router on every binding change and every 401, so nothing
+// remembered under a session can be read, carried over or found in storage
+// once that session has ended or changed -- as far as this tab has heard.
+//
+// History encryption covers what it has not heard (ADR 0019). An entry whose
+// page came with a history key is sealed with it -- AES-GCM, by a key the
+// server derives for the session and the browser imports as one it cannot
+// export -- and kept under `sealed` rather than `entries`. A tab restored
+// with its storage after the session ended, a session that ended elsewhere,
+// a copy of the storage taken off the disk: each finds ciphertext whose key
+// the server hands to no one but that session. An entry whose page came
+// with none -- not signed in, or opted out -- is kept as before, in the
+// clear, under `entries`.
+//
+// Values are stored as JSON. One that does not survive JSON is not
+// remembered faithfully; keep remembered state to plain data.
+
+/** The sessionStorage key the map is kept under. */
+export const REMEMBER_STORAGE_KEY = 'tinvar:remember';
+
+/** How many history entries' values are kept; the oldest go first. */
+export const MAX_REMEMBERED_ENTRIES = 50;
+
+/**
+ * Puts `value` in a map by history entry as its newest, dropping the oldest
+ * past MAX_REMEMBERED_ENTRIES -- what the router keeps by entry in memory
+ * (scroll positions, scroll regions, list anchors) is held to the same limit
+ * as what it keeps here. A Map keeps insertion order, so the oldest is the
+ * first key.
+ *
+ * @template V
+ * @param {Map<string, V>} map
+ * @param {string} entry
+ * @param {V} value
+ */
+export function keepNewest(map, entry, value) {
+  map.delete(entry);
+  map.set(entry, value);
+  while (map.size > MAX_REMEMBERED_ENTRIES) {
+    const oldest = map.keys().next();
+    if (oldest.done === true) break;
+    map.delete(oldest.value);
+  }
+}
+
+/** AES-GCM's nonce, in bytes: random for every seal. */
+const IV_BYTES = 12;
+
+/** A history key's length, in bytes: AES-256. */
+const KEY_BYTES = 32;
+
+/**
+ * @typedef {{
+ *   binding: string,
+ *   order: string[],
+ *   entries: Record<string, Record<string, unknown>>,
+ *   sealed?: Record<string, string>,
+ * }} StoredMap
+ *
+ * A page's history key, imported -- null when it could not be: no
+ * `crypto.subtle` (an insecure context), or a key that is not one.
+ * @typedef {Promise<CryptoKey | null>} HistoryKey
+ *
+ * @typedef {{
+ *   read(entry: string, binding: string | null): Record<string, unknown>,
+ *   isSealed(entry: string, binding: string | null): boolean,
+ *   open(entry: string, binding: string | null, key: HistoryKey | null): Promise<Record<string, unknown>>,
+ *   write(entry: string, binding: string | null, values: Record<string, unknown>, key?: HistoryKey | null): Promise<void>,
+ *   wipe(): void,
+ * }} RememberStore
+ */
+
+/**
+ * The tab's sessionStorage, or null where it cannot be used -- a sandboxed
+ * frame, storage switched off -- which throws on mere access.
+ *
+ * @param {Window | undefined} win
+ * @returns {Storage | null}
+ */
+export function tabStorage(win) {
+  try {
+    const storage = win?.sessionStorage ?? null;
+    if (storage === null) return null;
+    // Some browsers hand out a storage that throws on the first write.
+    storage.setItem(`${REMEMBER_STORAGE_KEY}:probe`, '1');
+    storage.removeItem(`${REMEMBER_STORAGE_KEY}:probe`);
+    return storage;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Imports a history key as the server sends it -- 32 bytes, base64url -- for
+ * AES-GCM, as a key script cannot export: the raw bytes are not kept by the
+ * router once imported, and are never written anywhere.
+ *
+ * @param {string} encoded
+ * @param {Crypto | undefined} [crypto]
+ * @returns {HistoryKey} null without `crypto.subtle`, or for a key that is not one
+ */
+export async function importHistoryKey(encoded, crypto = globalThis.crypto) {
+  const subtle = crypto?.subtle;
+  const bytes = fromBase64Url(encoded);
+  if (!subtle || bytes === null || bytes.length !== KEY_BYTES) return null;
+  try {
+    return await subtle.importKey('raw', bytes, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A store over a Storage, or over memory alone when there is none -- kept
+ * only for this document then, which is still bound and still wiped.
+ *
+ * @param {Storage | null} storage
+ * @param {Crypto | undefined} [crypto] what seals and opens entries
+ * @returns {RememberStore}
+ */
+export function createRememberStore(storage, crypto = globalThis.crypto) {
+  /** @type {StoredMap | null} */
+  let memory = null;
+
+  /**
+   * Bumped by every wipe. A seal still under way when the map is wiped
+   * belongs to what was wiped, and is never written after it.
+   */
+  let generation = 0;
+
+  /**
+   * The newest write to each entry. Sealing takes time, and a later write
+   * -- sealed or not -- must not be overwritten by an earlier one that
+   * finished after it.
+   *
+   * @type {Map<string, number>}
+   */
+  const newest = new Map();
+  let writes = 0;
+
+  /**
+   * Sealed writes, by entry: one is sealed at a time, and the newest asked
+   * for meanwhile waits as `pending`, replacing any that waited before it.
+   * A sealed write goes out at once rather than on the debounce, so each
+   * keystroke in a remembered field asks for one; sealed and stored each
+   * time, the map was encrypted and rewritten once a keystroke.
+   *
+   * @type {Map<string, { pending: { job: () => Promise<void>, resolve: () => void } | null }>}
+   */
+  const lanes = new Map();
+
+  /**
+   * Runs a sealed write for an entry now, or once the one being sealed for
+   * it settles. A write replaced while it waits settles with the one that
+   * replaced it.
+   *
+   * @param {string} entry
+   * @param {() => Promise<void>} job
+   * @returns {Promise<void>}
+   */
+  function inTurn(entry, job) {
+    const lane = lanes.get(entry);
+    if (lane !== undefined) {
+      const replaced = lane.pending;
+      const settled = new Promise((resolve) => {
+        lane.pending = { job, resolve: () => resolve(undefined) };
+      });
+      if (replaced !== null) void settled.then(replaced.resolve);
+      return /** @type {Promise<void>} */ (settled);
+    }
+    const created = { pending: null };
+    lanes.set(entry, created);
+    return drain(entry, created, job);
+  }
+
+  /**
+   * @param {string} entry
+   * @param {{ pending: { job: () => Promise<void>, resolve: () => void } | null }} lane
+   * @param {() => Promise<void>} job
+   * @returns {Promise<void>}
+   */
+  async function drain(entry, lane, job) {
+    try {
+      await job();
+    } catch {
+      // Nothing more can be done about a write that failed.
+    }
+    const next = lane.pending;
+    lane.pending = null;
+    if (next === null) {
+      lanes.delete(entry);
+      return;
+    }
+    void drain(entry, lane, next.job).then(next.resolve);
+  }
+
+  /** @returns {StoredMap | null} */
+  function load() {
+    if (storage === null) return memory;
+    let raw;
+    try {
+      raw = storage.getItem(REMEMBER_STORAGE_KEY);
+    } catch {
+      return null;
+    }
+    if (raw === null) return null;
+    try {
+      const data = JSON.parse(raw);
+      if (
+        typeof data?.binding === 'string' &&
+        Array.isArray(data.order) &&
+        isRecord(data.entries) &&
+        (data.sealed === undefined || isRecord(data.sealed))
+      ) {
+        return data;
+      }
+    } catch {
+      // Not ours, or damaged: dropped below.
+    }
+    wipe();
+    return null;
+  }
+
+  /** @param {StoredMap} data */
+  function save(data) {
+    // Absent when empty: a tab with nothing sealed keeps the map it always kept.
+    if (data.sealed !== undefined && Object.keys(data.sealed).length === 0) delete data.sealed;
+    if (storage === null) {
+      memory = data;
+      return;
+    }
+    try {
+      storage.setItem(REMEMBER_STORAGE_KEY, JSON.stringify(data));
+    } catch {
+      // Full, or a value JSON cannot hold: what was there stays, as of the
+      // last write that worked.
+    }
+  }
+
+  function wipe() {
+    generation++;
+    memory = null;
+    try {
+      storage?.removeItem(REMEMBER_STORAGE_KEY);
+    } catch {
+      // Nothing more can be done about storage that refuses.
+    }
+  }
+
+  /**
+   * Puts an entry's values in the map -- in the clear, or sealed, or not at
+   * all when both are null -- as its newest, and drops the oldest past the
+   * limit.
+   *
+   * @param {StoredMap} data
+   * @param {string} entry
+   * @param {Record<string, unknown> | null} values
+   * @param {string | null} sealed
+   */
+  function place(data, entry, values, sealed) {
+    data.order = data.order.filter((key) => key !== entry);
+    delete data.entries[entry];
+    if (data.sealed !== undefined) delete data.sealed[entry];
+
+    if (sealed !== null) {
+      data.sealed = { ...(data.sealed ?? {}), [entry]: sealed };
+      data.order.push(entry);
+    } else if (values !== null && Object.keys(values).length > 0) {
+      data.entries[entry] = values;
+      data.order.push(entry);
+    }
+
+    while (data.order.length > MAX_REMEMBERED_ENTRIES) {
+      const oldest = data.order.shift();
+      if (oldest === undefined) continue;
+      delete data.entries[oldest];
+      if (data.sealed !== undefined) delete data.sealed[oldest];
+    }
+    save(data);
+  }
+
+  return {
+    read(entry, binding) {
+      if (binding === null) return {};
+      const data = load();
+      if (data === null) return {};
+      // Kept under another session: it is purged, never read.
+      if (data.binding !== binding) {
+        wipe();
+        return {};
+      }
+      return valuesIn(data.entries[entry]);
+    },
+
+    isSealed(entry, binding) {
+      if (binding === null) return false;
+      const data = load();
+      return data !== null && data.binding === binding && typeof data.sealed?.[entry] === 'string';
+    },
+
+    async open(entry, binding, key) {
+      if (binding === null) return {};
+      const data = load();
+      if (data === null) return {};
+      if (data.binding !== binding) {
+        wipe();
+        return {};
+      }
+
+      const sealed = data.sealed?.[entry];
+      if (typeof sealed !== 'string') return valuesIn(data.entries[entry]);
+
+      // A page with no key -- since opted out, say -- cannot open what an
+      // encrypted one sealed, and leaves it for that page's next write.
+      const at = generation;
+      const imported = key === null ? null : await key;
+      if (imported === null) return {};
+
+      const values = await unseal(crypto, imported, binding, entry, sealed);
+      // Wiped while it was being opened: the session it was kept for ended.
+      if (at !== generation) return {};
+      if (values !== null) return values;
+
+      // Sealed under another key -- another session's, or moved here from
+      // another entry -- so it never opens under this one: dropped, not kept
+      // to be tried again. Unless it has been replaced since.
+      const now = load();
+      if (now !== null && now.sealed?.[entry] === sealed) place(now, entry, null, null);
+      return {};
+    },
+
+    async write(entry, binding, values, key = null) {
+      // No session to bind it to: nothing is kept.
+      if (binding === null) return;
+
+      const mine = ++writes;
+      newest.set(entry, mine);
+
+      if (key === null || Object.keys(values).length === 0) {
+        let data = load();
+        if (data === null || data.binding !== binding) data = { binding, order: [], entries: {} };
+        place(data, entry, values, null);
+        return;
+      }
+
+      const at = generation;
+      // Wiped meanwhile -- the session ended, or changed -- or written again
+      // since: this seal is of something no longer wanted.
+      const unwanted = () => at !== generation || newest.get(entry) !== mine;
+
+      return inTurn(entry, async () => {
+        if (unwanted()) return;
+        let sealed = null;
+        try {
+          const imported = await key;
+          if (imported !== null) sealed = await seal(crypto, imported, binding, entry, values);
+        } catch {
+          // A value JSON cannot hold, or a key the browser would not use:
+          // what is in the map for the entry is decided below.
+        }
+        if (unwanted()) return;
+
+        let data = load();
+        if (data !== null && data.binding !== binding) return;
+        data ??= { binding, order: [], entries: {} };
+
+        // A page that is to be sealed and cannot be keeps nothing: never its
+        // values in the clear, nor what an earlier write left for the entry.
+        place(data, entry, null, sealed);
+      });
+    },
+
+    wipe,
+  };
+}
+
+/**
+ * @param {unknown} values
+ * @returns {Record<string, unknown>}
+ */
+function valuesIn(values) {
+  return isRecord(values) ? /** @type {Record<string, unknown>} */ (values) : {};
+}
+
+/** @param {unknown} value */
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * What a sealed entry is bound to besides its key: the session and the
+ * entry it was sealed for. Ciphertext copied into another entry, or into a
+ * map under another session, does not open.
+ *
+ * @param {string} binding
+ * @param {string} entry
+ */
+function boundTo(binding, entry) {
+  return new TextEncoder().encode(JSON.stringify(['tinvar:remember', binding, entry]));
+}
+
+/**
+ * @param {Crypto | undefined} crypto
+ * @param {CryptoKey} key
+ * @param {string} binding
+ * @param {string} entry
+ * @param {Record<string, unknown>} values
+ * @returns {Promise<string>} the nonce and the ciphertext, base64url
+ */
+async function seal(crypto, key, binding, entry, values) {
+  if (!crypto?.subtle) throw new Error('No crypto.subtle to seal with.');
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const cipher = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv, additionalData: boundTo(binding, entry) },
+    key,
+    new TextEncoder().encode(JSON.stringify(values)),
+  );
+  const out = new Uint8Array(IV_BYTES + cipher.byteLength);
+  out.set(iv);
+  out.set(new Uint8Array(cipher), IV_BYTES);
+  return toBase64Url(out);
+}
+
+/**
+ * @param {Crypto | undefined} crypto
+ * @param {CryptoKey} key
+ * @param {string} binding
+ * @param {string} entry
+ * @param {string} sealed
+ * @returns {Promise<Record<string, unknown> | null>} null when it does not open
+ */
+async function unseal(crypto, key, binding, entry, sealed) {
+  const bytes = fromBase64Url(sealed);
+  if (!crypto?.subtle || bytes === null || bytes.length <= IV_BYTES) return null;
+  try {
+    const plain = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv: bytes.slice(0, IV_BYTES), additionalData: boundTo(binding, entry) },
+      key,
+      bytes.slice(IV_BYTES),
+    );
+    const values = JSON.parse(new TextDecoder().decode(plain));
+    return isRecord(values) ? values : null;
+  } catch {
+    return null;
+  }
+}
+
+/** @param {Uint8Array} bytes */
+function toBase64Url(bytes) {
+  // A character at a time: spreading a large array into fromCharCode
+  // overflows the stack.
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * @param {unknown} encoded
+ * @returns {Uint8Array | null}
+ */
+function fromBase64Url(encoded) {
+  if (typeof encoded !== 'string' || !/^[A-Za-z0-9_-]+$/.test(encoded)) return null;
+  try {
+    const binary = atob(encoded.replace(/-/g, '+').replace(/_/g, '/'));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  } catch {
+    return null;
+  }
+}

package/src/rescue.d.ts

@@ -0,0 +1,10 @@
+/** What a #[Rescue] field that threw is sent as. See ADR 0017. */
+export interface Rescued {
+  /** The digest the failure was logged under, to quote to support. */
+  readonly $rescued: string;
+}
+
+export declare const RESCUED_KEY: '$rescued';
+
+/** Whether a field was rescued rather than resolved; narrows `T | Rescued` to either side. */
+export declare function isRescued(value: unknown): value is Rescued;

package/src/rescue.js

@@ -0,0 +1,30 @@
+// What a rescued field arrives as.
+//
+// tinvar-spec.md, "Rescue and reloading": "A deferred or lazy field marked
+// `rescue` that throws is reported to the PHP exception handler and
+// omitted." A Lazy field marked #[Rescue] whose resolver threw is sent as
+// `{"$rescued": "<digest>"}`, and codegen types it `T | Rescued` (ADR 0017),
+// so a component has to say what it shows instead before it can read the
+// value.
+//
+// No React and no DOM: a page's server component reads its own data, so
+// this has to import cleanly in either environment.
+
+/** Mirrors Encoder::RESCUED_KEY. */
+export const RESCUED_KEY = '$rescued';
+
+/**
+ * Whether a field was rescued rather than resolved.
+ *
+ * Exactly one key: a Data object never encodes to a map with a `$` key -- no
+ * PHP property can be named that way -- but a rescued map field's own value
+ * could, by chance, carry one among others.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isRescued(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  return keys.length === 1 && keys[0] === RESCUED_KEY && typeof value[RESCUED_KEY] === 'string';
+}