@provex/utils 1.6.2 → 1.7.0-rc.20260522201545.020a3eb

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Provex
+
+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

@@ -284,4 +284,6 @@ When adding new utilities:
 
 ## License
 
-ISC License
+MIT — see `LICENSE` in this package.
+
+> Versions `1.6.3` and later are licensed under MIT. Versions published before `1.6.3` (up to and including `1.6.2`) carry the ISC license they were originally published under.

package/dist/consent.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview Per-section policy consent gate with content hashing.
+ *
+ * Each policy section (e.g. risks, disclaimer, terms, privacy) is
+ * tracked independently as `{ hash, acceptedAt }`. The hash is a cheap
+ * FNV-1a digest of the section content — when an author edits a
+ * section, the stored hash mismatches and only that section re-prompts;
+ * unchanged sections stay accepted. This avoids the "edit a typo,
+ * every user is re-prompted on every section" papercut of single-boolean
+ * gates and produces an audit trail for free.
+ *
+ * Pure utilities only — no React, no DOM, no project-specific section
+ * keys. The UI binds these primitives to its own section definitions
+ * and storage-key string.
+ *
+ * See `~/.claude/skills/per-section-policy-consent-hashing/SKILL.md`
+ * for the broader design rationale, layout candidates, and trade-offs.
+ */
+/** A single per-section consent receipt. */
+export interface ConsentEntry {
+    /** Content hash at the time of acceptance — see {@link hashString}. */
+    hash: string;
+    /** ISO-8601 timestamp the user accepted at. */
+    acceptedAt: string;
+}
+/** Map of section key (caller-defined) to its consent receipt. */
+export type ConsentState = Record<string, ConsentEntry | undefined>;
+/** Three-valued status of a single section. */
+export type SectionStatusValue = 'unread' | 'accepted' | 'stale';
+/**
+ * Minimal structural shape used by this module. Satisfied by
+ * `globalThis.localStorage` in browsers and by any in-memory shim in
+ * tests — the module never depends on a real DOM Storage instance.
+ */
+export interface ConsentStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * FNV-1a 32-bit hash, hex-truncated to 8 characters. Sync, no
+ * dependencies, non-cryptographic — the threat model is "did our
+ * authors edit this string", not adversarial.
+ *
+ * If a compliance requirement forces SHA-256 via SubtleCrypto, bump
+ * the storage key version (e.g. `provex_consent_v3`) and migrate.
+ */
+export declare function hashString(s: string): string;
+/**
+ * Compact relative-time formatter for the audit row next to the accept
+ * button. Past offsets only — future timestamps clamp to "just now".
+ * Falls back to a locale date string once the offset exceeds a week
+ * because "12d ago" is less useful than the actual date by then.
+ */
+export declare function formatRelative(iso: string, now?: Date): string;
+/**
+ * Reads the persisted consent state for a given storage key.
+ * Always returns a usable object — malformed JSON, missing keys, or a
+ * value of the wrong shape all degrade to `{}` rather than throwing,
+ * because surfacing a parse error at modal open is worse than
+ * re-prompting the user.
+ */
+export declare function readConsent(storageKey: string, storage?: ConsentStorage | null): ConsentState;
+/**
+ * Writes the consent state. Silently no-ops when storage is unavailable
+ * or write fails — private mode and quota errors should not break the
+ * accept flow, just fail to persist across sessions.
+ */
+export declare function writeConsent(storageKey: string, state: ConsentState, storage?: ConsentStorage | null): void;
+/**
+ * Computes the three-valued status of a single section from its stored
+ * entry and the current content hash. Pure — caller owns I/O.
+ */
+export declare function sectionStatus(stored: ConsentEntry | undefined, currentHash: string): SectionStatusValue;
+export interface AcceptSectionOptions {
+    storage?: ConsentStorage | null;
+    now?: Date;
+}
+/**
+ * Persists acceptance of a single section, preserving any sibling
+ * sections that already have entries. Returns the new state so React
+ * callers can update local state without re-reading storage.
+ */
+export declare function acceptSection(storageKey: string, sectionKey: string, currentHash: string, opts?: AcceptSectionOptions): ConsentState;
+/**
+ * The gate: returns true only when every section listed in
+ * `currentHashes` has a stored entry whose hash matches. Empty
+ * `currentHashes` returns false so the gate stays closed by default.
+ */
+export declare function allAccepted(storageKey: string, currentHashes: Record<string, string>, storage?: ConsentStorage | null): boolean;
+export interface MigrateLegacyBooleanOptions {
+    legacyKey: string;
+    storageKey: string;
+    currentHashes: Record<string, string>;
+    storage?: ConsentStorage | null;
+    now?: Date;
+}
+/**
+ * One-time migration from a single legacy boolean ("user accepted the
+ * old monolithic risk modal") to the per-section state shape. Treats
+ * the legacy flag as "all sections accepted at migration time" so
+ * existing users don't see the modal again on first open.
+ *
+ * Returns true iff migration ran. No-op (returns false) when:
+ *   - The legacy key is unset or not exactly `'1'`.
+ *   - Storage isn't available.
+ *   - Per-section state already exists for the new key — the new state
+ *     wins; the legacy boolean is left intact in case a downstream
+ *     migration wants to inspect it.
+ */
+export declare function migrateLegacyBoolean(opts: MigrateLegacyBooleanOptions): boolean;

