strata-storage 2.4.2 → 2.5.0

package/dist/utils/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAW7D;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,SAA2B,EAAE,OAAO,CAAC,EAAE,OAAO;CAIlE;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,WAAW;gBAC3C,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAInD;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;gBACpC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAOvE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,SAAgC,EAAE,OAAO,CAAC,EAAE,OAAO;CAIvE;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,OAAO,SAAiC,EAAE,OAAO,CAAC,EAAE,OAAO;CAIxE;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,SAAyB,EAAE,OAAO,CAAC,EAAE,OAAO;CAIhE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,OAAO,SAAuB,EAAE,OAAO,CAAC,EAAE,OAAO;CAI9D;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,WAAW;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,WAAW;gBAC5B,OAAO,SAA0B,EAAE,OAAO,CAAC,EAAE,OAAO;CAIjE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,WAAW;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBAChC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI3C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAepD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAe7D;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,SAA2B,EAAE,OAAO,CAAC,EAAE,OAAO;CAIlE;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,WAAW;gBAC3C,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAInD;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;gBACpC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAOvE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,SAAgC,EAAE,OAAO,CAAC,EAAE,OAAO;CAIvE;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,OAAO,SAAiC,EAAE,OAAO,CAAC,EAAE,OAAO;CAIxE;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,SAAyB,EAAE,OAAO,CAAC,EAAE,OAAO;CAIhE;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,WAAW;gBACjC,OAAO,SAAgC,EAAE,OAAO,CAAC,EAAE,OAAO;CAIvE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,OAAO,SAAuB,EAAE,OAAO,CAAC,EAAE,OAAO;CAI9D;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,WAAW;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,WAAW;gBAC5B,OAAO,SAA0B,EAAE,OAAO,CAAC,EAAE,OAAO;CAIjE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,WAAW;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBAChC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI3C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAepD"}

package/dist/utils/errors.js

@@ -12,9 +12,11 @@ export class StrataError extends Error {
         this.name = 'StrataError';
         this.code = code;
         this.details = details;
-        // Maintains proper stack trace for where our error was thrown
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, this.constructor);
+        // Maintains proper stack trace for where our error was thrown (V8-only API,
+        // typed locally so the zero-dependency core needs no @types/node).
+        const ErrorCtor = Error;
+        if (ErrorCtor.captureStackTrace) {
+            ErrorCtor.captureStackTrace(this, this.constructor);
         }
     }
 }
@@ -75,6 +77,16 @@ export class SerializationError extends StrataError {
         this.name = 'SerializationError';
     }
 }
+/**
+ * Error thrown when a stored value fails its integrity checksum (data
+ * corruption), or when a snapshot fails validation during restore.
+ */
+export class IntegrityError extends StrataError {
+    constructor(message = 'Data integrity check failed', details) {
+        super(message, 'INTEGRITY_ERROR', details);
+        this.name = 'IntegrityError';
+    }
+}
 /**
  * Error thrown when validation fails
  */

package/dist/utils/index.d.ts

