app

Local-first trade for farms and co-ops
git clone https://radroots.dev/git/app.git
Log | Files | Refs | README | LICENSE

commit 2979f764dc1cd9b0082a3da37aacedde8c6a2517
parent 51f20b37d4219e185fb7146277f3e1eaca5d32e4
Author: triesap <tyson@radroots.org>
Date:   Tue,  6 Oct 2026 20:55:55 +0000

storage: create the browser persistence owner (HCP-045)

- Bootstrap one browser-only versioned IndexedDB schema.
- Reject blocked, denied, incompatible and corrupt opens without reset.
- Fence cancellation and revoke connections on version changes.
- Verify real browser storage and exact schema preservation boundaries.

Diffstat:
Aweb/src/lib/persistence/database.ts | 193+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aweb/src/lib/persistence/schema.ts | 63+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aweb/tests/e2e/idb-open.spec.ts | 456+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aweb/tests/unit/database.test.ts | 60++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 772 insertions(+), 0 deletions(-)

diff --git a/web/src/lib/persistence/database.ts b/web/src/lib/persistence/database.ts @@ -0,0 +1,193 @@ +import { + browserDatabaseName, + browserSchemaVersion, + browserStores, + initializeBrowserSchema, + validateBrowserSchema, + type BrowserStore +} from './schema.ts'; + +export type StorageFailure = + | 'unavailable' + | 'denied' + | 'blocked' + | 'cancelled' + | 'incompatible_version' + | 'migration_failed' + | 'corrupt_schema' + | 'open_failed'; +export type BrowserDatabase = Readonly<{ kind: 'browser_database' }>; +type Owner = { + database: IDBDatabase; + close(reason: 'explicit' | 'version_change' | 'connection_closed'): void; + snapshot(): Readonly<{ + state: 'ready' | 'closed'; + reason: 'explicit' | 'version_change' | 'connection_closed' | null; + }>; +}; +const owners = new WeakMap<BrowserDatabase, Owner>(); +export type DatabaseOpenResult = + | Readonly<{ state: 'ready'; owner: BrowserDatabase }> + | Readonly<{ + state: 'unavailable'; + reason: StorageFailure; + message: string; + }>; + +function failure(reason: StorageFailure): DatabaseOpenResult { + return { + state: 'unavailable', + reason, + message: + 'Browser storage is unavailable. You can still browse public listings. Existing local data has not been reset.' + }; +} +function classify(error: unknown): StorageFailure { + const name = error instanceof DOMException ? error.name : ''; + if (name === 'SecurityError' || name === 'NotAllowedError') return 'denied'; + if (name === 'VersionError') return 'incompatible_version'; + return 'open_failed'; +} +function ownerOf(owner: BrowserDatabase): Owner { + const value = owners.get(owner); + if (!value) throw new Error('invalid_database_owner'); + return value; +} +export function closeBrowserDatabase(owner: BrowserDatabase): void { + ownerOf(owner).close('explicit'); +} +export function browserDatabaseState(owner: BrowserDatabase) { + return ownerOf(owner).snapshot(); +} + +// Explicit call only: importing this module never opens storage, including SSR. +export function openBrowserDatabase( + signal?: AbortSignal +): Promise<DatabaseOpenResult> { + if (signal?.aborted) return Promise.resolve(failure('cancelled')); + let request: IDBOpenDBRequest; + try { + if (typeof indexedDB === 'undefined') + return Promise.resolve(failure('unavailable')); + request = indexedDB.open(browserDatabaseName, browserSchemaVersion); + } catch (error) { + return Promise.resolve(failure(classify(error))); + } + return new Promise((resolve) => { + let settled = false; + let migrationFailed = false; + function finish(result: DatabaseOpenResult): void { + if (settled) return; + settled = true; + signal?.removeEventListener('abort', cancel); + resolve(result); + } + function abortUpgrade(): void { + try { + request.transaction?.abort(); + } catch { + // Already completed/aborted; success still closes any late connection. + } + } + function cancel(): void { + finish(failure('cancelled')); + abortUpgrade(); + } + signal?.addEventListener('abort', cancel, { once: true }); + if (signal?.aborted) cancel(); + request.addEventListener('blocked', () => { + finish(failure('blocked')); + abortUpgrade(); + }); + request.addEventListener('upgradeneeded', (event) => { + if (settled) { + abortUpgrade(); + return; + } + try { + initializeBrowserSchema( + request.result, + event.oldVersion, + event.newVersion + ); + } catch { + migrationFailed = true; + abortUpgrade(); + } + }); + request.addEventListener('error', () => { + finish( + failure(migrationFailed ? 'migration_failed' : classify(request.error)) + ); + }); + request.addEventListener('success', () => { + const database = request.result; + if (settled) { + database.close(); + return; + } + try { + if (!validateBrowserSchema(database)) { + database.close(); + finish(failure('corrupt_schema')); + return; + } + } catch { + database.close(); + finish(failure('corrupt_schema')); + return; + } + const owner: BrowserDatabase = Object.freeze({ + kind: 'browser_database' + }); + let state: 'ready' | 'closed' = 'ready'; + let reason: 'explicit' | 'version_change' | 'connection_closed' | null = + null; + const value: Owner = { + database, + close(selected) { + if (state !== 'ready') return; + state = 'closed'; + reason = selected; + database.close(); + }, + snapshot() { + return { state, reason }; + } + }; + owners.set(owner, value); + database.addEventListener('versionchange', () => + value.close('version_change') + ); + database.addEventListener('close', () => + value.close('connection_closed') + ); + finish({ state: 'ready', owner }); + }); + }); +} + +// Repositories own record validation and transaction completion/reconciliation. +// They must never hold this transaction across a signer or network await. +function validStores(value: unknown): value is readonly BrowserStore[] { + return ( + Array.isArray(value) && + value.length > 0 && + value.length <= browserStores.length && + new Set(value).size === value.length && + value.every((name: unknown) => + browserStores.some((allowed) => allowed === name) + ) + ); +} +export function browserDatabaseTransaction( + owner: BrowserDatabase, + stores: readonly BrowserStore[], + mode: 'readonly' | 'readwrite' +): IDBTransaction { + const value = ownerOf(owner); + if (value.snapshot().state !== 'ready') throw new Error('database_closed'); + if (!validStores(stores) || (mode !== 'readonly' && mode !== 'readwrite')) + throw new Error('invalid_database_transaction'); + return value.database.transaction([...stores], mode); +} diff --git a/web/src/lib/persistence/schema.ts b/web/src/lib/persistence/schema.ts @@ -0,0 +1,63 @@ +// Browser-only bootstrap metadata. Record validation, revisions and quotas +// belong to typed repositories; this schema never imports desktop state. +export const browserDatabaseName = 'harvestcircle_browser'; +export const browserSchemaVersion = 1; +export const browserStores = Object.freeze([ + 'public_drafts', + 'public_operations', + 'preference_operations', + 'private_sends', + 'received_envelopes', + 'conversations', + 'local_preferences' +] as const); +export type BrowserStore = (typeof browserStores)[number]; + +export function initializeBrowserSchema( + database: IDBDatabase, + oldVersion: number, + newVersion: number | null +): void { + // No released browser predecessor exists. Future migration owners must + // explicitly qualify preservation of all uncertain records before upgrading. + if (oldVersion !== 0 || newVersion !== browserSchemaVersion) + throw new Error('unsupported_browser_migration'); + for (const name of browserStores) { + const store = database.createObjectStore(name, { + keyPath: ['owner', 'id'] + }); + store.createIndex('by_owner', 'owner', { + unique: false, + multiEntry: false + }); + } +} + +export function validateBrowserSchema(database: IDBDatabase): boolean { + if ( + database.name !== browserDatabaseName || + database.version !== browserSchemaVersion || + database.objectStoreNames.length !== browserStores.length || + browserStores.some((name) => !database.objectStoreNames.contains(name)) + ) + return false; + const transaction = database.transaction([...browserStores], 'readonly'); + for (const name of browserStores) { + const store = transaction.objectStore(name); + const key = store.keyPath; + if ( + !Array.isArray(key) || + key.length !== 2 || + key[0] !== 'owner' || + key[1] !== 'id' || + store.autoIncrement || + store.indexNames.length !== 1 || + !store.indexNames.contains('by_owner') + ) + return false; + const index = store.index('by_owner'); + if (index.keyPath !== 'owner' || index.unique || index.multiEntry) + return false; + } + return true; +} diff --git a/web/tests/e2e/idb-open.spec.ts b/web/tests/e2e/idb-open.spec.ts @@ -0,0 +1,456 @@ +import { expect, test, type Page } from '@playwright/test'; +import { createHash } from 'node:crypto'; +import { readFile } from 'node:fs/promises'; +import ts from 'typescript'; +import { createStaticHarness } from '../integration/harness/static.ts'; +import type * as Database from '../../src/lib/persistence/database.ts'; +declare global { + interface Window { + hcp045: typeof Database; + } +} +let server: Awaited<ReturnType<typeof createStaticHarness>>; +let schema: string; +let database: string; +test.beforeAll(async () => { + server = await createStaticHarness(); + schema = await readFile( + new URL('../../src/lib/persistence/schema.ts', import.meta.url), + 'utf8' + ); + database = await readFile( + new URL('../../src/lib/persistence/database.ts', import.meta.url), + 'utf8' + ); + console.log( + JSON.stringify({ + fixture: 'HCP045_REAL_CHROMIUM_NATIVE_IDB', + schema: createHash('sha256').update(schema).digest('hex'), + database: createHash('sha256').update(database).digest('hex'), + exposure: 'test-only module URLs; no production route or dependency' + }) + ); +}); +test.afterAll(async () => server.close()); +function javascript(source: string): string { + return ts.transpileModule(source, { + compilerOptions: { + target: ts.ScriptTarget.ES2022, + module: ts.ModuleKind.ESNext + } + }).outputText; +} +async function load(page: Page, futureVersionProbe = false) { + // Production has no released old schema. A separately labelled version2 + // variant tests the native blocked-upgrade event, never a supported migration. + const selected = futureVersionProbe + ? schema.replace( + 'export const browserSchemaVersion = 1;', + 'export const browserSchemaVersion = 2;' + ) + : schema; + if (futureVersionProbe) expect(selected).not.toBe(schema); + expect(database.split("from './schema.ts'")).toHaveLength(2); + await page.route('**/__hcp045/schema.js', (route) => + route.fulfill({ + contentType: 'text/javascript', + body: javascript(selected) + }) + ); + await page.route('**/__hcp045/database.js', (route) => + route.fulfill({ + contentType: 'text/javascript', + body: + javascript( + database.replace("from './schema.ts'", "from './schema.js'") + ) + + '\nglobalThis.hcp045={openBrowserDatabase,closeBrowserDatabase,browserDatabaseState,browserDatabaseTransaction};' + }) + ); + await page.goto(server.url + '/search'); + await page.addScriptTag({ + url: server.url + '/__hcp045/database.js', + type: 'module' + }); +} + +test('fresh schema, acknowledged records, reopen, owner revocation and transaction admission use actual IndexedDB', async ({ + page +}) => { + await load(page); + const result = await page.evaluate(async () => { + const api = window.hcp045; + const opened = await api.openBrowserDatabase(); + if (opened.state !== 'ready') throw new Error(opened.reason); + const transaction = api.browserDatabaseTransaction( + opened.owner, + ['public_drafts'], + 'readwrite' + ); + // Test-only sentinel, not a qualified public draft record or repository. + transaction + .objectStore('public_drafts') + .put({ owner: 'test-owner', id: 'sentinel', value: 'preserve' }); + await new Promise<void>((resolve, reject) => { + transaction.addEventListener('complete', () => resolve()); + transaction.addEventListener('abort', () => reject(new Error('abort'))); + }); + let rejected = 0; + for (const stores of [ + [], + ['public_drafts', 'public_drafts'], + ['unknown'] + ]) { + try { + api.browserDatabaseTransaction( + opened.owner, + stores as ['public_drafts'], + 'readonly' + ); + } catch { + rejected++; + } + } + api.closeBrowserDatabase(opened.owner); + api.closeBrowserDatabase(opened.owner); + const closed = api.browserDatabaseState(opened.owner); + try { + api.browserDatabaseTransaction( + opened.owner, + ['public_drafts'], + 'readonly' + ); + } catch { + rejected++; + } + const reopened = await api.openBrowserDatabase(); + if (reopened.state !== 'ready') throw new Error(reopened.reason); + const read = api + .browserDatabaseTransaction(reopened.owner, ['public_drafts'], 'readonly') + .objectStore('public_drafts') + .get(['test-owner', 'sentinel']); + const value = await new Promise<unknown>((resolve, reject) => { + read.addEventListener('success', () => resolve(read.result)); + read.addEventListener('error', () => reject(new Error('read_failed'))); + }); + api.closeBrowserDatabase(reopened.owner); + return { closed, rejected, value }; + }); + expect(result).toEqual({ + closed: { state: 'closed', reason: 'explicit' }, + rejected: 4, + value: { owner: 'test-owner', id: 'sentinel', value: 'preserve' } + }); +}); + +test('real version change closes the owned connection and rejects the unsupported future schema', async ({ + page, + context +}) => { + await load(page); + await page.evaluate(async () => { + const opened = await window.hcp045.openBrowserDatabase(); + if (opened.state !== 'ready') throw new Error(opened.reason); + // Retain only a test closure, never an exported raw production connection. + Object.assign(window, { + readHcp045State: () => window.hcp045.browserDatabaseState(opened.owner) + }); + }); + const other = await context.newPage(); + await other.goto(server.url + '/search'); + expect( + await other.evaluate( + () => + new Promise<number>((resolve, reject) => { + const request = indexedDB.open('harvestcircle_browser', 2); + request.addEventListener('success', () => { + const version = request.result.version; + request.result.close(); + resolve(version); + }); + request.addEventListener('error', () => + reject(new Error('upgrade_failed')) + ); + }) + ) + ).toBe(2); + const state = await page.evaluate(() => { + const host = window as unknown as { readHcp045State: () => unknown }; + return host.readHcp045State(); + }); + expect(state).toEqual({ state: 'closed', reason: 'version_change' }); + expect( + await page.evaluate(() => window.hcp045.openBrowserDatabase()) + ).toMatchObject({ state: 'unavailable', reason: 'incompatible_version' }); +}); + +test('actual other-tab blocked upgrade fails closed; late release cannot expose or migrate an abandoned owner', async ({ + page, + context +}) => { + const incumbent = await context.newPage(); + await incumbent.goto(server.url + '/search'); + await incumbent.evaluate( + () => + new Promise<void>((resolve, reject) => { + const request = indexedDB.open('harvestcircle_browser', 1); + request.addEventListener('success', () => { + Object.assign(window, { + closeIncumbent: () => request.result.close() + }); + resolve(); + }); + request.addEventListener('error', () => + reject(new Error('incumbent_failed')) + ); + }) + ); + await load(page, true); + const blocked = await page.evaluate(() => + window.hcp045.openBrowserDatabase() + ); + expect(blocked).toMatchObject({ state: 'unavailable', reason: 'blocked' }); + await incumbent.evaluate(() => { + (window as unknown as { closeIncumbent: () => void }).closeIncumbent(); + }); + // A following request serializes behind the abandoned real upgrade. Its v1 + // success proves that the late upgrade aborted and no hidden v2 reset won. + expect( + await incumbent.evaluate( + () => + new Promise<number>((resolve, reject) => { + const request = indexedDB.open('harvestcircle_browser', 1); + request.addEventListener('success', () => { + const version = request.result.version; + request.result.close(); + resolve(version); + }); + request.addEventListener('error', () => + reject(new Error('late_upgrade_mutated_state')) + ); + }) + ) + ).toBe(1); +}); + +test('actual migration transaction abort is reported; only an explicit new attempt initializes', async ({ + page +}) => { + await load(page); + const result = await page.evaluate(async () => { + const original = Object.getOwnPropertyDescriptor( + IDBDatabase.prototype, + 'createObjectStore' + ); + if (!original) throw new Error('missing_browser_prototype'); + IDBDatabase.prototype.createObjectStore = function () { + throw new DOMException('test-only failure', 'QuotaExceededError'); + }; + let failed; + try { + failed = await window.hcp045.openBrowserDatabase(); + } finally { + Object.defineProperty( + IDBDatabase.prototype, + 'createObjectStore', + original + ); + } + const retry = await window.hcp045.openBrowserDatabase(); + if (retry.state === 'ready') + window.hcp045.closeBrowserDatabase(retry.owner); + return { failed, retry: retry.state }; + }); + expect(result.failed).toMatchObject({ + state: 'unavailable', + reason: 'migration_failed' + }); + expect(result.retry).toBe('ready'); +}); + +test('corrupt existing schema and sentinel data are preserved without reset', async ({ + page +}) => { + await load(page); + const result = await page.evaluate(async () => { + await new Promise<void>((resolve, reject) => { + const request = indexedDB.open('harvestcircle_browser', 1); + request.addEventListener('upgradeneeded', () => + request.result + .createObjectStore('unknown_records') + .put('retain', 'sentinel') + ); + request.addEventListener('success', () => { + request.result.close(); + resolve(); + }); + request.addEventListener('error', () => + reject(new Error('fixture_failed')) + ); + }); + const failed = await window.hcp045.openBrowserDatabase(); + const sentinel = await new Promise<unknown>((resolve, reject) => { + const request = indexedDB.open('harvestcircle_browser', 1); + request.addEventListener('success', () => { + const read = request.result + .transaction('unknown_records') + .objectStore('unknown_records') + .get('sentinel'); + read.addEventListener('success', () => { + request.result.close(); + resolve(read.result); + }); + read.addEventListener('error', () => + reject(new Error('sentinel_failed')) + ); + }); + request.addEventListener('error', () => + reject(new Error('fixture_reopen_failed')) + ); + }); + return { failed, sentinel }; + }); + expect(result.failed).toMatchObject({ + state: 'unavailable', + reason: 'corrupt_schema' + }); + expect(result.sentinel).toBe('retain'); +}); + +test('denied capability branch returns browse-only explanation and keeps the real public page usable', async ({ + page +}) => { + await load(page); + const failed = await page.evaluate(async () => { + // Browser capability denial branch injection, not private-mode qualification. + const original = Object.getOwnPropertyDescriptor(window, 'indexedDB'); + Object.defineProperty(window, 'indexedDB', { + configurable: true, + get() { + throw new DOMException('test-only denied', 'SecurityError'); + } + }); + try { + return await window.hcp045.openBrowserDatabase(); + } finally { + if (original) Object.defineProperty(window, 'indexedDB', original); + else Reflect.deleteProperty(window, 'indexedDB'); + } + }); + expect(failed).toMatchObject({ + state: 'unavailable', + reason: 'denied', + message: expect.stringContaining('still browse') + }); + await expect( + page.getByRole('textbox', { name: 'What are you looking for?' }) + ).toBeVisible(); +}); + +test('immediate cancellation owns the pending real open and permits only a separate explicit retry', async ({ + page +}) => { + await load(page); + const result = await page.evaluate(async () => { + const controller = new AbortController(); + const pending = window.hcp045.openBrowserDatabase(controller.signal); + controller.abort(); + const cancelled = await pending; + const retry = await window.hcp045.openBrowserDatabase(); + if (retry.state === 'ready') + window.hcp045.closeBrowserDatabase(retry.owner); + return { cancelled, retry: retry.state }; + }); + expect(result.cancelled).toMatchObject({ + state: 'unavailable', + reason: 'cancelled' + }); + expect(result.retry).toBe('ready'); +}); + +for (const defect of [ + 'key_path', + 'auto_increment', + 'unique_index', + 'missing_index', + 'extra_index' +] as const) { + test(`exact schema rejects ${defect} and preserves existing data`, async ({ + page + }) => { + await load(page); + const result = await page.evaluate(async (defect) => { + const stores = [ + 'public_drafts', + 'public_operations', + 'preference_operations', + 'private_sends', + 'received_envelopes', + 'conversations', + 'local_preferences' + ]; + await new Promise<void>((resolve, reject) => { + const request = indexedDB.open('harvestcircle_browser', 1); + request.addEventListener('upgradeneeded', () => { + for (const name of stores) { + const selected = name === 'public_drafts'; + const store = request.result.createObjectStore(name, { + keyPath: + selected && + (defect === 'key_path' || defect === 'auto_increment') + ? 'id' + : ['owner', 'id'], + autoIncrement: selected && defect === 'auto_increment' + }); + if (!(selected && defect === 'missing_index')) + store.createIndex('by_owner', 'owner', { + unique: selected && defect === 'unique_index' + }); + if (selected && defect === 'extra_index') + store.createIndex('unexpected', 'id'); + } + request.transaction + ?.objectStore('local_preferences') + .put({ owner: 'test-owner', id: 'sentinel', value: 'preserve' }); + }); + request.addEventListener('success', () => { + request.result.close(); + resolve(); + }); + request.addEventListener('error', () => + reject(new Error('fixture_failed')) + ); + }); + const failed = await window.hcp045.openBrowserDatabase(); + const sentinel = await new Promise<unknown>((resolve, reject) => { + const request = indexedDB.open('harvestcircle_browser', 1); + request.addEventListener('success', () => { + const read = request.result + .transaction('local_preferences') + .objectStore('local_preferences') + .get(['test-owner', 'sentinel']); + read.addEventListener('success', () => { + request.result.close(); + resolve(read.result); + }); + read.addEventListener('error', () => + reject(new Error('read_failed')) + ); + }); + request.addEventListener('error', () => + reject(new Error('reopen_failed')) + ); + }); + return { failed, sentinel }; + }, defect); + expect(result.failed).toMatchObject({ + state: 'unavailable', + reason: 'corrupt_schema' + }); + expect(result.sentinel).toEqual({ + owner: 'test-owner', + id: 'sentinel', + value: 'preserve' + }); + }); +} diff --git a/web/tests/unit/database.test.ts b/web/tests/unit/database.test.ts @@ -0,0 +1,60 @@ +import { describe, expect, it } from 'vitest'; +import { + browserDatabaseState, + browserDatabaseTransaction, + closeBrowserDatabase, + openBrowserDatabase +} from '../../src/lib/persistence/database.ts'; +import { browserStores } from '../../src/lib/persistence/schema.ts'; + +describe('browser persistence bootstrap without browser capabilities', () => { + it('imports without an implicit open and explicitly reports unavailable storage', async () => { + expect( + Object.getOwnPropertyDescriptor(globalThis, 'indexedDB') + ).toHaveProperty('get'); + const result = await openBrowserDatabase(); + expect(result).toMatchObject({ + state: 'unavailable', + reason: 'open_failed' + }); + if (result.state !== 'unavailable') throw new Error('unexpected_ready'); + expect(result.message).toContain('still browse'); + }); + it('reports a genuinely absent capability without opening another store', async () => { + const original = Object.getOwnPropertyDescriptor(globalThis, 'indexedDB'); + if (!original) throw new Error('missing_ssr_guard'); + Object.defineProperty(globalThis, 'indexedDB', { + configurable: true, + value: undefined + }); + try { + expect(await openBrowserDatabase()).toMatchObject({ + state: 'unavailable', + reason: 'unavailable' + }); + } finally { + Object.defineProperty(globalThis, 'indexedDB', original); + } + }); + it('rejects already cancelled work before probing storage', async () => { + const controller = new AbortController(); + controller.abort(); + expect(await openBrowserDatabase(controller.signal)).toMatchObject({ + state: 'unavailable', + reason: 'cancelled' + }); + }); + it('rejects fabricated owner capabilities', () => { + const fake = Object.freeze({ kind: 'browser_database' as const }); + expect(() => closeBrowserDatabase(fake)).toThrow('invalid_database_owner'); + expect(() => browserDatabaseState(fake)).toThrow('invalid_database_owner'); + expect(() => + browserDatabaseTransaction(fake, ['public_drafts'], 'readonly') + ).toThrow('invalid_database_owner'); + }); + it('keeps namespaces separated and bootstrap metadata immutable', () => { + expect(browserStores).toHaveLength(7); + expect(new Set(browserStores).size).toBe(7); + expect(Object.isFrozen(browserStores)).toBe(true); + }); +});