neural-consent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Le Vain Bey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# neural-consent
+
+**Purpose-granular consent records with a tamper-evident local event log** for tools that read a neural or assistive signal on the user's own device. Zero dependencies. Runs in the browser and in Node.
+
+```bash
+npm install neural-consent
+```
+
+```js
+import { ConsentManager, PURPOSES, DISCLAIMER } from 'neural-consent';
+
+const consent = new ConsentManager({ storage: localStorage });
+
+// The gate. Processing must not happen without this passing.
+if (consent.isGranted(PURPOSES.ACQUIRE_SIGNAL.id)) {
+  startReadingSignal();
+}
+```
+
+---
+
+## What this is not
+
+**This is not a compliance solution, and it does not claim to be one.** That sentence is the most important one in this README.
+
+Whether a privacy statute applies to a given tool depends on facts about whoever *publishes* it — their revenue, how many people use it, and where those people live — not on what the code does. A consent screen cannot change that. The shipped `DISCLAIMER` says so in the words the tool should show its users, and a test asserts that it never contains the phrases *"CCPA compliant"*, *"GDPR compliant"*, *"HIPAA compliant"*, *"FDA cleared"*, *"certified"*, or *"privacy-compliant by architecture"*.
+
+A comparable project markets itself as "privacy-compliant by architecture — not by policy." No library can make that claim. Architecture is evidence; compliance is a legal conclusion that depends on facts outside the code.
+
+## The thing that is actually true
+
+A tool that never transmits the signal **has no third party to share it with, nothing to sell, and no database to breach.** That is a verifiable statement about the software — you can open your browser's network panel and watch that nothing leaves.
+
+This module records that as a machine-readable field rather than a promise:
+
+```js
+record.handling = {
+  storage: 'local-only',
+  recipients: [],
+  recipientsDeclaration: 'none — no transmission',
+}
+```
+
+## The gate actually gates
+
+A consent screen that records a decision but does not prevent processing is documentation, not consent. So the API is shaped as a gate, and `require()` **throws** rather than returning a falsy value — a silently-skipped permission check is how consent gets bypassed by accident:
+
+```js
+consent.require(PURPOSES.PROCESS_LOCALLY.id); // throws ConsentRequiredError
+```
+
+## Purposes are separate
+
+Granularity is deliberate. Both ISO/IEC TS 27560 and the state laws require **purpose limitation**: consent to one thing must not silently authorise another. There is no bundled "I agree."
+
+| Purpose | What it covers |
+|---|---|
+| `acquire_signal` | reading the switch / gaze / EEG signal |
+| `process_locally` | processing it on the device |
+| `persist_locally` | remembering settings between sessions |
+| `export` | the user saving their own data to a file |
+
+There is deliberately no *analytics* or *improve our services* purpose — including a purpose you do not use is its own kind of dishonesty.
+
+## Withdrawal is immediate and symmetric
+
+```js
+consent.withdraw(PURPOSES.ACQUIRE_SIGNAL.id); // takes effect now
+consent.withdrawAll();                        // the "turn it all off" path
+consent.isGranted(id);                        // false
+```
+
+Withdrawal is recorded as an event, not as an amendment. Consent also **lapses**: grants carry a validity window, and a stale record is expired on load rather than silently remaining valid. `reaffirm()` renews deliberately.
+
+## The event log is tamper-evident, not tamper-proof
+
+Each event carries the hash of the previous one, so altering or removing a past entry breaks the chain and `verify()` reports where:
+
+```js
+const { ok, brokenAt } = record.verify();
+```
+
+**Be clear about what this does and does not do.** Anyone with access to their own device can rewrite the whole file — that is inherent to local-first storage and pretending otherwise would be a lie. The chain's job is to make *accidental or partial* modification detectable, and to give a user a way to check their own record was not quietly changed by the tool.
+
+The hash is FNV-1a (32-bit), not a cryptographic digest, because this runs in a browser with zero dependencies and WebCrypto's digest is async. 32 bits is the right size for detecting accidental modification. It is not a security hash.
+
+## Structured per ISO/IEC TS 27560 — with documented departures
+
+The field set follows ISO/IEC TS 27560:2023's consent record model (mandatory fields are public via the W3C Data Privacy Vocabularies and Controls CG guide, published 2026-02-15).
+
+Two deliberate departures, both recorded in the output rather than silently omitted:
+
+```js
+handling.omittedFields = ['pii_controller_address', 'jurisdiction', 'authority_party']
+```
+
+Those 27560 fields exist to let one organisation's consent records be read by another. A local-first tool exchanges nothing with anyone, so carrying a controller address would be theatre. A reviewer can see the decision instead of guessing at an absence.
+
+Kept, because they earn their place: schema version, record id, subject id, the **notice version actually shown**, language, purpose, data types, a `neural` sensitivity flag, grant time, validity duration, the named withdrawal path, and the full event log.
+
+## Accessibility is a requirement, not a nicety
+
+This module serves tools built *for* disabled users. A consent flow that a screen-reader user cannot operate is self-refuting, so the demo is keyboard-operable with labelled controls and plain-language text. The notice model is layered — a concise key-information panel first, full detail available behind it — which is both the Common Rule's explicit model (45 CFR 46.116(a)(5)(i)) and what accessibility practice wants: a user should hear five lines before deciding, not a wall of text.
+
+## Demo
+
+```bash
+python -m http.server 8796
+# open http://127.0.0.1:8796/demo/
+```
+
+## Tests
+
+```bash
+npm test
+```
+
+28 tests, zero dependencies, `node:test`. The clock is injected everywhere, so validity-window and expiry behaviour is deterministic.
+
+## What the research says about applicability
+
+Verified against primary sources (September 2026):
+
+- **Colorado HB24-1058** — in force 2024-08-07; adds neural data to the CPA's sensitive-data category requiring **opt-in** consent. Its "biological data" trigger only bites when the data is used for **identification**, which FPF notes "significantly narrow[s]" its scope for ordinary neural data.
+- **California SB 1223** — operative 2025-01-01; neural data is sensitive personal information, giving a right to limit use.
+- **Connecticut PA 25-113** (in force 2026-07-01) — note the sensitive-data trigger has **no consumer-count minimum**.
+- **Vermont S.71** (signed 2026-06-16, effective 2028-01-01) — third threshold regime, 3,000 consumers' sensitive data.
+- **Washington's My Health My Data Act** — **no thresholds at all, and a private right of action.** This is the jurisdiction where an overclaimed privacy policy creates the most exposure.
+- **No federal neural-data statute.** The MIND Act (S.2925) would only direct an FTC study and has not advanced. FTC Act Section 5 remains the live federal instrument — which is precisely why *claims* matter, whether or not a privacy statute applies.
+
+**No statute addresses on-device-only processing.** The argument that a tool which never receives data does not "collect" or "process" it is an interpretation, not settled law. This module is built so that the interpretation is at least easy to defend — and never asserted as established.
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "neural-consent",
+  "version": "0.1.0",
+  "description": "Purpose-granular consent records with a tamper-evident local event log for neural-data tools. Local-first, zero dependencies. Structured on the ISO/IEC TS 27560 field model — and explicit about what it does not claim.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./record.js": "./src/record.js",
+    "./notices.js": "./src/notices.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/consent.test.mjs"
+  },
+  "keywords": [
+    "consent",
+    "neural-data",
+    "neurotech",
+    "bci",
+    "privacy",
+    "consent-record",
+    "iso-27560",
+    "local-first",
+    "accessibility",
+    "a11y"
+  ],
+  "license": "MIT",
+  "author": "Le Vain Bey",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LE-VAI/neural-consent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/LE-VAI/neural-consent/issues"
+  },
+  "homepage": "https://github.com/LE-VAI/neural-consent#readme",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/consent.js

