const APP_NAMESPACE = "ca-frontend"; export type StorageBackend = | "memory" | "sessionStorage" | "localStorage" | "disabled" | "forbidden" /** * Another adapter owns the value format and writes the physical key itself. * The registry only owns the name, so StoragePort refuses the key. */ | "external"; export type StorageValueCodec = | "color-scheme-v1" | "opaque-string-v1" | "none"; export type StorageKeyInput = Readonly<{ logicalName: string; scope: string; name: string; backend: StorageBackend; classification: | "public-preference" | "opaque-cache" | "sensitive-forbidden"; schemaVersion: number; valueCodec: StorageValueCodec; ttl: number | "session" | null; migration: "discard"; quotaFallback: "memory" | "no-persist" | "feature-disable"; }>; export type StorageDefinition = Readonly< StorageKeyInput & { physicalKey: string } >; export const STORAGE_REGISTRY = Object.freeze({ COLOR_SCHEME: defineStorageKey({ logicalName: "COLOR_SCHEME", scope: "preference", name: "color-scheme", backend: "localStorage", classification: "public-preference", schemaVersion: 1, valueCodec: "color-scheme-v1", ttl: null, migration: "discard", quotaFallback: "memory", }), /** The chosen UI locale. Presentation normalizes whatever it reads back. */ LOCALE: defineStorageKey({ logicalName: "LOCALE", scope: "preference", name: "locale", backend: "localStorage", classification: "public-preference", schemaVersion: 1, valueCodec: "opaque-string-v1", ttl: null, migration: "discard", quotaFallback: "memory", }), CHUNK_RELOAD_GUARD: defineStorageKey({ logicalName: "CHUNK_RELOAD_GUARD", scope: "release", name: "chunk-reload-guard", backend: "sessionStorage", classification: "opaque-cache", schemaVersion: 1, valueCodec: "opaque-string-v1", ttl: "session", migration: "discard", quotaFallback: "no-persist", }), /** * scale-architecture.md ยง45 / release-coherence plan Task 6. One reload-once marker per boot * release-mismatch key, so a mixed rolling release can recover with one * fresh HTML fetch but can never reload-loop. */ RELEASE_MISMATCH_RECOVERY: defineStorageKey({ logicalName: "RELEASE_MISMATCH_RECOVERY", scope: "release", name: "boot-mismatch-recovery", backend: "sessionStorage", classification: "opaque-cache", schemaVersion: 1, valueCodec: "opaque-string-v1", ttl: "session", migration: "discard", quotaFallback: "no-persist", }), QUERY_PERSISTENCE: defineStorageKey({ logicalName: "QUERY_PERSISTENCE", scope: "cache", name: "query-persistence", backend: "disabled", classification: "sensitive-forbidden", schemaVersion: 1, valueCodec: "none", ttl: null, migration: "discard", quotaFallback: "feature-disable", }), /** * 05-01. The cross-context invalidation adapter writes raw wire JSON to this * localStorage key with no envelope. Only the physical key name lives here. * The key string is a channel between deployed tabs and must not change. */ CACHE_INVALIDATION_PULSE: defineStorageKey({ logicalName: "CACHE_INVALIDATION_PULSE", scope: "cache-invalidation", name: "pulse", backend: "external", classification: "opaque-cache", schemaVersion: 1, valueCodec: "none", ttl: null, migration: "discard", quotaFallback: "no-persist", }), AUTH_TOKEN: defineStorageKey({ logicalName: "AUTH_TOKEN", scope: "auth", name: "auth-token", backend: "forbidden", classification: "sensitive-forbidden", schemaVersion: 1, valueCodec: "none", ttl: null, migration: "discard", quotaFallback: "feature-disable", }), /** * 1105/05-01. The OIDC PKCE session owner recipe * (`recipes/session-owners/oidc-pkce-session-owner.ts`) keeps one sign-in * transaction here in sessionStorage: the PKCE verifier, `state`, `nonce` * and the return path, never a token, for at most ten minutes, and the * callback deletes it first. The recipe owns the value format, so only the * name lives here and StoragePort refuses the key. It is not * `sensitive-forbidden`, which means "never stored"; this one is stored by * design for one redirect. */ AUTH_REDIRECT_TRANSACTION: defineStorageKey({ logicalName: "AUTH_REDIRECT_TRANSACTION", scope: "auth", name: "oidc-pkce-transaction", backend: "external", classification: "opaque-cache", schemaVersion: 1, valueCodec: "none", ttl: "session", migration: "discard", quotaFallback: "no-persist", }), }); export function defineStorageKey( definition: Definition, ): Readonly { if ( !["color-scheme-v1", "opaque-string-v1", "none"].includes( definition.valueCodec, ) ) { throw new Error("Unknown client storage value codec"); } if (definition.migration !== "discard") { throw new Error("Unsupported client storage migration policy"); } if (definition.classification === "sensitive-forbidden") { if (!["disabled", "forbidden"].includes(definition.backend)) { throw new Error("Sensitive client storage registration is forbidden"); } if (definition.valueCodec !== "none") { throw new Error("Sensitive client storage codec is forbidden"); } } else if (definition.backend === "external") { if (definition.valueCodec !== "none") { throw new Error("Externally owned storage keys have no StoragePort codec"); } } else if (definition.valueCodec === "none") { throw new Error("Persisted storage keys require a value codec"); } if (!Number.isInteger(definition.schemaVersion) || definition.schemaVersion < 1) { throw new Error("Storage schemaVersion must be a positive integer"); } return Object.freeze({ ...definition, physicalKey: buildPhysicalKey( definition.scope, definition.schemaVersion, definition.name, ), }); } export function buildPhysicalKey( scope: string, schemaVersion: number, name: string, ): string { return `${APP_NAMESPACE}:${scope}:v${schemaVersion}:${name}`; } export function getStorageDefinition(logicalName: string): StorageDefinition { const registry: Readonly> = STORAGE_REGISTRY; const definition = Object.hasOwn(registry, logicalName) ? registry[logicalName] : undefined; if (!definition) throw new Error(`Unregistered storage key: ${logicalName}`); if (definition.classification === "sensitive-forbidden") { throw new Error(`Forbidden storage key: ${logicalName}`); } if (definition.backend === "external") { throw new Error(`Externally owned storage key: ${logicalName}`); } return definition; } export function isStorageValueAllowed( definition: StorageDefinition, value: unknown, ): boolean { switch (definition.valueCodec) { case "color-scheme-v1": return value === "light" || value === "dark" || value === "system"; case "opaque-string-v1": return ( typeof value === "string" && value.length >= 1 && value.length <= 2_048 ); default: return false; } }