package/dist/consent.js

@@ -0,0 +1,194 @@
+/**
+ * @fileoverview Per-section policy consent gate with content hashing.
+ *
+ * Each policy section (e.g. risks, disclaimer, terms, privacy) is
+ * tracked independently as `{ hash, acceptedAt }`. The hash is a cheap
+ * FNV-1a digest of the section content — when an author edits a
+ * section, the stored hash mismatches and only that section re-prompts;
+ * unchanged sections stay accepted. This avoids the "edit a typo,
+ * every user is re-prompted on every section" papercut of single-boolean
+ * gates and produces an audit trail for free.
+ *
+ * Pure utilities only — no React, no DOM, no project-specific section
+ * keys. The UI binds these primitives to its own section definitions
+ * and storage-key string.
+ *
+ * See `~/.claude/skills/per-section-policy-consent-hashing/SKILL.md`
+ * for the broader design rationale, layout candidates, and trade-offs.
+ */
+/**
+ * Returns the ambient browser storage, or `null` in non-browser /
+ * private-mode / SSR contexts. Never throws — failure to access storage
+ * is normal, not exceptional.
+ */
+function ambientStorage() {
+    try {
+        if (typeof globalThis === 'undefined')
+            return null;
+        const candidate = globalThis.localStorage;
+        if (candidate !== null &&
+            typeof candidate === 'object' &&
+            'getItem' in candidate &&
+            'setItem' in candidate &&
+            'removeItem' in candidate) {
+            return candidate;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * FNV-1a 32-bit hash, hex-truncated to 8 characters. Sync, no
+ * dependencies, non-cryptographic — the threat model is "did our
+ * authors edit this string", not adversarial.
+ *
+ * If a compliance requirement forces SHA-256 via SubtleCrypto, bump
+ * the storage key version (e.g. `provex_consent_v3`) and migrate.
+ */
+export function hashString(s) {
+    let h = 2166136261;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return ('00000000' + (h >>> 0).toString(16)).slice(-8);
+}
+/**
+ * Compact relative-time formatter for the audit row next to the accept
+ * button. Past offsets only — future timestamps clamp to "just now".
+ * Falls back to a locale date string once the offset exceeds a week
+ * because "12d ago" is less useful than the actual date by then.
+ */
+export function formatRelative(iso, now = new Date()) {
+    if (!iso)
+        return '';
+    const then = new Date(iso).getTime();
+    if (Number.isNaN(then))
+        return '';
+    const sec = Math.max(0, Math.floor((now.getTime() - then) / 1000));
+    if (sec < 5)
+        return 'just now';
+    if (sec < 60)
+        return sec + 's ago';
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return min + 'm ago';
+    const hr = Math.floor(min / 60);
+    if (hr < 24)
+        return hr + 'h ago';
+    const day = Math.floor(hr / 24);
+    if (day < 7)
+        return day + 'd ago';
+    return new Date(iso).toLocaleDateString();
+}
+/**
+ * Reads the persisted consent state for a given storage key.
+ * Always returns a usable object — malformed JSON, missing keys, or a
+ * value of the wrong shape all degrade to `{}` rather than throwing,
+ * because surfacing a parse error at modal open is worse than
+ * re-prompting the user.
+ */
+export function readConsent(storageKey, storage = ambientStorage()) {
+    if (!storage)
+        return {};
+    try {
+        const raw = storage.getItem(storageKey);
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            return {};
+        }
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Writes the consent state. Silently no-ops when storage is unavailable
+ * or write fails — private mode and quota errors should not break the
+ * accept flow, just fail to persist across sessions.
+ */
+export function writeConsent(storageKey, state, storage = ambientStorage()) {
+    if (!storage)
+        return;
+    try {
+        storage.setItem(storageKey, JSON.stringify(state));
+    }
+    catch {
+        // Quota / private-mode — accept stands for the session but won't survive a reload.
+    }
+}
+/**
+ * Computes the three-valued status of a single section from its stored
+ * entry and the current content hash. Pure — caller owns I/O.
+ */
+export function sectionStatus(stored, currentHash) {
+    if (!stored)
+        return 'unread';
+    return stored.hash === currentHash ? 'accepted' : 'stale';
+}
+/**
+ * Persists acceptance of a single section, preserving any sibling
+ * sections that already have entries. Returns the new state so React
+ * callers can update local state without re-reading storage.
+ */
+export function acceptSection(storageKey, sectionKey, currentHash, opts = {}) {
+    const storage = opts.storage === undefined ? ambientStorage() : opts.storage;
+    const now = opts.now ?? new Date();
+    const previous = readConsent(storageKey, storage);
+    const next = {
+        ...previous,
+        [sectionKey]: { hash: currentHash, acceptedAt: now.toISOString() },
+    };
+    writeConsent(storageKey, next, storage);
+    return next;
+}
+/**
+ * The gate: returns true only when every section listed in
+ * `currentHashes` has a stored entry whose hash matches. Empty
+ * `currentHashes` returns false so the gate stays closed by default.
+ */
+export function allAccepted(storageKey, currentHashes, storage = ambientStorage()) {
+    const keys = Object.keys(currentHashes);
+    if (keys.length === 0)
+        return false;
+    const state = readConsent(storageKey, storage);
+    return keys.every((k) => sectionStatus(state[k], currentHashes[k]) === 'accepted');
+}
+/**
+ * One-time migration from a single legacy boolean ("user accepted the
+ * old monolithic risk modal") to the per-section state shape. Treats
+ * the legacy flag as "all sections accepted at migration time" so
+ * existing users don't see the modal again on first open.
+ *
+ * Returns true iff migration ran. No-op (returns false) when:
+ *   - The legacy key is unset or not exactly `'1'`.
+ *   - Storage isn't available.
+ *   - Per-section state already exists for the new key — the new state
+ *     wins; the legacy boolean is left intact in case a downstream
+ *     migration wants to inspect it.
+ */
+export function migrateLegacyBoolean(opts) {
+    const storage = opts.storage === undefined ? ambientStorage() : opts.storage;
+    if (!storage)
+        return false;
+    if (storage.getItem(opts.legacyKey) !== '1')
+        return false;
+    const existing = readConsent(opts.storageKey, storage);
+    if (Object.keys(existing).length > 0)
+        return false;
+    const acceptedAt = (opts.now ?? new Date()).toISOString();
+    const state = {};
+    for (const k of Object.keys(opts.currentHashes)) {
+        state[k] = { hash: opts.currentHashes[k], acceptedAt };
+    }
+    writeConsent(opts.storageKey, state, storage);
+    storage.removeItem(opts.legacyKey);
+    return true;
+}

package/dist/consent.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/consent.test.js

@@ -0,0 +1,247 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { hashString, formatRelative, readConsent, writeConsent, sectionStatus, acceptSection, allAccepted, migrateLegacyBoolean, } from './consent.js';
+/**
+ * Minimal in-memory `ConsentStorage` shim used by every test so each
+ * case starts from a clean slate. The production caller passes
+ * `globalThis.localStorage`; the tests never touch globals.
+ */
+function memStorage() {
+    const data = new Map();
+    return {
+        getItem: (k) => (data.has(k) ? data.get(k) : null),
+        setItem: (k, v) => void data.set(k, v),
+        removeItem: (k) => void data.delete(k),
+    };
+}
+describe('hashString (FNV-1a)', () => {
+    it('produces same hash for same input', () => {
+        assert.equal(hashString('hello'), hashString('hello'));
+    });
+    it('produces different hashes for different inputs', () => {
+        assert.notEqual(hashString('hello'), hashString('world'));
+    });
+    it('returns 8-character lowercase hex', () => {
+        assert.match(hashString('anything'), /^[0-9a-f]{8}$/);
+    });
+    it('handles the empty string', () => {
+        // Important: empty content must still hash to something stable so
+        // sectionStatus doesn't blow up if a section is temporarily empty.
+        assert.match(hashString(''), /^[0-9a-f]{8}$/);
+    });
+    it('reflects single-character edits', () => {
+        const before = hashString('the cutting-edge software statement.');
+        const after = hashString('the cutting-edge software statement!');
+        assert.notEqual(before, after);
+    });
+});
+describe('formatRelative', () => {
+    // Anchor "now" so the relative-time bands are deterministic.
+    const T0 = new Date('2026-05-21T18:00:00.000Z').getTime();
+    const now = new Date(T0);
+    const at = (offsetSec) => new Date(T0 - offsetSec * 1000).toISOString();
+    it('returns "just now" for offsets under 5s', () => {
+        assert.equal(formatRelative(at(2), now), 'just now');
+    });
+    it('returns "Xs ago" for offsets under 60s', () => {
+        assert.equal(formatRelative(at(30), now), '30s ago');
+    });
+    it('returns "Xm ago" for offsets under 60m', () => {
+        assert.equal(formatRelative(at(120), now), '2m ago');
+    });
+    it('returns "Xh ago" for offsets under 24h', () => {
+        assert.equal(formatRelative(at(3 * 3600), now), '3h ago');
+    });
+    it('returns "Xd ago" for offsets under 7 days', () => {
+        assert.equal(formatRelative(at(2 * 86400), now), '2d ago');
+    });
+    it('returns a locale date for offsets at or above 7 days', () => {
+        const out = formatRelative(at(8 * 86400), now);
+        // The exact format is locale-dependent — assert only on the audit
+        // signal: it no longer reads as a relative duration.
+        assert.ok(!out.includes('ago'), `expected a date, got "${out}"`);
+        assert.ok(out.length > 0);
+    });
+    it('returns empty string for empty input', () => {
+        assert.equal(formatRelative('', now), '');
+    });
+});
+describe('readConsent', () => {
+    it('returns {} when the storage key is unset', () => {
+        assert.deepEqual(readConsent('k', memStorage()), {});
+    });
+    it('parses a previously written state', () => {
+        const s = memStorage();
+        s.setItem('k', JSON.stringify({ risks: { hash: 'abc', acceptedAt: 'T' } }));
+        assert.deepEqual(readConsent('k', s), {
+            risks: { hash: 'abc', acceptedAt: 'T' },
+        });
+    });
+    it('returns {} on malformed JSON instead of throwing', () => {
+        // Private-mode quirks and manual localStorage edits both produce
+        // unparseable values — we must not surface those as user-visible
+        // errors at modal open.
+        const s = memStorage();
+        s.setItem('k', '{nope');
+        assert.deepEqual(readConsent('k', s), {});
+    });
+    it('returns {} when the parsed value is not an object', () => {
+        const s = memStorage();
+        s.setItem('k', '"a string"');
+        assert.deepEqual(readConsent('k', s), {});
+    });
+    it('returns {} when storage is null', () => {
+        // Server-side render path: no localStorage available.
+        assert.deepEqual(readConsent('k', null), {});
+    });
+});
+describe('sectionStatus', () => {
+    it('returns "unread" when no stored entry exists', () => {
+        assert.equal(sectionStatus(undefined, 'abc'), 'unread');
+    });
+    it('returns "accepted" when stored hash matches current', () => {
+        assert.equal(sectionStatus({ hash: 'abc', acceptedAt: 'T' }, 'abc'), 'accepted');
+    });
+    it('returns "stale" when stored hash differs from current', () => {
+        assert.equal(sectionStatus({ hash: 'old', acceptedAt: 'T' }, 'new'), 'stale');
+    });
+});
+describe('acceptSection', () => {
+    it('writes a new entry with the supplied hash and timestamp', () => {
+        const s = memStorage();
+        const now = new Date('2026-05-21T18:00:00.000Z');
+        const after = acceptSection('k', 'risks', 'h1', { storage: s, now });
+        assert.deepEqual(after.risks, {
+            hash: 'h1',
+            acceptedAt: '2026-05-21T18:00:00.000Z',
+        });
+        assert.deepEqual(readConsent('k', s), after);
+    });
+    it('preserves other sections when accepting one', () => {
+        const s = memStorage();
+        writeConsent('k', { terms: { hash: 't', acceptedAt: 'A' } }, s);
+        const after = acceptSection('k', 'risks', 'r', {
+            storage: s,
+            now: new Date(0),
+        });
+        assert.equal(after.terms?.hash, 't');
+        assert.equal(after.risks?.hash, 'r');
+    });
+    it('overwrites the existing entry for the same section', () => {
+        const s = memStorage();
+        writeConsent('k', { risks: { hash: 'old', acceptedAt: 'A' } }, s);
+        const after = acceptSection('k', 'risks', 'new', {
+            storage: s,
+            now: new Date(0),
+        });
+        assert.equal(after.risks?.hash, 'new');
+    });
+});
+describe('allAccepted', () => {
+    it('is true when every required section has a matching hash', () => {
+        const s = memStorage();
+        writeConsent('k', {
+            risks: { hash: 'r', acceptedAt: 'A' },
+            disclaimer: { hash: 'd', acceptedAt: 'A' },
+        }, s);
+        assert.equal(allAccepted('k', { risks: 'r', disclaimer: 'd' }, s), true);
+    });
+    it('is false when a required section is missing', () => {
+        const s = memStorage();
+        writeConsent('k', { risks: { hash: 'r', acceptedAt: 'A' } }, s);
+        assert.equal(allAccepted('k', { risks: 'r', disclaimer: 'd' }, s), false);
+    });
+    it('is false when a required section is stale', () => {
+        const s = memStorage();
+        writeConsent('k', {
+            risks: { hash: 'old', acceptedAt: 'A' },
+            disclaimer: { hash: 'd', acceptedAt: 'A' },
+        }, s);
+        assert.equal(allAccepted('k', { risks: 'r', disclaimer: 'd' }, s), false);
+    });
+    it('is false when the required-hashes map is empty', () => {
+        // Defensive: no sections defined means "nothing to accept", which
+        // we treat as not-yet-accepted so the gate stays closed.
+        assert.equal(allAccepted('k', {}, memStorage()), false);
+    });
+});
+describe('migrateLegacyBoolean', () => {
+    it('is a no-op when the legacy key is unset', () => {
+        const s = memStorage();
+        const migrated = migrateLegacyBoolean({
+            legacyKey: 'old',
+            storageKey: 'new',
+            currentHashes: { risks: 'r' },
+            storage: s,
+        });
+        assert.equal(migrated, false);
+        assert.deepEqual(readConsent('new', s), {});
+    });
+    it('is a no-op when the legacy value is not "1"', () => {
+        const s = memStorage();
+        s.setItem('old', '0');
+        const migrated = migrateLegacyBoolean({
+            legacyKey: 'old',
+            storageKey: 'new',
+            currentHashes: { risks: 'r' },
+            storage: s,
+        });
+        assert.equal(migrated, false);
+        assert.deepEqual(readConsent('new', s), {});
+        // Legacy value left intact when we didn't migrate.
+        assert.equal(s.getItem('old'), '0');
+    });
+    it('migrates "1" by writing every section with the current hash', () => {
+        const s = memStorage();
+        s.setItem('old', '1');
+        const now = new Date('2026-05-21T18:00:00.000Z');
+        const migrated = migrateLegacyBoolean({
+            legacyKey: 'old',
+            storageKey: 'new',
+            currentHashes: { risks: 'r1', disclaimer: 'd1' },
+            storage: s,
+            now,
+        });
+        assert.equal(migrated, true);
+        const state = readConsent('new', s);
+        assert.equal(state.risks?.hash, 'r1');
+        assert.equal(state.disclaimer?.hash, 'd1');
+        assert.equal(state.risks?.acceptedAt, '2026-05-21T18:00:00.000Z');
+        assert.equal(state.disclaimer?.acceptedAt, '2026-05-21T18:00:00.000Z');
+    });
+    it('clears the legacy key after migrating', () => {
+        const s = memStorage();
+        s.setItem('old', '1');
+        migrateLegacyBoolean({
+            legacyKey: 'old',
+            storageKey: 'new',
+            currentHashes: { risks: 'r' },
+            storage: s,
+        });
+        assert.equal(s.getItem('old'), null);
+    });
+    it('does not overwrite existing per-section state', () => {
+        // The new key wins — if a user has already accepted via the new
+        // flow on another device or tab, the legacy boolean is moot.
+        const s = memStorage();
+        s.setItem('old', '1');
+        writeConsent('new', { risks: { hash: 'existing', acceptedAt: 'A' } }, s);
+        const migrated = migrateLegacyBoolean({
+            legacyKey: 'old',
+            storageKey: 'new',
+            currentHashes: { risks: 'r1' },
+            storage: s,
+        });
+        assert.equal(migrated, false);
+        assert.equal(readConsent('new', s).risks?.hash, 'existing');
+    });
+    it('returns false when storage is null', () => {
+        const migrated = migrateLegacyBoolean({
+            legacyKey: 'old',
+            storageKey: 'new',
+            currentHashes: { risks: 'r' },
+            storage: null,
+        });
+        assert.equal(migrated, false);
+    });
+});

package/dist/index.d.ts

@@ -44,3 +44,4 @@ export * from './peer-types.js';
 export * from './fees.js';
 export * from './reputation.js';
 export * from './transports.js';
+export * from './consent.js';

package/dist/index.js

@@ -44,3 +44,4 @@ export * from './peer-types.js';
 export * from './fees.js';
 export * from './reputation.js';
 export * from './transports.js';
+export * from './consent.js';