@@ -0,0 +1,255 @@
+/**
+ * consent.js — the manager a tool actually talks to.
+ *
+ * The point of this layer is that the REST of the tool asks permission before
+ * doing anything with a signal. A consent screen that records a decision but
+ * does not gate behaviour is documentation, not consent. So the API is shaped
+ * as a gate:
+ *
+ *   if (!consent.isGranted(PURPOSES.ACQUIRE_SIGNAL.id)) return;  // do not read
+ *
+ * and `require()` throws rather than returning a falsy value, because a
+ * silently-skipped permission check is how consent gets bypassed by accident.
+ *
+ * PERSISTENCE IS OPTIONAL AND LOCAL. When a storage object is supplied the
+ * record is written to it; when it is not, everything lives in memory for the
+ * session. No network path exists in this module at all — there is no fetch,
+ * no beacon, no endpoint configuration. That absence is the feature: it is
+ * what makes the "recipients: none" declaration in the record true rather
+ * than aspirational.
+ */
+
+import { ConsentRecord, generateId } from './record.js';
+import { PURPOSES, DISCLAIMER, noticeVersion, purposeById } from './notices.js';
+
+export { PURPOSES, DISCLAIMER, noticeVersion, purposeById };
+
+export class ConsentManager {
+  /**
+   * @param {object} [options]
+   * @param {object} [options.storage] an object with getItem/setItem/removeItem
+   *   (e.g. window.localStorage). Omit for in-memory only.
+   * @param {string} [options.storageKey='neural-consent.record']
+   * @param {string} [options.recordId]
+   * @param {Function} [options.now] injected clock
+   * @param {number} [options.validDays=365] validity window for a grant
+   * @param {string} [options.language='en']
+   */
+  constructor(options = {}) {
+    this.storage = options.storage ?? null;
+    this.storageKey = options.storageKey ?? 'neural-consent.record';
+    this.validDays = options.validDays ?? 365;
+    this.language = options.language ?? 'en';
+    this.recordId = options.recordId ?? null;
+    this._now = options.now ?? (() => Date.now());
+
+    /** Change listeners — a UI subscribes to re-render on any decision. */
+    this._listeners = new Set();
+
+    this.record = this._load();
+    // Consent should lapse. Expiring on load means a record that sat unused
+    // past its window is correctly inert rather than silently still valid.
+    const lapsed = this.record.expireLapsed();
+    if (lapsed.length) this._emit({ type: 'expired', purposes: lapsed });
+  }
+
+  // -- the gate --------------------------------------------------------------
+
+  /** True only while consent is currently held for the purpose. */
+  isGranted(purposeId) {
+    return this.record.isGranted(purposeId);
+  }
+
+  /**
+   * Throw unless consent is held. Use this where processing must not happen
+   * without it — a falsy return that a caller forgets to check is how a gate
+   * silently stops gating.
+   */
+  require(purposeId) {
+    if (!this.isGranted(purposeId)) {
+      throw new ConsentRequiredError(purposeId);
+    }
+    return true;
+  }
+
+  /** Every purpose currently granted. */
+  granted() {
+    return this.record.grantedPurposes();
+  }
+
+  /**
+   * Grant consent for a purpose. The notice version shown MUST be passed in
+   * by the UI — the manager will not guess it, because the record has to
+   * reflect the text the person actually read.
+   *
+   * @param {string} purposeId
+   * @param {object} [meta]
+   * @param {string} meta.noticeVersion
+   */
+  grant(purposeId, meta = {}) {
+    if (!purposeById(purposeId)) throw new Error(`unknown purpose: ${purposeId}`);
+    const event = this.record.decide(purposeId, 'given', {
+      noticeVersion: meta.noticeVersion ?? noticeVersion(),
+      language: meta.language ?? this.language,
+      validDays: meta.validDays ?? this.validDays,
+      dataTypes: meta.dataTypes ?? [],
+      withdrawalMethod: meta.withdrawalMethod,
+    });
+    this._persist();
+    this._emit({ type: 'grant', purposeId });
+    return event;
+  }
+
+  /** Decline a purpose. Refusal is recorded, not discarded. */
+  refuse(purposeId, meta = {}) {
+    if (!purposeById(purposeId)) throw new Error(`unknown purpose: ${purposeId}`);
+    const event = this.record.decide(purposeId, 'refused', {
+      noticeVersion: meta.noticeVersion ?? noticeVersion(),
+      language: meta.language ?? this.language,
+    });
+    this._persist();
+    this._emit({ type: 'refuse', purposeId });
+    return event;
+  }
+
+  /** Withdraw a grant. Immediate, symmetric, and logged. */
+  withdraw(purposeId, meta = {}) {
+    const event = this.record.withdraw(purposeId, meta);
+    if (event) {
+      this._persist();
+      this._emit({ type: 'withdraw', purposeId });
+    }
+    return event;
+  }
+
+  /**
+   * Re-affirm an existing grant, resetting its validity window.
+   *
+   * Colorado's rules require periodic consent refresh for sensitive data, and
+   * a validity window that can only expire — never renew — would leave a user
+   * re-consenting from scratch every cycle. Re-affirmation is the same
+   * decision, re-taken deliberately, recorded as its own event.
+   */
+  reaffirm(purposeId, meta = {}) {
+    if (!purposeById(purposeId)) throw new Error(`unknown purpose: ${purposeId}`);
+    const existing = this.record.purposes[purposeId];
+    if (!existing) throw new Error(`no consent recorded for purpose: ${purposeId}`);
+    const event = this.record.decide(purposeId, 'given', {
+      noticeVersion: meta.noticeVersion ?? existing.noticeVersion,
+      language: meta.language ?? this.language,
+      validDays: meta.validDays ?? this.validDays,
+      dataTypes: meta.dataTypes ?? existing.dataTypes,
+      withdrawalMethod: meta.withdrawalMethod ?? existing.withdrawalMethod,
+    });
+    this._persist();
+    this._emit({ type: 'reaffirm', purposeId });
+    return event;
+  }
+
+  /** Withdraw everything at once — the "turn it all off" path. */
+  withdrawAll(meta = {}) {
+    const ids = this.granted();
+    const events = ids.map((id) => this.record.withdraw(id, meta)).filter(Boolean);
+    if (events.length) {
+      this._persist();
+      this._emit({ type: 'withdraw-all', purposes: ids });
+    }
+    return events;
+  }
+
+  // -- inspection ------------------------------------------------------------
+
+  /** State of one purpose, or null if never decided. */
+  stateOf(purposeId) {
+    return this.record.purposes[purposeId]?.state ?? null;
+  }
+
+  /** A snapshot the UI renders from. Includes the disclaimer, always. */
+  snapshot() {
+    const granted = this.record.grantedPurposes();
+    return {
+      recordId: this.record.recordId,
+      createdAt: this.record.createdAt,
+      // The gate's answer, so a UI does not have to re-derive it and get it
+      // wrong. A consent screen that shows the wrong state is worse than none.
+      granted,
+      purposes: Object.values(PURPOSES).map((p) => ({
+        id: p.id,
+        label: p.label,
+        keyText: p.keyText,
+        detailText: p.detailText,
+        version: p.version,
+        state: this.stateOf(p.id),
+        entry: this.record.purposes[p.id] ?? null,
+      })),
+      disclaimer: DISCLAIMER,
+      handling: this.record.handling,
+      chain: this.record.verify(),
+      eventCount: this.record.events.length,
+    };
+  }
+
+  /** Subscribe to decisions. Returns an unsubscribe function. */
+  onChange(fn) {
+    this._listeners.add(fn);
+    return () => this._listeners.delete(fn);
+  }
+
+  _emit(evt) {
+    for (const fn of this._listeners) {
+      try { fn(evt, this.snapshot()); } catch { /* a bad listener must not break the gate */ }
+    }
+  }
+
+  // -- persistence -----------------------------------------------------------
+
+  _load() {
+    if (this.storage) {
+      try {
+        const raw = this.storage.getItem(this.storageKey);
+        if (raw) {
+          const data = JSON.parse(raw);
+          return ConsentRecord.fromJSON(data, { now: this._now });
+        }
+      } catch {
+        // A corrupt record must not silently become a fresh one with
+        // everything granted. Fall through to an empty record, which grants
+        // nothing — the fail-closed direction.
+      }
+    }
+    return new ConsentRecord({ now: this._now, recordId: this.recordId ?? generateId() });
+  }
+
+  _persist() {
+    if (!this.storage) return;
+    try {
+      this.storage.setItem(this.storageKey, JSON.stringify(this.record.toJSON()));
+    } catch {
+      // Storage may be unavailable (private mode, quota). Consent stays valid
+      // for the session; it simply will not survive a reload.
+    }
+  }
+
+  /** Export the record — the portability path the user controls. */
+  export() {
+    return JSON.stringify(this.record.toJSON(), null, 2);
+  }
+
+  /** Erase everything, locally. */
+  erase() {
+    this.record = new ConsentRecord({ now: this._now });
+    if (this.storage) {
+      try { this.storage.removeItem(this.storageKey); } catch { /* nothing to remove */ }
+    }
+    this._emit({ type: 'erase' });
+  }
+}
+
+/** Thrown when processing is attempted without consent. */
+export class ConsentRequiredError extends Error {
+  constructor(purposeId) {
+    super(`consent required for: ${purposeId}`);
+    this.name = 'ConsentRequiredError';
+    this.purposeId = purposeId;
+  }
+}

