peachsim 0.1.1641 → 0.1.1653

package/src/storageSnapshotContract.ts

@@ -0,0 +1,344 @@
+// the storage snapshot's wire shape, its validator, and the one translation a
+// non-browser host needs. this module is pure: no browser APIs, no compat
+// stubs, no engine runtime. that is what lets the rnx Cloud sim service
+// validate a create payload and seed a headless tenant without pulling the
+// preview host's IndexedDB and SecureStore machinery into a workerd isolate.
+//
+// storage-snapshot.ts owns the browser side (dump and restore) and re-exports
+// everything here, so callers keep importing one module.
+
+import type { AppSettingsSnapshot } from '#peach-cli-contract/permissions/app-settings-client'
+import type {
+  SootSimExternalAppResetResult,
+  SootSimStorageResetStrategy,
+} from '@peach/globals'
+
+export type TenantStorageClearResult = Pick<
+  SootSimExternalAppResetResult,
+  'cleared' | 'failures'
+>
+
+export type TenantStorageResetRequest =
+  | { scopeUrl?: string; strategy: 'keychain' }
+  | {
+      scopeUrl?: string
+      strategy: SootSimStorageResetStrategy
+      localStorageKeys: string[]
+      appSettings?: AppSettingsSnapshot
+    }
+
+export const SECURE_STORE_PLAINTEXT_PREFIX = '__sootsim_secure_store_plaintext:'
+
+const LEGACY_ASYNC_STORAGE_PREFIX = '@soot_as:'
+const NATIVE_ASYNC_STORAGE_PREFIX = '@sootsim:async-storage:'
+
+// reset partition vocabulary. mirrors tenantResetRemovesStorageKey in
+// storage-snapshot.ts and the skipped reasons in mcp/sim-reset.ts, so the
+// headless runner classifies the same keys the same way without pulling the
+// browser-side module into a workerd isolate. the literals mirror their
+// owners: async prefixes here, mmkv compat/stubs/mmkv-storage-contract,
+// user defaults storage-snapshot.ts, the auth cookie
+// render-worker/native-auth-cookies.
+export const RESET_ASYNC_STORAGE_PREFIXES = [
+  LEGACY_ASYNC_STORAGE_PREFIX,
+  NATIVE_ASYNC_STORAGE_PREFIX,
+] as const
+export const RESET_MMKV_STORAGE_PREFIX = '@sootsim_mmkv:'
+export const RESET_USER_DEFAULTS_PREFIX = 'rn-default-preference:'
+export const RESET_NATIVE_AUTH_COOKIE_KEY = '__rnx_native_auth_cookies'
+
+export type ResetStorageKind = 'async-storage' | 'mmkv' | 'user-defaults' | 'secure-store'
+
+export function resetStorageKindForKey(key: string): ResetStorageKind | null {
+  if (RESET_ASYNC_STORAGE_PREFIXES.some((prefix) => key.startsWith(prefix)))
+    return 'async-storage'
+  if (key.startsWith(RESET_MMKV_STORAGE_PREFIX)) return 'mmkv'
+  if (key.startsWith(RESET_USER_DEFAULTS_PREFIX)) return 'user-defaults'
+  if (
+    key.startsWith(SECURE_STORE_PLAINTEXT_PREFIX) ||
+    key === RESET_NATIVE_AUTH_COOKIE_KEY
+  )
+    return 'secure-store'
+  return null
+}
+
+// data wipes app data and keeps install-scoped credentials; full wipes those
+// too. unknown keys are kept by both, exactly like the page path: a reset
+// removes named stores, never an arbitrary host key.
+export function resetRemovesStorageKey(key: string, strategy: 'data' | 'full'): boolean {
+  const kind = resetStorageKindForKey(key)
+  if (kind === 'async-storage' || kind === 'mmkv') return true
+  if (strategy !== 'full') return false
+  return kind === 'user-defaults' || kind === 'secure-store'
+}
+
+export type StorageSnapshotEntry = {
+  key: string
+  value: string
+}
+
+export type SecureStoreSnapshotEntry = {
+  key: string
+  value: string
+  keychainService?: string
+  accessGroup?: string
+  requireAuthentication?: boolean
+}
+
+export type IndexedDBSnapshotKind =
+  | 'bedrock-memfs'
+  | 'blob-util-fs'
+  | 'react-native-keychain'
+  | 'sootsim-system-permissions'
+
+export type SerializedIndexedDBValue =
+  | { type: 'array'; value: SerializedIndexedDBValue[] }
+  | { type: 'array-buffer'; value: string }
+  | { type: 'null'; value: null }
+  | { type: 'object'; value: Record<string, SerializedIndexedDBValue> }
+  | { type: 'primitive'; value: boolean | number | string }
+  | { type: 'uint8-array'; value: string }
+
+export type IndexedDBSnapshotEntry = {
+  key: string
+  value: SerializedIndexedDBValue
+}
+
+export type IndexedDBStoreSnapshot = {
+  name: string
+  entries: IndexedDBSnapshotEntry[]
+}
+
+export type IndexedDBSnapshot = {
+  kind: IndexedDBSnapshotKind
+  stores: IndexedDBStoreSnapshot[]
+  sourceAppId?: string
+}
+
+export type PreviewRouteSnapshot = {
+  currentPath: string
+  routeNames?: string[]
+}
+
+export type ShareableStorageSnapshot = {
+  entries: StorageSnapshotEntry[]
+  indexedDB?: IndexedDBSnapshot[]
+  route?: PreviewRouteSnapshot
+}
+
+// legacy snapshots may contain SecureStore values in their own field. keep the
+// read shape until existing shares are remediated. a snapshot captured today
+// carries credentials, when it carries them at all, as the plaintext-shadow
+// localStorage entries the SecureStore stub itself reads first.
+export type StorageSnapshot = ShareableStorageSnapshot & {
+  secureStore?: SecureStoreSnapshotEntry[]
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isStorageSnapshotEntry(value: unknown): value is StorageSnapshotEntry {
+  return (
+    isRecord(value) && typeof value.key === 'string' && typeof value.value === 'string'
+  )
+}
+
+function isSecureStoreSnapshotEntry(value: unknown): value is SecureStoreSnapshotEntry {
+  return (
+    isRecord(value) &&
+    typeof value.key === 'string' &&
+    typeof value.value === 'string' &&
+    (value.keychainService == null || typeof value.keychainService === 'string') &&
+    (value.accessGroup == null || typeof value.accessGroup === 'string') &&
+    (value.requireAuthentication == null ||
+      typeof value.requireAuthentication === 'boolean')
+  )
+}
+
+export function isPreviewRouteSnapshot(value: unknown): value is PreviewRouteSnapshot {
+  return (
+    isRecord(value) &&
+    typeof value.currentPath === 'string' &&
+    (value.routeNames == null ||
+      (Array.isArray(value.routeNames) &&
+        value.routeNames.every((routeName) => typeof routeName === 'string')))
+  )
+}
+
+function isSerializedIndexedDBValue(value: unknown): value is SerializedIndexedDBValue {
+  if (!isRecord(value) || typeof value.type !== 'string') return false
+  switch (value.type) {
+    case 'array':
+      return Array.isArray(value.value) && value.value.every(isSerializedIndexedDBValue)
+    case 'array-buffer':
+    case 'uint8-array':
+      return typeof value.value === 'string'
+    case 'null':
+      return value.value === null
+    case 'object':
+      return (
+        isRecord(value.value) &&
+        Object.values(value.value).every(isSerializedIndexedDBValue)
+      )
+    case 'primitive':
+      return (
+        typeof value.value === 'boolean' ||
+        typeof value.value === 'number' ||
+        typeof value.value === 'string'
+      )
+    default:
+      return false
+  }
+}
+
+function isIndexedDBSnapshotKind(value: unknown): value is IndexedDBSnapshotKind {
+  return (
+    value === 'bedrock-memfs' ||
+    value === 'blob-util-fs' ||
+    value === 'react-native-keychain' ||
+    value === 'sootsim-system-permissions'
+  )
+}
+
+function isIndexedDBSnapshotEntry(value: unknown): value is IndexedDBSnapshotEntry {
+  return (
+    isRecord(value) &&
+    typeof value.key === 'string' &&
+    isSerializedIndexedDBValue(value.value)
+  )
+}
+
+function isIndexedDBStoreSnapshot(value: unknown): value is IndexedDBStoreSnapshot {
+  return (
+    isRecord(value) &&
+    typeof value.name === 'string' &&
+    Array.isArray(value.entries) &&
+    value.entries.every(isIndexedDBSnapshotEntry)
+  )
+}
+
+function isIndexedDBSnapshot(value: unknown): value is IndexedDBSnapshot {
+  return (
+    isRecord(value) &&
+    isIndexedDBSnapshotKind(value.kind) &&
+    (value.sourceAppId == null ||
+      (value.kind === 'sootsim-system-permissions' &&
+        typeof value.sourceAppId === 'string' &&
+        value.sourceAppId.length > 0)) &&
+    Array.isArray(value.stores) &&
+    value.stores.every(isIndexedDBStoreSnapshot)
+  )
+}
+
+export function isStorageSnapshot(value: unknown): value is StorageSnapshot {
+  return (
+    isRecord(value) &&
+    Array.isArray(value.entries) &&
+    value.entries.every(isStorageSnapshotEntry) &&
+    (value.secureStore == null ||
+      (Array.isArray(value.secureStore) &&
+        value.secureStore.every(isSecureStoreSnapshotEntry))) &&
+    (value.indexedDB == null ||
+      (Array.isArray(value.indexedDB) && value.indexedDB.every(isIndexedDBSnapshot))) &&
+    (value.route == null || isPreviewRouteSnapshot(value.route))
+  )
+}
+
+export function normalizeStorageSnapshotKey(key: string): string {
+  if (!key.startsWith(LEGACY_ASYNC_STORAGE_PREFIX)) return key
+  return `${NATIVE_ASYNC_STORAGE_PREFIX}${key.slice(LEGACY_ASYNC_STORAGE_PREFIX.length)}`
+}
+
+export function secureStoreRecordKey(
+  scope: string,
+  entry: SecureStoreSnapshotEntry,
+): string {
+  const service = entry.keychainService ?? 'app'
+  const accessGroup = entry.accessGroup ?? ''
+  const auth = entry.requireAuthentication ? 'auth' : 'no-auth'
+  return `${scope}:${service}:${accessGroup}:${auth}:${entry.key}`
+}
+
+export function secureStorePlaintextKey(recordKey: string): string {
+  return `${SECURE_STORE_PLAINTEXT_PREFIX}${recordKey}`
+}
+
+// a plaintext shadow key is `<prefix><scope>:<service>:<group>:<auth>:<key>`,
+// and deriveBedrockTenantScope sanitizes a scope to [A-Za-z0-9_-], so the first
+// colon after the prefix always ends it. that makes the scope swappable by
+// position without parsing the rest, which matters because an app's own key may
+// itself contain colons.
+function rescopeSecureStorePlaintextKey(key: string, scope: string): string {
+  const rest = key.slice(SECURE_STORE_PLAINTEXT_PREFIX.length)
+  const separator = rest.indexOf(':')
+  if (separator < 0) return key
+  return `${SECURE_STORE_PLAINTEXT_PREFIX}${scope}${rest.slice(separator)}`
+}
+
+/**
+ * the guest-visible localStorage a headless tenant boots with, given a snapshot
+ * captured somewhere else.
+ *
+ * a headless tenant has one flat localStorage keyed exactly as the guest wrote
+ * it, so a snapshot's `entries` transfer directly. SecureStore is the one thing
+ * that needs rewriting: its record keys embed the capturing host's tenant scope,
+ * which is derived from that host's bundle URL and never matches the tenant's.
+ * the stub reads its plaintext shadow before it reaches for encrypted storage,
+ * so restoring the shadow under this tenant's scope is what carries a signed-in
+ * session across.
+ *
+ * IndexedDB is absent: workerd has none, so the snapshot's `indexedDB` stores
+ * (the blob-util filesystem, bedrock's memfs, the keychain, system permissions)
+ * cannot be restored in a cloud simulator and are dropped here rather than
+ * failing the boot.
+ */
+export function storageSnapshotTenantEntries(
+  snapshot: StorageSnapshot,
+  tenantScope: string,
+): Array<[string, string]> {
+  const entries = new Map<string, string>()
+  for (const entry of snapshot.entries) {
+    const key = normalizeStorageSnapshotKey(entry.key)
+    entries.set(
+      key.startsWith(SECURE_STORE_PLAINTEXT_PREFIX)
+        ? rescopeSecureStorePlaintextKey(key, tenantScope)
+        : key,
+      entry.value,
+    )
+  }
+  for (const entry of snapshot.secureStore ?? []) {
+    if (!entry.key) continue
+    entries.set(
+      secureStorePlaintextKey(secureStoreRecordKey(tenantScope, entry)),
+      entry.value,
+    )
+  }
+  return [...entries.entries()]
+}
+
+// a share carries no SecureStore values and no keychain: `/preview/<id>` and
+// every recording upload read this shape.
+export function prepareStorageSnapshotForShare(
+  snapshot: StorageSnapshot,
+): ShareableStorageSnapshot {
+  const entries = snapshot.entries.filter(
+    (entry) => !entry.key.startsWith(SECURE_STORE_PLAINTEXT_PREFIX),
+  )
+  const indexedDB = snapshot.indexedDB?.filter(
+    (entry) => entry.kind !== 'react-native-keychain',
+  )
+  return {
+    entries,
+    ...(indexedDB && indexedDB.length > 0 ? { indexedDB } : null),
+    ...(snapshot.route ? { route: snapshot.route } : null),
+  }
+}
+
+export function hasShareableStorage(snapshot: ShareableStorageSnapshot): boolean {
+  return (
+    snapshot.entries.length > 0 ||
+    (snapshot.indexedDB?.length ?? 0) > 0 ||
+    snapshot.route != null
+  )
+}