@@ -23,7 +23,16 @@ export declare function isCapacitor(): boolean;
  */
 export declare function deepClone<T>(obj: T): T;
 /**
- * Deep merge objects
+ * Check whether a key is safe to copy into a target object. Rejects the keys
+ * that prototype-pollution payloads use (`__proto__`, `constructor`,
+ * `prototype`). Use whenever merging/assigning keys from untrusted JSON.
+ */
+export declare function isSafeKey(key: string): boolean;
+/**
+ * Deep merge objects.
+ *
+ * Security: skips the prototype-pollution keys (`__proto__`, `constructor`,
+ * `prototype`) so a malicious source object cannot mutate `Object.prototype`.
  */
 export declare function deepMerge<T extends Record<string, unknown>>(target: T, ...sources: Partial<T>[]): T;
 /**
@@ -35,7 +44,39 @@ export declare function isObject(item: unknown): item is Record<string, unknown>
  */
 export declare function generateId(): string;
 /**
- * Simple glob pattern matching
+ * Maximum length of a regex source string we are willing to compile from
+ * caller-supplied input (glob patterns, `$regex` query operands, deserialized
+ * RegExp). A hard cap is the simplest robust mitigation against catastrophic
+ * backtracking (ReDoS): an attacker cannot supply an arbitrarily long pattern
+ * that takes exponential time to match. 1000 chars comfortably fits every
+ * legitimate key glob / field regex while bounding worst-case work.
+ *
+ * NOTE: This caps pattern LENGTH, not matching complexity. A short pattern can
+ * still backtrack pathologically (e.g. `(a+)+$`). The JS RegExp engine has no
+ * timeout, so callers passing patterns from fully untrusted sources should
+ * validate them, prefer literal/prefix matching, or run matching off the main
+ * thread. Strata never builds a RegExp from a value it stores itself.
+ */
+export declare const SAFE_REGEX_MAX_LENGTH = 1000;
+/**
+ * Construct a RegExp from a possibly-untrusted source with two safety guards:
+ * 1. The source length is capped at {@link SAFE_REGEX_MAX_LENGTH} — an
+ *    over-long pattern is rejected up front instead of being compiled.
+ * 2. Compilation is wrapped so an invalid pattern throws a clear, typed error
+ *    rather than leaking a raw `SyntaxError`.
+ *
+ * This does NOT alter matching semantics for valid, reasonably-sized patterns —
+ * the resulting RegExp behaves identically to `new RegExp(source, flags)`.
+ *
+ * @throws {ValidationError} if the source exceeds the length cap or is invalid.
+ */
+export declare function safeRegExp(source: string, flags?: string): RegExp;
+/**
+ * Simple glob pattern matching.
+ *
+ * Security: glob metacharacters are escaped before compilation and the source
+ * is length-capped via {@link safeRegExp}, so a hostile glob cannot inject an
+ * arbitrary regex or supply an unbounded pattern.
  */
 export declare function matchGlob(pattern: string, str: string): boolean;
 /**
@@ -84,7 +125,13 @@ export declare function createDeferred<T>(): {
  */
 export declare function serialize(value: unknown): string;
 /**
- * Deserialize JSON with support for special types
+ * Deserialize JSON with support for special types.
+ *
+ * Security: the reviver drops the prototype-pollution keys (`__proto__`,
+ * `constructor`, `prototype`) by returning `undefined` for them, so parsing
+ * untrusted JSON cannot smuggle a polluting key into the resulting object.
+ * The reconstructed RegExp is built from a length-capped source to avoid
+ * pathological patterns (see SAFE_REGEX_MAX_LENGTH).
  */
 export declare function deserialize(json: string): unknown;
 /**
@@ -103,11 +150,22 @@ export declare class EventEmitter {
     removeAllListeners(event?: string): void;
 }
 /**
- * Check if a value is a valid storage key
+ * Upper bound on storage-key length. Real keys are short; an unbounded key is a
+ * memory/DoS vector and offers no legitimate benefit. 1024 chars is generous.
+ */
+export declare const MAX_KEY_LENGTH = 1024;
+/**
+ * Check if a value is a valid storage key.
+ *
+ * A valid key is a non-empty string within {@link MAX_KEY_LENGTH} characters
+ * that is not a prototype-pollution key (`__proto__`, `constructor`,
+ * `prototype`) — those must never be used as storage keys.
  */
 export declare function isValidKey(key: unknown): key is string;
 /**
- * Check if a value can be stored
+ * Check if a value can be stored. Allows any value except `undefined`. Symbols
+ * and functions are rejected because they are not JSON-serializable and cannot
+ * round-trip through any storage backend.
  */
 export declare function isValidValue(value: unknown): boolean;
 /**

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.js

@@ -3,6 +3,7 @@
  * Zero dependencies - all utilities implemented from scratch
  */
 import { ValidationError } from "./errors.js";
+import { logger } from "./logger.js";
 /**
  * Check if code is running in a browser environment
  */