package/src/index.js

@@ -0,0 +1,37 @@
+/**
+ * neural-consent — local-first consent mechanics for neural-data tools.
+ *
+ * WHAT THIS IS. A purpose-granular consent record with a tamper-evident local
+ * event log, structured on the ISO/IEC TS 27560 field model, for tools that
+ * read a neural or assistive signal on the user's own device.
+ *
+ * WHAT THIS IS NOT. It is not a compliance solution, and it does not claim to
+ * be one. Whether a privacy statute applies to a given tool depends on facts
+ * about whoever publishes it — revenue, consumer counts, jurisdictions — not
+ * on what the code does. A consent screen cannot change that. The DISCLAIMER
+ * export states this in the words the tool should show.
+ *
+ * The honest position this module is built on: a tool that never transmits
+ * the signal has no third party to share with, nothing to sell, and no
+ * database to breach. That is a verifiable statement about the software. The
+ * record states it as a machine-readable field rather than as a promise.
+ */
+
+export {
+  ConsentManager,
+  ConsentRequiredError,
+  PURPOSES,
+  DISCLAIMER,
+  noticeVersion,
+  purposeById,
+} from './consent.js';
+
+export {
+  ConsentRecord,
+  SCHEMA_VERSION,
+  STATES,
+  generateId,
+  fnv1a,
+} from './record.js';
+
+export { keyInformationText } from './notices.js';

