import { describe, expect, it, vi } from "vitest"; import { createBrowserStorageAdapter } from "../../src/adapters/storage/browser-storage-adapter.ts"; import { STORAGE_REGISTRY, buildPhysicalKey, defineStorageKey, getStorageDefinition, isStorageValueAllowed, type StorageDefinition, type StorageKeyInput, } from "../../src/contracts/storage-keys.ts"; type StorageFailureMode = "none" | "quota" | "firefox-quota" | "security"; function createStorage(options: { initial?: Readonly>; writeFailure?: StorageFailureMode; readFailure?: StorageFailureMode; removeFailure?: StorageFailureMode; } = {}) { const values = new Map(Object.entries(options.initial ?? {})); const state = { writeFailure: options.writeFailure ?? "none", readFailure: options.readFailure ?? "none", removeFailure: options.removeFailure ?? "none", }; const getItem = vi.fn((key: string) => { throwFor(state.readFailure); return values.get(key) ?? null; }); const setItem = vi.fn((key: string, value: string) => { throwFor(state.writeFailure); values.set(key, value); }); const removeItem = vi.fn((key: string) => { throwFor(state.removeFailure); values.delete(key); }); const storage: Storage = { getItem, setItem, removeItem, clear: () => values.clear(), key: (index) => [...values.keys()][index] ?? null, get length() { return values.size; }, }; return { storage, values, state, getItem, setItem, removeItem }; } function throwFor(mode: StorageFailureMode): void { if (mode === "quota") { throw new DOMException("private quota detail", "QuotaExceededError"); } if (mode === "firefox-quota") { // Older Firefox names the quota error this way, with code 1014. throw new DOMException("private quota detail", "NS_ERROR_DOM_QUOTA_REACHED"); } if (mode === "security") { throw new DOMException("private security detail", "SecurityError"); } } function serializedEnvelope( value: unknown, overrides: Readonly<{ schemaVersion?: number; expiresAt?: number | null; }> = {}, ): string { return JSON.stringify({ schemaVersion: overrides.schemaVersion ?? 1, expiresAt: overrides.expiresAt ?? null, value, }); } function definitionResolver( extra: Readonly>, ) { return (logicalName: string): StorageDefinition => extra[logicalName] ?? getStorageDefinition(logicalName); } describe("storage registry", () => { it("builds namespace and schema-versioned physical keys", () => { expect(buildPhysicalKey("preference", 2, "theme")).toBe( "ca-frontend:preference:v2:theme", ); expect(STORAGE_REGISTRY.COLOR_SCHEME.physicalKey).toContain(":v1:"); }); it("rejects token or secret persistence registrations", () => { expect(() => defineStorageKey({ logicalName: "TOKEN", scope: "auth", name: "token", backend: "localStorage", classification: "sensitive-forbidden", schemaVersion: 1, valueCodec: "none", ttl: null, migration: "discard", quotaFallback: "feature-disable", }), ).toThrow("Sensitive client storage registration is forbidden"); }); it("enforces the registry-owned typed value codec contract", () => { const colorScheme = STORAGE_REGISTRY.COLOR_SCHEME; expect( ["system", "light", "dark"].every((value) => isStorageValueAllowed(colorScheme, value), ), ).toBe(true); expect( [ "", "LIGHT", "private-custom-theme", 1, null, { mode: "dark" }, ].some((value) => isStorageValueAllowed(colorScheme, value)), ).toBe(false); const opaqueString = STORAGE_REGISTRY.CHUNK_RELOAD_GUARD; expect(isStorageValueAllowed(opaqueString, "a")).toBe(true); expect(isStorageValueAllowed(opaqueString, "x".repeat(2_048))).toBe(true); expect(isStorageValueAllowed(opaqueString, "")).toBe(false); expect(isStorageValueAllowed(opaqueString, "x".repeat(2_049))).toBe(false); expect(isStorageValueAllowed(opaqueString, { value: "opaque" })).toBe(false); expect( isStorageValueAllowed( STORAGE_REGISTRY.QUERY_PERSISTENCE, "must-never-persist", ), ).toBe(false); }); it("rejects unregistered codecs and executable migration policies", () => { const definition = { logicalName: "UNSAFE_POLICY", scope: "preference", name: "unsafe-policy", backend: "localStorage", classification: "public-preference", schemaVersion: 1, valueCodec: "unregistered-codec", ttl: null, migration: "discard", quotaFallback: "no-persist", } as unknown as StorageKeyInput; expect(() => defineStorageKey(definition)).toThrow( "Unknown client storage value codec", ); expect(() => defineStorageKey({ ...definition, valueCodec: "opaque-string-v1", migration: (() => "unsafe") as unknown as "discard", }), ).toThrow("Unsupported client storage migration policy"); }); // 05-01. The cross-context adapter writes raw wire JSON to this physical // key. StoragePort must refuse the key instead of discarding that value as // a corrupt envelope or overwriting it with one. it("refuses the externally owned pulse key without touching its value", () => { const pulse = STORAGE_REGISTRY.CACHE_INVALIDATION_PULSE; const rawPulse = JSON.stringify({ protocolVersion: 1, topic: "t" }); const { storage, values, setItem, removeItem } = createStorage({ initial: { [pulse.physicalKey]: rawPulse }, }); const adapter = createBrowserStorageAdapter({ localStorage: storage }); expect(adapter.read("CACHE_INVALIDATION_PULSE")).toMatchObject({ ok: false, error: { code: "CACHE_INVALIDATION_PULSE_READ_UNAVAILABLE" }, }); expect(adapter.write("CACHE_INVALIDATION_PULSE", "hello")).toMatchObject({ ok: false, }); expect(adapter.remove("CACHE_INVALIDATION_PULSE")).toMatchObject({ ok: false, }); expect(setItem).not.toHaveBeenCalled(); expect(removeItem).not.toHaveBeenCalled(); expect(values.get(pulse.physicalKey)).toBe(rawPulse); expect(pulse.physicalKey).toBe("ca-frontend:cache-invalidation:v1:pulse"); expect(pulse).toMatchObject({ backend: "external", valueCodec: "none" }); expect(() => getStorageDefinition("CACHE_INVALIDATION_PULSE")).toThrow( "Externally owned storage key: CACHE_INVALIDATION_PULSE", ); }); // 1105/05-01. The OIDC PKCE recipe wrote its sessionStorage key as a // literal outside the registry, so renaming APP_NAMESPACE split it off. The // key is now a registry row the recipe reads, and StoragePort refuses it // like the pulse key. it("registers the PKCE sign-in transaction key as externally owned and refuses it", () => { const transaction = STORAGE_REGISTRY.AUTH_REDIRECT_TRANSACTION; const raw = JSON.stringify({ state: "s", nonce: "n" }); const { storage, values, setItem, removeItem } = createStorage({ initial: { [transaction.physicalKey]: raw }, }); const adapter = createBrowserStorageAdapter({ sessionStorage: storage }); expect(transaction).toMatchObject({ scope: "auth", name: "oidc-pkce-transaction", backend: "external", valueCodec: "none", }); expect(transaction.physicalKey).toBe( buildPhysicalKey("auth", 1, "oidc-pkce-transaction"), ); expect(adapter.read("AUTH_REDIRECT_TRANSACTION")).toMatchObject({ ok: false, }); expect(adapter.write("AUTH_REDIRECT_TRANSACTION", "hello")).toMatchObject({ ok: false, }); expect(adapter.remove("AUTH_REDIRECT_TRANSACTION")).toMatchObject({ ok: false, }); expect(setItem).not.toHaveBeenCalled(); expect(removeItem).not.toHaveBeenCalled(); expect(values.get(transaction.physicalKey)).toBe(raw); expect(() => getStorageDefinition("AUTH_REDIRECT_TRANSACTION")).toThrow( "Externally owned storage key: AUTH_REDIRECT_TRANSACTION", ); }); it("rejects a value codec on an externally owned key", () => { expect(() => defineStorageKey({ logicalName: "EXTERNAL_WITH_CODEC", scope: "cache", name: "external-with-codec", backend: "external", classification: "opaque-cache", schemaVersion: 1, valueCodec: "opaque-string-v1", ttl: null, migration: "discard", quotaFallback: "no-persist", }), ).toThrow("Externally owned storage keys have no StoragePort codec"); }); it("round-trips public preferences through the adapter", () => { const { storage: localStorage } = createStorage(); const adapter = createBrowserStorageAdapter({ localStorage }); expect(adapter.write("COLOR_SCHEME", "dark")).toEqual({ ok: true }); expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "dark" }); }); it("keeps local and session registry entries on their declared backends", () => { const local = createStorage(); const session = createStorage(); const adapter = createBrowserStorageAdapter({ localStorage: local.storage, sessionStorage: session.storage, }); expect(adapter.write("COLOR_SCHEME", "light")).toEqual({ ok: true }); expect(adapter.write("CHUNK_RELOAD_GUARD", "release-a->release-b")).toEqual({ ok: true, }); expect( local.values.has(STORAGE_REGISTRY.COLOR_SCHEME.physicalKey), ).toBe(true); expect( local.values.has(STORAGE_REGISTRY.CHUNK_RELOAD_GUARD.physicalKey), ).toBe(false); expect( session.values.has(STORAGE_REGISTRY.CHUNK_RELOAD_GUARD.physicalKey), ).toBe(true); expect(adapter.read("CHUNK_RELOAD_GUARD")).toEqual({ ok: true, value: "release-a->release-b", }); }); it("falls back to memory when preference storage quota is exceeded", () => { const { storage: localStorage } = createStorage({ writeFailure: "quota", }); const record = vi.fn(); const adapter = createBrowserStorageAdapter({ localStorage, diagnostics: { record }, }); expect(adapter.write("COLOR_SCHEME", "dark")).toMatchObject({ ok: false, fallback: "memory", error: { kind: "STORAGE_QUOTA_EXCEEDED" }, }); expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "dark" }); expect(record).toHaveBeenCalledOnce(); expect(record).toHaveBeenCalledWith({ level: "warn", eventId: "storage.operation.failed", context: { operation: "write:COLOR_SCHEME", error_kind: "STORAGE_QUOTA_EXCEEDED", reason: "QUOTA_EXCEEDED", }, }); expect(JSON.stringify(record.mock.calls)).not.toContain("dark"); expect(JSON.stringify(record.mock.calls)).not.toContain( "private quota detail", ); }); // 2026-11-01 05-06. The second quota name was in the adapter's list but no // test sent it, so dropping it went unseen. it("falls back to memory on Firefox's quota error name too", () => { const { storage: localStorage } = createStorage({ writeFailure: "firefox-quota", }); const adapter = createBrowserStorageAdapter({ localStorage }); expect(adapter.write("COLOR_SCHEME", "dark")).toMatchObject({ ok: false, fallback: "memory", error: { kind: "STORAGE_QUOTA_EXCEEDED" }, }); expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "dark" }); }); it("discards data from a previous schema version", () => { const { storage: localStorage, values, removeItem } = createStorage({ initial: { [STORAGE_REGISTRY.COLOR_SCHEME.physicalKey]: serializedEnvelope( "dark", { schemaVersion: 2 }, ), }, }); const adapter = createBrowserStorageAdapter({ localStorage }); expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: undefined }); expect(removeItem).toHaveBeenCalledOnce(); expect(values.has(STORAGE_REGISTRY.COLOR_SCHEME.physicalKey)).toBe(false); }); it("rejects values outside the selected key codec before persistence", () => { const { storage: localStorage, setItem } = createStorage(); const adapter = createBrowserStorageAdapter({ localStorage }); expect(adapter.write("COLOR_SCHEME", { mode: "dark" })).toMatchObject({ ok: false, error: { kind: "STORAGE_UNAVAILABLE", code: "COLOR_SCHEME_WRITE_VALUE_REJECTED", }, }); expect(setItem).not.toHaveBeenCalled(); }); it.each([ ["malformed JSON", "{private malformed value", "VALUE_REJECTED"], [ "invalid envelope", JSON.stringify({ schemaVersion: 1, expiresAt: null, value: "dark", unexpected: "private", }), "VALUE_REJECTED", ], ["oversized record", "x".repeat(512), "SIZE_LIMIT_EXCEEDED"], ])( "removes a %s once and suppresses it when native cleanup fails", (_label, raw, reason) => { const physicalKey = STORAGE_REGISTRY.COLOR_SCHEME.physicalKey; const { storage, getItem, removeItem } = createStorage({ initial: { [physicalKey]: raw }, removeFailure: "security", }); const record = vi.fn(); const adapter = createBrowserStorageAdapter({ localStorage: storage, diagnostics: { record }, maxSerializedBytes: 128, }); expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: undefined, }); expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: undefined, }); expect(getItem).toHaveBeenCalledOnce(); expect(removeItem).toHaveBeenCalledOnce(); // 05-02. A discarded value must not read as "storage unavailable". expect(record).toHaveBeenCalledWith({ level: "warn", eventId: "storage.operation.failed", context: { operation: "discard:COLOR_SCHEME", error_kind: "STORAGE_UNAVAILABLE", reason, }, }); expect(JSON.stringify(record.mock.calls)).not.toMatch( /private|malformed|unexpected/, ); }, ); it("removes expired persistent records and does not return their value", () => { const expiring = defineStorageKey({ logicalName: "EXPIRING_PREFERENCE", scope: "preference", name: "expiring", backend: "localStorage", classification: "public-preference", schemaVersion: 1, valueCodec: "opaque-string-v1", ttl: 10, migration: "discard", quotaFallback: "memory", }); const { storage, removeItem } = createStorage({ initial: { [expiring.physicalKey]: serializedEnvelope("private-expired", { expiresAt: 99, }), }, }); const adapter = createBrowserStorageAdapter({ localStorage: storage, now: () => 100, resolveDefinition: definitionResolver({ EXPIRING_PREFERENCE: expiring, }), }); expect(adapter.read("EXPIRING_PREFERENCE")).toEqual({ ok: true, value: undefined, }); expect(removeItem).toHaveBeenCalledWith(expiring.physicalKey); }); // 2026-11-01 05-06. A record is expired at its expiry instant, not after it. it.each([ [100, undefined], [101, "private-expiring"], ])("reads a record expiring at %i at time 100 as %s", (expiresAt, value) => { const expiring = defineStorageKey({ logicalName: "EXPIRING_PREFERENCE", scope: "preference", name: "expiring", backend: "localStorage", classification: "public-preference", schemaVersion: 1, valueCodec: "opaque-string-v1", ttl: 10, migration: "discard", quotaFallback: "memory", }); const { storage } = createStorage({ initial: { [expiring.physicalKey]: serializedEnvelope("private-expiring", { expiresAt, }), }, }); const adapter = createBrowserStorageAdapter({ localStorage: storage, now: () => 100, resolveDefinition: definitionResolver({ EXPIRING_PREFERENCE: expiring, }), }); expect(adapter.read("EXPIRING_PREFERENCE")).toEqual({ ok: true, value }); }); it("prioritizes a failed-write memory envelope over stale persistent data and expires it", () => { let timestamp = 100; const expiring = defineStorageKey({ logicalName: "EXPIRING_PREFERENCE", scope: "preference", name: "expiring", backend: "localStorage", classification: "public-preference", schemaVersion: 1, valueCodec: "opaque-string-v1", ttl: 10, migration: "discard", quotaFallback: "memory", }); const { storage, state } = createStorage({ initial: { [expiring.physicalKey]: serializedEnvelope("stale", { expiresAt: 1_000, }), }, writeFailure: "quota", }); const adapter = createBrowserStorageAdapter({ localStorage: storage, now: () => timestamp, resolveDefinition: definitionResolver({ EXPIRING_PREFERENCE: expiring, }), }); expect(adapter.write("EXPIRING_PREFERENCE", "fresh")).toMatchObject({ ok: false, fallback: "memory", }); expect(adapter.read("EXPIRING_PREFERENCE")).toEqual({ ok: true, value: "fresh", }); state.writeFailure = "none"; timestamp = 111; expect(adapter.read("EXPIRING_PREFERENCE")).toEqual({ ok: true, value: undefined, }); }); it("clears a failed-write overlay after a later persistent write succeeds", () => { const physicalKey = STORAGE_REGISTRY.COLOR_SCHEME.physicalKey; const { storage, state, values } = createStorage({ writeFailure: "security", }); const adapter = createBrowserStorageAdapter({ localStorage: storage }); expect(adapter.write("COLOR_SCHEME", "dark")).toMatchObject({ ok: false, fallback: "memory", error: { kind: "STORAGE_UNAVAILABLE" }, }); expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "dark", }); state.writeFailure = "none"; expect(adapter.write("COLOR_SCHEME", "light")).toEqual({ ok: true }); values.set(physicalKey, serializedEnvelope("system")); expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "system", }); }); it("purges the memory overlay even when persistent remove throws", () => { const { storage, state } = createStorage({ writeFailure: "quota", removeFailure: "security", }); const adapter = createBrowserStorageAdapter({ localStorage: storage }); expect(adapter.write("COLOR_SCHEME", "dark")).toMatchObject({ fallback: "memory", }); state.writeFailure = "none"; expect(adapter.remove("COLOR_SCHEME")).toMatchObject({ ok: false, error: { kind: "STORAGE_UNAVAILABLE" }, }); expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: undefined, }); }); it("normalizes SecurityError reads and never exposes native details", () => { const { storage } = createStorage({ readFailure: "security" }); const record = vi.fn(); const adapter = createBrowserStorageAdapter({ localStorage: storage, diagnostics: { record }, }); const result = adapter.read("COLOR_SCHEME"); expect(result).toMatchObject({ ok: false, error: { kind: "STORAGE_UNAVAILABLE", code: "COLOR_SCHEME_READ_UNAVAILABLE", }, }); expect(JSON.stringify({ result, calls: record.mock.calls })).not.toContain( "private security detail", ); }); it.each([ ["cyclic", (() => { const value: { self?: unknown; secret: string } = { secret: "private-cyclic", }; value.self = value; return value; })()], ["BigInt", { secret: "private-bigint", value: 1n }], ["exotic", new Date(0)], ])("rejects %s values before calling the backend", (_label, value) => { const { storage, setItem } = createStorage(); const record = vi.fn(); const adapter = createBrowserStorageAdapter({ localStorage: storage, diagnostics: { record }, }); const result = adapter.write("COLOR_SCHEME", value); expect(result).toMatchObject({ ok: false, error: { kind: "STORAGE_UNAVAILABLE", code: "COLOR_SCHEME_WRITE_VALUE_REJECTED", }, }); expect(setItem).not.toHaveBeenCalled(); expect(JSON.stringify({ result, calls: record.mock.calls })).not.toMatch( /private-cyclic|private-bigint/, ); }); it("rejects oversized serialized values before persistence and redacts them", () => { const secret = `private-oversize-${"x".repeat(512)}`; const { storage, setItem } = createStorage(); const record = vi.fn(); const adapter = createBrowserStorageAdapter({ sessionStorage: storage, diagnostics: { record }, maxSerializedBytes: 128, }); const result = adapter.write("CHUNK_RELOAD_GUARD", secret); expect(result).toMatchObject({ ok: false, error: { kind: "STORAGE_UNAVAILABLE", code: "CHUNK_RELOAD_GUARD_WRITE_SIZE_LIMIT_EXCEEDED", }, }); expect(record).toHaveBeenCalledWith( expect.objectContaining({ context: expect.objectContaining({ reason: "SIZE_LIMIT_EXCEEDED" }), }), ); expect(setItem).not.toHaveBeenCalled(); expect(JSON.stringify({ result, calls: record.mock.calls })).not.toContain( secret, ); }); });