@@ -13,9 +14,10 @@ export function isBrowser() {
  * Check if code is running in Node.js
  */
 export function isNode() {
-    return (typeof process !== 'undefined' &&
-        process.versions !== undefined &&
-        process.versions.node !== undefined);
+    // Access `process` through globalThis so the universal core compiles without
+    // Node ambient types and never throws in browsers where `process` is absent.
+    const proc = globalThis.process;
+    return proc?.versions?.node !== undefined;
 }
 /**
  * Check if code is running in a Web Worker
@@ -51,7 +53,23 @@ export function deepClone(obj) {
     return clonedObj;
 }
 /**
- * Deep merge objects
+ * Keys that must never be copied during a merge/assign of untrusted data —
+ * setting them can pollute `Object.prototype` (prototype pollution).
+ */
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * Check whether a key is safe to copy into a target object. Rejects the keys
+ * that prototype-pollution payloads use (`__proto__`, `constructor`,
+ * `prototype`). Use whenever merging/assigning keys from untrusted JSON.
+ */
+export function isSafeKey(key) {
+    return !FORBIDDEN_KEYS.has(key);
+}
+/**
+ * Deep merge objects.
+ *
+ * Security: skips the prototype-pollution keys (`__proto__`, `constructor`,
+ * `prototype`) so a malicious source object cannot mutate `Object.prototype`.
  */
 export function deepMerge(target, ...sources) {
     if (!sources.length)
@@ -59,6 +77,9 @@ export function deepMerge(target, ...sources) {
     const source = sources.shift();
     if (isObject(target) && isObject(source)) {
         for (const key in source) {
+            // Skip own dangerous keys; never let untrusted data reach the prototype.
+            if (!Object.prototype.hasOwnProperty.call(source, key) || !isSafeKey(key))
+                continue;
             if (isObject(source[key])) {
                 if (!target[key])
                     Object.assign(target, { [key]: {} });
@@ -86,14 +107,62 @@ export function generateId() {
     return `${timestamp}-${randomPart}`;
 }
 /**
- * Simple glob pattern matching
+ * Maximum length of a regex source string we are willing to compile from
+ * caller-supplied input (glob patterns, `$regex` query operands, deserialized
+ * RegExp). A hard cap is the simplest robust mitigation against catastrophic
+ * backtracking (ReDoS): an attacker cannot supply an arbitrarily long pattern
+ * that takes exponential time to match. 1000 chars comfortably fits every
+ * legitimate key glob / field regex while bounding worst-case work.
+ *
+ * NOTE: This caps pattern LENGTH, not matching complexity. A short pattern can
+ * still backtrack pathologically (e.g. `(a+)+$`). The JS RegExp engine has no
+ * timeout, so callers passing patterns from fully untrusted sources should
+ * validate them, prefer literal/prefix matching, or run matching off the main
+ * thread. Strata never builds a RegExp from a value it stores itself.
+ */
+export const SAFE_REGEX_MAX_LENGTH = 1000;
+/**
+ * Construct a RegExp from a possibly-untrusted source with two safety guards:
+ * 1. The source length is capped at {@link SAFE_REGEX_MAX_LENGTH} — an
+ *    over-long pattern is rejected up front instead of being compiled.
+ * 2. Compilation is wrapped so an invalid pattern throws a clear, typed error
+ *    rather than leaking a raw `SyntaxError`.
+ *
+ * This does NOT alter matching semantics for valid, reasonably-sized patterns —
+ * the resulting RegExp behaves identically to `new RegExp(source, flags)`.
+ *
+ * @throws {ValidationError} if the source exceeds the length cap or is invalid.
+ */
+export function safeRegExp(source, flags) {
+    if (source.length > SAFE_REGEX_MAX_LENGTH) {
+        throw new ValidationError('Regular expression pattern is too long', {
+            length: source.length,
+            max: SAFE_REGEX_MAX_LENGTH,
+        });
+    }
+    try {
+        return new RegExp(source, flags);
+    }
+    catch (error) {
+        throw new ValidationError('Invalid regular expression pattern', {
+            pattern: source,
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Simple glob pattern matching.
+ *
+ * Security: glob metacharacters are escaped before compilation and the source
+ * is length-capped via {@link safeRegExp}, so a hostile glob cannot inject an
+ * arbitrary regex or supply an unbounded pattern.
  */
 export function matchGlob(pattern, str) {
     const regexPattern = pattern
         .replace(/[.+^${}()|[\]\\]/g, '\\$&')
         .replace(/\*/g, '.*')
         .replace(/\?/g, '.');
-    return new RegExp(`^${regexPattern}$`).test(str);
+    return safeRegExp(`^${regexPattern}$`).test(str);
 }
 /**
  * Format bytes to human readable
@@ -233,17 +302,26 @@ export function serialize(value) {
     });
 }
 /**
- * Deserialize JSON with support for special types
+ * Deserialize JSON with support for special types.
+ *
+ * Security: the reviver drops the prototype-pollution keys (`__proto__`,
+ * `constructor`, `prototype`) by returning `undefined` for them, so parsing
+ * untrusted JSON cannot smuggle a polluting key into the resulting object.
+ * The reconstructed RegExp is built from a length-capped source to avoid
+ * pathological patterns (see SAFE_REGEX_MAX_LENGTH).
  */
 export function deserialize(json) {
-    return JSON.parse(json, (_, val) => {
+    return JSON.parse(json, (key, val) => {
+        // Returning undefined from a reviver removes the property from the result.
+        if (!isSafeKey(key))
+            return undefined;
         if (val && typeof val === 'object' && '__type' in val) {
             switch (val.__type) {
                 case 'Date':
                     return new Date(val.value);
                 case 'RegExp': {
-                    const match = val.value.match(/^\/(.*)\/([gimuy]*)$/);
-                    return match ? new RegExp(match[1], match[2]) : new RegExp(val.value);
+                    const match = typeof val.value === 'string' ? val.value.match(/^\/(.*)\/([gimuy]*)$/) : null;
+                    return match ? safeRegExp(match[1], match[2]) : safeRegExp(String(val.value));
                 }
                 case 'Map':
                     return new Map(val.value);
@@ -312,7 +390,7 @@ export class EventEmitter {
                 handler(...args);
             }
             catch (error) {
-                console.error(`Error in event handler for ${event}:`, error);
+                logger.error(`Error in event handler for ${event}:`, error);
             }
         });
     }
@@ -333,17 +411,32 @@ export class EventEmitter {
     }
 }
 /**
- * Check if a value is a valid storage key
+ * Upper bound on storage-key length. Real keys are short; an unbounded key is a
+ * memory/DoS vector and offers no legitimate benefit. 1024 chars is generous.
+ */
+export const MAX_KEY_LENGTH = 1024;
+/**
+ * Check if a value is a valid storage key.
+ *
+ * A valid key is a non-empty string within {@link MAX_KEY_LENGTH} characters
+ * that is not a prototype-pollution key (`__proto__`, `constructor`,
+ * `prototype`) — those must never be used as storage keys.
  */
 export function isValidKey(key) {
-    return typeof key === 'string' && key.length > 0;
+    return (typeof key === 'string' && key.length > 0 && key.length <= MAX_KEY_LENGTH && isSafeKey(key));
 }
 /**
- * Check if a value can be stored
+ * Check if a value can be stored. Allows any value except `undefined`. Symbols
+ * and functions are rejected because they are not JSON-serializable and cannot
+ * round-trip through any storage backend.
  */
 export function isValidValue(value) {
-    // Allow all values except undefined
-    return value !== undefined;
+    if (value === undefined)
+        return false;
+    const t = typeof value;
+    if (t === 'function' || t === 'symbol')
+        return false;
+    return true;
 }
 /**
  * Serialize a value for storage

package/dist/utils/logger.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Internal logger for Strata Storage.
+ *
+ * A library must never spam the consumer's console, so every diagnostic message
+ * routes through this single, level-gated logger instead of calling `console.*`
+ * directly. It deliberately does NOT patch the global `console` (that would be
+ * hostile to consumers) — it only forwards to it when the level allows.
+ *
+ * Default level is `warn`: warnings and errors surface (they signal real
+ * problems), while `debug`/`info` stay quiet. Raise verbosity with
+ * `new Strata({ debug: true })`, `setLogLevel('debug')`, or — in a browser
+ * devtools session — `globalThis.__strataSetLogLevel('debug')`.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/** Set the global log level for all Strata diagnostic output. */
+export declare function setLogLevel(level: LogLevel): void;
+/** Get the current global log level. */
+export declare function getLogLevel(): LogLevel;
+export declare const logger: {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+};
+/**
+ * Expose runtime log-level controls on the global scope for devtools use.
+ * Call once (e.g. from a Strata instance) — never auto-invoked at module load
+ * so the package stays free of import-time side effects (`sideEffects: false`).
+ */
+export declare function exposeLogLevelControls(): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AActE,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED,wCAAwC;AACxC,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAOD,eAAO,MAAM,MAAM;mBACF,OAAO,EAAE,GAAG,IAAI;kBAGjB,OAAO,EAAE,GAAG,IAAI;kBAGhB,OAAO,EAAE,GAAG,IAAI;mBAGf,OAAO,EAAE,GAAG,IAAI;CAGhC,CAAC;AAGF;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAO7C"}

package/dist/utils/logger.js

@@ -0,0 +1,63 @@
+/**
+ * Internal logger for Strata Storage.
+ *
+ * A library must never spam the consumer's console, so every diagnostic message
+ * routes through this single, level-gated logger instead of calling `console.*`
+ * directly. It deliberately does NOT patch the global `console` (that would be
+ * hostile to consumers) — it only forwards to it when the level allows.
+ *
+ * Default level is `warn`: warnings and errors surface (they signal real
+ * problems), while `debug`/`info` stay quiet. Raise verbosity with
+ * `new Strata({ debug: true })`, `setLogLevel('debug')`, or — in a browser
+ * devtools session — `globalThis.__strataSetLogLevel('debug')`.
+ */
+const LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+const PREFIX = '[strata-storage]';
+let currentLevel = 'warn';
+/** Set the global log level for all Strata diagnostic output. */
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+/** Get the current global log level. */
+export function getLogLevel() {
+    return currentLevel;
+}
+function isEnabled(level) {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[currentLevel];
+}
+/* eslint-disable no-console -- this module is the single sanctioned console boundary */
+export const logger = {
+    debug(...args) {
+        if (isEnabled('debug'))
+            console.debug(PREFIX, ...args);
+    },
+    info(...args) {
+        if (isEnabled('info'))
+            console.info(PREFIX, ...args);
+    },
+    warn(...args) {
+        if (isEnabled('warn'))
+            console.warn(PREFIX, ...args);
+    },
+    error(...args) {
+        if (isEnabled('error'))
+            console.error(PREFIX, ...args);
+    },
+};
+/* eslint-enable no-console */
+/**
+ * Expose runtime log-level controls on the global scope for devtools use.
+ * Call once (e.g. from a Strata instance) — never auto-invoked at module load
+ * so the package stays free of import-time side effects (`sideEffects: false`).
+ */
+export function exposeLogLevelControls() {
+    const scope = globalThis;
+    scope.__strataSetLogLevel = setLogLevel;
+    scope.__strataGetLogLevel = getLogLevel;
+}

package/ios/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md — ios/
+
+Last Updated: 2026-04-03
+
+> Agent instructions for iOS native development.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `Plugin/StrataStoragePlugin.swift` | Capacitor plugin entry |
+| `Plugin/UserDefaultsStorage.swift` | General key-value storage |
+| `Plugin/KeychainStorage.swift` | Secure storage |
+| `Plugin/SQLiteStorage.swift` | Database storage (~11KB) |
+
+## Agent Rules
+
+### Security (IRON-SOLID)
+- Sensitive data MUST use `KeychainStorage`
+- NEVER store secrets in `UserDefaultsStorage`
+
+### SQL Safety
+- ALWAYS use parameterized queries in SQLiteStorage
+- NEVER string-interpolate SQL values
+
+### Plugin Architecture
+- Methods exposed through `StrataStoragePlugin.swift`
+- Each storage backend is a separate Swift file
+- Bridges Capacitor JS calls to native Swift
+
+### Before Modifying
+- Understand Capacitor plugin protocol
+- Test on iOS simulator after changes

package/ios/CLAUDE.md

@@ -0,0 +1,49 @@
+# CLAUDE.md — ios/
+
+Last Updated: 2026-04-03
+
+## iOS Native Plugin
+
+Swift implementation of native storage backends for Capacitor.
+
+### Files
+
+| File | Purpose |
+|------|---------|
+| `Plugin/StrataStoragePlugin.swift` | Main Capacitor plugin entry point |
+| `Plugin/UserDefaultsStorage.swift` | UserDefaults-based general storage |
+| `Plugin/KeychainStorage.swift` | Keychain-based secure storage |
+| `Plugin/SQLiteStorage.swift` | SQLite database storage (~11KB) |
+
+### Configuration
+
+- Pod spec: `StrataStorage.podspec` (root)
+- Minimum iOS version: defined in podspec
+- Language: Swift
+
+## Rules
+
+### Security (IRON-SOLID)
+- Sensitive data MUST use `KeychainStorage`
+- NEVER store credentials, tokens, or secrets in `UserDefaultsStorage`
+- Keychain items should use appropriate access control flags
+
+### Plugin Architecture
+- All native methods are exposed through `StrataStoragePlugin.swift`
+- Plugin bridges Capacitor JS calls to native Swift implementations
+- Each storage backend is a separate Swift file
+
+### SQLite
+- `SQLiteStorage.swift` is the largest file (~11KB)
+- Handles table creation, migrations, and CRUD operations
+- Use parameterized queries — NEVER string-interpolate SQL
+
+### Testing
+- Native code is tested through the Capacitor bridge
+- Test via the demo app on iOS simulator
+- Verify all adapter methods work end-to-end
+
+### Before Modifying
+- Understand the Capacitor plugin protocol
+- Test on iOS simulator after changes
+- Verify podspec still resolves