package/src/notices.js

@@ -0,0 +1,158 @@
+/**
+ * notices.js — consent notice text and the layered presentation model.
+ *
+ * WHAT THIS FILE IS FOR. Consent is only meaningful if the person actually
+ * understood what they agreed to. The legal basis for presenting it in layers
+ * is 45 CFR 46.116(a)(5)(i) (the Common Rule — the most rigorous consent model
+ * in US law): consent "must begin with a concise and focused presentation of
+ * the key information." That is a regulation explicitly asking for a
+ * short-form-first design, which is also what accessibility practice wants:
+ * a screen-reader user should hear five lines, not a wall.
+ *
+ * So every purpose carries TWO texts:
+ *   - keyText:    the concise, focused version, shown first
+ *   - detailText: the full explanation, available on request
+ *
+ * Both are versioned. The version that was SHOWN is recorded in the consent
+ * record, because "what did the user actually agree to" is an evidentiary
+ * question and the answer must be reconstructable.
+ *
+ * TONE. The text here is written for the person, not for a lawyer. It states
+ * what happens, in plain words, at a reading level appropriate to someone
+ * using an assistive tool — many of whom are disabled, tired, or in a hurry.
+ * It does not use "we may" constructions that hide who does what.
+ */
+
+/**
+ * The purposes this module can record consent for.
+ *
+ * Granularity is deliberate and minimal. ISO/IEC TS 27560 and the state laws
+ * both require PURPOSE LIMITATION: consent to one thing must not silently
+ * authorise another. A blanket "I agree" fails that, so each purpose is
+ * separate and separate consent is required for each.
+ *
+ * These are the four things a local-first access-input-style tool actually
+ * does. There is no "analytics" and no "improve our services" purpose,
+ * because this tool does neither — including a purpose you do not use is its
+ * own kind of dishonesty.
+ */
+export const PURPOSES = {
+  ACQUIRE_SIGNAL: {
+    id: 'acquire_signal',
+    version: '1.0.0',
+    label: 'Read my input signal',
+    keyText:
+      'The tool reads the signal you connect — a switch, a gaze tracker, or an ' +
+      'EEG sensor — to know what you are pointing at. This happens on your ' +
+      'device, while the tool is open.',
+    detailText:
+      'Your device captures a signal from whatever input you connect. The tool ' +
+      'uses it to decide which item on screen you mean, using the dwell and ' +
+      'scan timings you set. Nothing about this signal is sent anywhere. ' +
+      'Closing the tool stops the reading.',
+  },
+  PROCESS_LOCALLY: {
+    id: 'process_locally',
+    version: '1.0.0',
+    label: 'Process it on this device',
+    keyText:
+      'Your signal is processed in this browser. It is not sent to a server, ' +
+      'and no copy leaves this device.',
+    detailText:
+      'All processing — filtering, timing, deciding when a selection happens — ' +
+      'runs in this browser tab. There is no backend that receives your data. ' +
+      'This is verifiable: you can open your browser\u2019s network panel and ' +
+      'watch that nothing is transmitted.',
+  },
+  PERSIST_LOCALLY: {
+    id: 'persist_locally',
+    version: '1.0.0',
+    label: 'Remember my settings',
+    keyText:
+      'Your settings — dwell time, scan speed, and which input you use — are ' +
+      'saved on this device so you do not have to set them again.',
+    detailText:
+      'Settings are stored in this browser\u2019s local storage. They stay on ' +
+      'this device. Clearing your browser data removes them. No settings ' +
+      'history is kept beyond your current choices.',
+  },
+  EXPORT: {
+    id: 'export',
+    version: '1.0.0',
+    label: 'Let me export my own data',
+    keyText:
+      'You can save a copy of your own settings and consent record to a file, ' +
+      'so you can move it to another device or send it to someone you choose.',
+    detailText:
+      'Export produces a file on your device containing your settings and this ' +
+      'consent record. The tool does not send it anywhere \u2014 you decide what ' +
+      'to do with the file. This exists so your data is portable to you, ' +
+      'which is a right under several state privacy laws.',
+  },
+};
+
+/**
+ * The disclaimer, stated once and exported so every surface uses identical
+ * wording.
+ *
+ * WHY THIS TEXT IS LOAD-BEARING. The FTC\u2019s deception doctrine reaches ANY
+ * claim a product makes, whether or not a privacy statute applies to the
+ * publisher. So a tool that says "CCPA compliant" when applicability depends
+ * on facts about the developer (revenue, consumer counts) is not being modest
+ * \u2014 it is making a false claim, which is its own legal exposure. The honest
+ * position is the one below: describe the mechanics precisely, decline to
+ * assert compliance, and say why.
+ *
+ * This wording deliberately avoids: "compliant", "certified", "HIPAA",
+ * "FDA cleared", "GDPR", and "privacy compliant by architecture". The last is
+ * the overclaim a comparable project shipped; architecture is evidence, not a
+ * legal conclusion.
+ */
+export const DISCLAIMER = {
+  version: '1.0.0',
+  short:
+    'This tool handles your data in the ways described above. It does not ' +
+    'claim to satisfy any particular privacy law.',
+  full:
+    'WHAT THIS DOES\n' +
+    'This consent layer records what you agreed to, lets you change or withdraw ' +
+    'it at any time, and keeps a local record of those changes. It implements ' +
+    'the consent mechanics described in the ISO/IEC TS 27560 field model.\n\n' +
+    'WHAT THIS DOES NOT DO\n' +
+    'It does not make this tool "compliant" with any specific law. Whether a ' +
+    'law applies depends on facts about whoever publishes the tool \u2014 their ' +
+    'revenue, how many people use it, and where those people live \u2014 not on ' +
+    'what the code does. A consent screen cannot change that.\n\n' +
+    'Specifically: this is not a claim of CCPA, CPA, CTDPA, or VDPOSA ' +
+    'compliance. It is not a HIPAA claim (HIPAA generally does not apply to a ' +
+    'direct-to-consumer tool with no health-care provider involved). It is not ' +
+    'an FDA claim. ISO/IEC TS 27560 is a technical specification with no ' +
+    'certification programme, so "structured per 27560" describes the record ' +
+    'format and nothing more.\n\n' +
+    'WHAT IS ACTUALLY TRUE\n' +
+    'Your signal is processed on this device and is not transmitted. There is ' +
+    'no server receiving it, so there is nobody to sell it to, no third party ' +
+    'to share it with, and no database to breach. That is a statement about ' +
+    'this software, and you can verify it.',
+};
+
+/** Concatenate the key texts for the initial panel. */
+export function keyInformationText(purposes = Object.values(PURPOSES)) {
+  return purposes.map((p) => `\u2022 ${p.keyText}`).join('\n\n');
+}
+
+/** Look up a purpose by id, or null. */
+export function purposeById(id) {
+  return Object.values(PURPOSES).find((p) => p.id === id) ?? null;
+}
+
+/**
+ * A stable identifier for the notice bundle as a whole. Recorded in every
+ * consent record so the exact text a person saw is reconstructable later.
+ */
+export function noticeVersion(purposes = Object.values(PURPOSES)) {
+  return purposes
+    .map((p) => `${p.id}@${p.version}`)
+    .sort()
+    .join('+');
+}

package/src/record.js

@@ -0,0 +1,329 @@
+/**
+ * record.js — the consent record and its event log.
+ *
+ * DATA MODEL BASIS. The field set follows ISO/IEC TS 27560:2023 ("Privacy
+ * technologies — Consent record information structure"), whose mandatory
+ * fields are public via the W3C Data Privacy Vocabularies and Controls CG
+ * guide (published 2026-02-15). Two deliberate departures, each documented
+ * where it happens, because blindly copying an inter-organisational standard
+ * into a local-first tool imports fields that exist only to make records
+ * exchangeable BETWEEN organisations.
+ *
+ * WHAT 27560 ASKS FOR AND WHY WE KEEP IT:
+ *   - schema version, record id, subject id  → the record must be
+ *     self-describing and attributable
+ *   - privacy notice + language               → "what did they actually agree
+ *     to" is an evidentiary question
+ *   - purpose, data types, retention          → purpose limitation
+ *   - withdrawal method                       → must name a REAL working path
+ *   - events: time, validity, entity, type, state
+ *
+ * WHAT WE DROP, AND WHY: 27560 mandates a controller address, jurisdiction,
+ * and an authority party — fields whose only function is to let one
+ * organisation's records be read by another. A local-first tool exchanges
+ * nothing with anyone, so carrying a controller address would be theatre.
+ * The fields are documented as intentionally absent rather than silently
+ * omitted, so a reviewer can see the decision.
+ *
+ * THE EVENT LOG IS TAMPER-EVIDENT, NOT TAMPER-PROOF. Each event carries the
+ * hash of the previous one, so altering or removing a past entry breaks the
+ * chain and verify() reports it. A determined user with their own device can
+ * always rewrite the whole file — that is inherent to local-first storage and
+ * pretending otherwise would be a lie. The chain's job is to make ACCIDENTAL
+ * or partial modification detectable, and to give the user a way to check
+ * their own record was not quietly changed by the tool.
+ */
+
+/** Bump when the record shape changes; recorded in every record. */
+export const SCHEMA_VERSION = '1.0.0';
+
+/**
+ * Consent lifecycle states (ISO/IEC TS 27560 event states).
+ *   requested  — the user was asked
+ *   given      — the user agreed
+ *   refused    — the user declined
+ *   withdrawn  — the user revoked a previous grant
+ *   expired    — the validity window lapsed
+ *   terminated — the tool or purpose no longer exists
+ */
+export const STATES = ['requested', 'given', 'refused', 'withdrawn', 'expired', 'terminated'];
+
+/** The statuses a purpose can currently be in. */
+export const ACTIVE_STATES = new Set(['given']);
+
+/**
+ * FNV-1a, 32-bit, as a hex string.
+ *
+ * Why not SHA-256: this runs in a browser with no dependencies, and the
+ * WebCrypto digest is async — which would make every append() asynchronous
+ * and force the whole API to be promise-based for a check that is only
+ * detecting accidental modification. 32 bits is the right size for that job.
+ * It is NOT a security hash and the code says so rather than implying it.
+ */
+export function fnv1a(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/** Stable stringify so a hash does not depend on key order. */
+function canonical(obj) {
+  if (obj === null || typeof obj !== 'object') return JSON.stringify(obj);
+  if (Array.isArray(obj)) return '[' + obj.map(canonical).join(',') + ']';
+  const keys = Object.keys(obj).sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonical(obj[k])).join(',') + '}';
+}
+
+/** Event hash = fnv1a(previous hash + canonical event payload). */
+function eventHash(prevHash, event) {
+  const { hash, ...rest } = event; // never hash the hash field itself
+  return fnv1a(prevHash + '|' + canonical(rest));
+}
+
+/**
+ * A local consent record.
+ *
+ * @param {object} [options]
+ * @param {string} [options.subjectId] local pseudonymous id; never transmitted
+ * @param {Function} [options.now] clock, injected for determinism
+ * @param {string} [options.storageKey] localStorage key, when persistence is on
+ */
+export class ConsentRecord {
+  constructor(options = {}) {
+    // The clock must be assigned BEFORE anything reads it — createdAt below
+    // depends on it, and reading it first was a real bug caught by the suite.
+    this._now = options.now ?? (() => Date.now());
+    this.schemaVersion = SCHEMA_VERSION;
+    this.recordId = options.recordId ?? generateId();
+    this.subjectId = options.subjectId ?? generateId();
+    this.createdAt = options.createdAt ?? new Date(this._now()).toISOString();
+    this._storageKey = options.storageKey ?? null;
+
+    /**
+     * Per-purpose consent entries. Keyed by purpose id.
+     * Each entry is the 27560 "Processing" block for one purpose.
+     */
+    this.purposes = {};
+
+    /** Append-only event log. */
+    this.events = [];
+
+    /**
+     * RECIPIENTS IS ALWAYS EMPTY, AND THAT IS THE POINT.
+     *
+     * 27560 makes "recipient third parties" a mandatory field. For this tool
+     * the honest value is a declared emptiness: there is no server, so there
+     * is nobody to receive the data. Recording that as an explicit field
+     * rather than prose makes the tool's central privacy claim machine-
+     * readable and checkable.
+     */
+    this.handling = {
+      storage: 'local-only',
+      recipients: [],
+      recipientsDeclaration: 'none — no transmission',
+      // 27560 fields intentionally not carried (see the file header):
+      omittedFields: ['pii_controller_address', 'jurisdiction', 'authority_party'],
+    };
+  }
+
+  /** Local pseudonymous identifier generator (no PII, no network). */
+  _newEventId() {
+    return generateId();
+  }
+
+  /**
+   * Record a consent decision for one purpose.
+   *
+   * @param {string} purposeId
+   * @param {('given'|'refused')} state
+   * @param {object} [meta]
+   * @param {string} meta.noticeVersion  the notice text version shown
+   * @param {string} [meta.language]     BCP-47 tag of the text shown
+   * @param {number} [meta.validDays]    validity window; consent should lapse
+   * @param {string[]} [meta.dataTypes]  what data this purpose covers
+   * @param {string} [meta.withdrawalMethod] how to revoke (must be real)
+   * @returns {object} the event appended
+   */
+  decide(purposeId, state, meta = {}) {
+    if (!STATES.includes(state)) {
+      throw new Error(`unknown consent state: ${state}`);
+    }
+    const at = new Date(this._now()).toISOString();
+
+    const entry = {
+      purposeId,
+      state,
+      noticeId: meta.noticeId ?? 'default',
+      noticeVersion: meta.noticeVersion ?? 'unversioned',
+      language: meta.language ?? 'en',
+      dataTypes: meta.dataTypes ?? [],
+      sensitivity: 'neural',
+      grantedAt: state === 'given' ? at : null,
+      validUntil: this._validUntil(at, meta.validDays),
+      // 27560 requires the withdrawal method be named. It must describe a
+      // path that actually exists in the UI — naming a method the user
+      // cannot reach is worse than omitting the field.
+      withdrawalMethod: meta.withdrawalMethod ?? 'Settings \u2192 Consent \u2192 withdraw',
+      // Legal basis is what the PUBLISHER asserts. This module does not
+      // assert compliance on anyone's behalf, so it records the honest
+      // default rather than inventing one.
+      legalBasis: meta.legalBasis ?? 'consent',
+    };
+
+    this.purposes[purposeId] = entry;
+    return this.append(state === 'given' ? 'grant' : 'refuse', {
+      purposeId,
+      state,
+      ...entry,
+    });
+  }
+
+  /** Withdraw a previously granted purpose. Symmetric and immediate. */
+  withdraw(purposeId, meta = {}) {
+    const existing = this.purposes[purposeId];
+    if (!existing) throw new Error(`no consent recorded for purpose: ${purposeId}`);
+    if (existing.state === 'withdrawn') return null; // idempotent
+    const at = new Date(this._now()).toISOString();
+    this.purposes[purposeId] = {
+      ...existing,
+      state: 'withdrawn',
+      withdrawnAt: at,
+    };
+    return this.append('withdraw', {
+      purposeId,
+      state: 'withdrawn',
+      at,
+      reason: meta.reason ?? 'user request',
+    });
+  }
+
+  /** Re-affirm consent (Colorado requires periodic refresh). */
+  reaffirm(purposeId, meta = {}) {
+    const existing = this.purposes[purposeId];
+    if (!existing) throw new Error(`no consent recorded for purpose: ${purposeId}`);
+    return this.decide(purposeId, 'given', { ...meta, noticeVersion: existing.noticeVersion });
+  }
+
+  /**
+   * Mark any purpose whose validity window has lapsed as expired.
+   * Returns the ids that expired, so the host can re-ask.
+   */
+  expireLapsed() {
+    const now = this._now();
+    const expired = [];
+    for (const [id, entry] of Object.entries(this.purposes)) {
+      if (entry.state !== 'given' || !entry.validUntil) continue;
+      if (Date.parse(entry.validUntil) <= now) {
+        this.purposes[id] = { ...entry, state: 'expired', expiredAt: new Date(now).toISOString() };
+        this.append('expire', { purposeId: id, state: 'expired', at: new Date(now).toISOString() });
+        expired.push(id);
+      }
+    }
+    return expired;
+  }
+
+  /** Is consent currently held for this purpose? */
+  isGranted(purposeId) {
+    return this.purposes[purposeId]?.state === 'given';
+  }
+
+  /** Every purpose currently granted. */
+  grantedPurposes() {
+    return Object.entries(this.purposes)
+      .filter(([, e]) => e.state === 'given')
+      .map(([id]) => id);
+  }
+
+  /**
+   * Append an event to the tamper-evident log.
+   * The chain makes accidental or partial edits detectable.
+   */
+  append(type, payload = {}) {
+    const prev = this.events[this.events.length - 1];
+    const event = {
+      seq: this.events.length,
+      type,
+      at: new Date(this._now()).toISOString(),
+      ...payload,
+      prevHash: prev ? prev.hash : 'genesis',
+    };
+    event.hash = eventHash(event.prevHash, event);
+    this.events.push(event);
+    return event;
+  }
+
+  /**
+   * Verify the event chain. Returns { ok, brokenAt } — brokenAt is the seq of
+   * the first event whose hash does not match its contents, or -1.
+   */
+  verify() {
+    let prevHash = 'genesis';
+    for (const event of this.events) {
+      if (event.prevHash !== prevHash) return { ok: false, brokenAt: event.seq };
+      const expected = eventHash(prevHash, event);
+      if (event.hash !== expected) return { ok: false, brokenAt: event.seq };
+      prevHash = event.hash;
+    }
+    return { ok: true, brokenAt: -1 };
+  }
+
+  /** Serialise for export or storage. */
+  toJSON() {
+    return {
+      schemaVersion: this.schemaVersion,
+      recordId: this.recordId,
+      subjectId: this.subjectId,
+      createdAt: this.createdAt,
+      purposes: this.purposes,
+      handling: this.handling,
+      events: this.events,
+    };
+  }
+
+  /** Restore from a serialised record. */
+  static fromJSON(data, options = {}) {
+    const rec = new ConsentRecord({
+      ...options,
+      recordId: data.recordId,
+      subjectId: data.subjectId,
+      createdAt: data.createdAt,
+    });
+    rec.schemaVersion = data.schemaVersion ?? SCHEMA_VERSION;
+    rec.purposes = data.purposes ?? {};
+    rec.handling = data.handling ?? rec.handling;
+    rec.events = data.events ?? [];
+    return rec;
+  }
+
+  /** A human-readable summary — what the person can actually read back. */
+  summary() {
+    return {
+      recordId: this.recordId,
+      createdAt: this.createdAt,
+      granted: this.grantedPurposes(),
+      events: this.events.length,
+      chainIntact: this.verify().ok,
+      recipients: this.handling.recipientsDeclaration,
+    };
+  }
+
+  _validUntil(fromIso, validDays) {
+    if (!validDays || validDays <= 0) return null;
+    return new Date(Date.parse(fromIso) + validDays * 86400000).toISOString();
+  }
+}
+
+/**
+ * A local, non-identifying id. Prefers crypto.randomUUID when available, and
+ * falls back to a timestamp + random suffix so the module works in any
+ * environment without a polyfill. Neither form carries personal data.
+ */
+export function generateId() {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return `id-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}