@biglogic/rgs 3.7.3 → 3.7.6

package/COPYRIGHT.md

@@ -0,0 +1,4 @@
+# Copyright
+
+Copyright (c), Dario Passariello. All rights reserved.
+<https://dario.passariello.ca>

package/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: passariello
+patreon: passariello
+ko_fi: passariello
+liberapay: passariello
+issuehunt: passariello
+custom:
+ [
+  "https://dario.passariello.ca",
+  "https://www.indiegogo.com/individuals/28513718",
+ ]

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security
+
+Reactive Global State (RGS) implements enterprise-grade security including AES-256-GCM encryption, RBAC, and internal XSS sanitization as a secondary defense layer.
+
+## Reporting a Vulnerability
+
+Please email [@passariello](https://github.com/passariello) or see <https://dario.passariello.ca/contact/> if you have a potential security vulnerability to report.
+
+## Recent Hardening
+
+- Improved XSS sanitization patterns to block `data:`, `vbscript:`, and complex HTML tag combinations.
+- Implemented removal of HTML entity obfuscation.
+- Enhanced deep cloning to support `Map`/`Set` and circular references.

package/advanced.d.ts

@@ -0,0 +1,9 @@
+import { createStore, StorageAdapters } from "./core/store";
+import type { IStore, StoreConfig, PersistOptions, CustomStorage } from "./core/types";
+import * as Security from "./core/security";
+export declare const createStoreWithStorage: <S extends Record<string, unknown>>(storage: CustomStorage, config?: StoreConfig<S>) => IStore<S>;
+export declare const createMemoryStore: <S extends Record<string, unknown>>(config?: StoreConfig<S>) => IStore<S>;
+export declare const createSessionStore: <S extends Record<string, unknown>>(config?: StoreConfig<S>) => IStore<S> | null;
+export { createStore, StorageAdapters, Security };
+export type { IStore, StoreConfig, PersistOptions, CustomStorage };
+export type { EncryptionKey, AuditEntry, Permission, AccessRule, ConsentRecord } from "./core/security";

package/core/advanced.d.ts

@@ -0,0 +1,5 @@
+export { createAsyncStore } from "./async";
+export { StorageAdapters } from "./store";
+export { syncPlugin as SyncPlugin } from "../plugins/official/sync.plugin";
+export { analyticsPlugin as AnalyticsPlugin } from "../plugins/official/analytics.plugin";
+export type { AsyncState, Middleware, IPlugin, PluginContext } from "./types";

package/core/async.d.ts

@@ -0,0 +1,8 @@
+import type { IStore, AsyncState } from "./types";
+export declare const createAsyncStore: <T>(resolver: () => Promise<T>, options?: {
+    key?: string;
+    persist?: boolean;
+    store?: IStore<Record<string, AsyncState<T>>>;
+}) => IStore<Record<string, AsyncState<T>>> & {
+    execute: () => Promise<void>;
+};

package/core/env.d.ts

@@ -0,0 +1,4 @@
+export declare const isProduction: () => boolean;
+export declare const isDevelopment: () => boolean;
+export declare const isBrowser: () => boolean;
+export declare const isServer: () => boolean;

package/core/hooks.d.ts

@@ -0,0 +1,17 @@
+import type { IStore, StoreConfig, PersistOptions, StateUpdater } from "./types";
+import { SyncEngine, SyncConfig, SyncState } from "./sync";
+export declare const initState: <S extends Record<string, unknown>>(config?: StoreConfig<S>) => IStore<S>;
+export declare const destroyState: () => void;
+export declare const useIsStoreReady: (store?: IStore<Record<string, unknown>>) => boolean;
+export declare const getStore: () => IStore<Record<string, unknown>> | null;
+export declare function useStore<T, S extends Record<string, unknown> = Record<string, unknown>>(selector: (state: S) => T, store?: IStore<S>): T;
+export declare function useStore<T = unknown, S extends Record<string, unknown> = Record<string, unknown>>(key: string, store?: IStore<S>): readonly [T | undefined, (val: T | StateUpdater<T>, options?: PersistOptions) => boolean];
+export declare const initSync: (store: IStore<Record<string, unknown>>, config: SyncConfig) => SyncEngine<Record<string, unknown>>;
+export declare const destroySync: (namespace: string) => void;
+export declare function useSyncedState<T = unknown>(key: string, store?: IStore<Record<string, unknown>>): readonly [
+    T | undefined,
+    (val: T | StateUpdater<T>, options?: PersistOptions) => boolean,
+    SyncState
+];
+export declare const useSyncStatus: () => SyncState;
+export declare const triggerSync: (namespace?: string) => Promise<void>;

package/core/minimal.d.ts

@@ -0,0 +1,8 @@
+type Listener = () => void;
+interface Store<T extends Record<string, unknown>> {
+    get<K extends keyof T>(key: K): T[K];
+    set<K extends keyof T>(key: K, value: T[K]): void;
+    subscribe(listener: Listener): () => void;
+}
+declare const createStore: <T extends Record<string, unknown>>(initialState: T) => Store<T>;
+export { createStore, type Store };

package/core/minimal.js

@@ -0,0 +1,19 @@
+// core/minimal.ts
+var createStore = (initialState) => {
+  let state = { ...initialState };
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    get: (key) => state[key],
+    set: (key, value) => {
+      state = { ...state, [key]: value };
+      listeners.forEach((l) => l());
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+};
+export {
+  createStore
+};

package/core/persistence.d.ts

@@ -0,0 +1,23 @@
+import { StorageAdapters } from "./store";
+import * as Security from "./security";
+import type { StoreConfig, PersistOptions } from "./types";
+export interface PersistenceContext {
+    store: Map<string, unknown>;
+    versions: Map<string, number>;
+    sizes: Map<string, number>;
+    totalSize: number;
+    storage: ReturnType<typeof StorageAdapters.local>;
+    config: StoreConfig<Record<string, unknown>>;
+    diskQueue: Map<string, {
+        value: unknown;
+        options: PersistOptions;
+    }>;
+    encryptionKey: Security.EncryptionKey | null;
+    audit: (action: 'set' | 'get' | 'delete' | 'hydrate', key: string, success: boolean, error?: string) => void;
+    onError?: (error: Error, metadata?: Record<string, unknown>) => void;
+    silent: boolean;
+    debounceTime: number;
+    currentVersion: number;
+}
+export declare const flushDisk: (ctx: PersistenceContext) => Promise<void>;
+export declare const hydrateStore: (ctx: PersistenceContext, calculateSize: (val: unknown) => number, emit: () => void) => Promise<void>;

package/core/plugins.d.ts

@@ -0,0 +1,8 @@
+import { IStore, PluginHookName, PluginContext, IPlugin } from "./types";
+export interface PluginManagerContext<S extends Record<string, unknown>> {
+    plugins: Map<string, IPlugin<S>>;
+    onError?: (error: Error, metadata?: Record<string, unknown>) => void;
+    silent: boolean;
+}
+export declare const runHook: <S extends Record<string, unknown>>(ctx: PluginManagerContext<S>, name: PluginHookName, hookContext: PluginContext<S>) => void;
+export declare const installPlugin: <S extends Record<string, unknown>>(ctx: PluginManagerContext<S>, plugin: IPlugin<S>, storeInstance: IStore<S>) => void;

package/core/reactivity.d.ts

@@ -0,0 +1,19 @@
+import { ComputedSelector, WatcherCallback, StoreSubscriber } from "./types";
+export interface ReactivityContext {
+    computed: Map<string, {
+        selector: ComputedSelector<unknown>;
+        lastValue: unknown;
+        deps: Set<string>;
+    }>;
+    computedDeps: Map<string, Set<string>>;
+    watchers: Map<string, Set<WatcherCallback<unknown>>>;
+    listeners: Set<StoreSubscriber>;
+    keyListeners: Map<string, Set<StoreSubscriber>>;
+    versions: Map<string, number>;
+    storeInstance: unknown;
+    immer: boolean;
+    onError?: (error: Error, metadata?: Record<string, unknown>) => void;
+    silent: boolean;
+}
+export declare const updateComputed: (ctx: ReactivityContext, key: string, emit: (k?: string) => void) => void;
+export declare const emitChange: (ctx: ReactivityContext, changedKey?: string, isTransaction?: boolean, setPendingEmit?: (v: boolean) => void, emit?: (k?: string) => void) => void;

package/core/security.d.ts

@@ -0,0 +1,56 @@
+export declare const isCryptoAvailable: boolean;
+export declare const deriveKeyFromPassword: (password: string, salt: Uint8Array, iterations?: number) => Promise<EncryptionKey>;
+export declare const generateSalt: (length?: number) => Uint8Array;
+export interface EncryptionKey {
+    key: CryptoKey;
+    iv: Uint8Array;
+}
+export declare const generateEncryptionKey: () => Promise<EncryptionKey>;
+export declare const exportKey: (encryptionKey: EncryptionKey) => Promise<{
+    key: string;
+    iv: string;
+}>;
+export declare const importKey: (keyData: string, ivData: string) => Promise<EncryptionKey>;
+export declare const encrypt: (data: unknown, encryptionKey: EncryptionKey) => Promise<string>;
+export declare const decrypt: <T>(encryptedData: string, encryptionKey: EncryptionKey) => Promise<T>;
+export interface AuditEntry {
+    timestamp: number;
+    action: 'set' | 'get' | 'delete' | 'hydrate';
+    key: string;
+    userId?: string;
+    success: boolean;
+    error?: string;
+}
+export declare const setAuditLogger: (logger: (entry: AuditEntry) => void) => void;
+export declare const isAuditActive: () => boolean;
+export declare const logAudit: (entry: AuditEntry) => void;
+export type Permission = 'read' | 'write' | 'delete' | 'admin';
+export interface AccessRule {
+    pattern: string | ((key: string, userId?: string) => boolean);
+    permissions: Permission[];
+}
+export type AccessRulesMap = Map<string | ((key: string, userId?: string) => boolean), Permission[]>;
+export declare const addAccessRule: (rules: AccessRulesMap, pattern: string | ((key: string, userId?: string) => boolean), perms: Permission[]) => void;
+export declare const hasPermission: (rules: AccessRulesMap, key: string, action: Permission, _userId?: string) => boolean;
+export declare const sanitizeValue: (value: unknown) => unknown;
+export declare const validateKey: (key: string) => boolean;
+export interface ConsentRecord {
+    id: string;
+    purpose: string;
+    granted: boolean;
+    timestamp: number;
+}
+export type ConsentsMap = Map<string, ConsentRecord[]>;
+export declare const recordConsent: (consents: ConsentsMap, userId: string, purpose: string, granted: boolean) => ConsentRecord;
+export declare const hasConsent: (consents: ConsentsMap, userId: string, purpose: string) => boolean;
+export declare const revokeConsent: (consents: ConsentsMap, userId: string, purpose: string) => ConsentRecord | null;
+export declare const getConsents: (consents: ConsentsMap, userId: string) => ConsentRecord[];
+export declare const exportUserData: (consents: ConsentsMap, userId: string) => {
+    userId: string;
+    exportedAt: number;
+    consents: ConsentRecord[];
+};
+export declare const deleteUserData: (consents: ConsentsMap, userId: string) => {
+    success: boolean;
+    deletedConsents: number;
+};

package/core/store.d.ts

@@ -0,0 +1,7 @@
+import type { IStore, StoreConfig, CustomStorage } from './types';
+export declare const StorageAdapters: {
+    local: () => CustomStorage | null;
+    session: () => CustomStorage | null;
+    memory: () => CustomStorage;
+};
+export declare const createStore: <S extends Record<string, unknown> = Record<string, unknown>>(config?: StoreConfig<S>) => IStore<S>;

package/core/sync.d.ts

@@ -0,0 +1,76 @@
+import { IStore } from "./types";
+export type SyncStrategy = 'last-write-wins' | 'merge' | 'crdt' | 'server-wins' | 'client-wins';
+export interface SyncConfig {
+    endpoint: string;
+    authToken?: string | (() => string | null);
+    strategy?: SyncStrategy;
+    autoSyncInterval?: number;
+    syncOnReconnect?: boolean;
+    debounceTime?: number;
+    fetch?: typeof fetch;
+    onSync?: (result: SyncResult) => void;
+    onConflict?: (conflict: ConflictInfo) => ConflictResolution;
+    maxRetries?: number;
+}
+export interface SyncResult {
+    success: boolean;
+    syncedKeys: string[];
+    conflicts: ConflictInfo[];
+    errors: string[];
+    timestamp: number;
+    duration: number;
+}
+export interface ConflictInfo {
+    key: string;
+    localValue: unknown;
+    remoteValue: unknown;
+    localVersion: number;
+    remoteVersion: number;
+    timestamp: number;
+}
+export type ConflictResolution = {
+    action: 'accept-local';
+} | {
+    action: 'accept-remote';
+} | {
+    action: 'merge';
+    value: unknown;
+} | {
+    action: 'discard';
+};
+export interface SyncState {
+    isOnline: boolean;
+    isSyncing: boolean;
+    lastSyncTimestamp: number | null;
+    pendingChanges: number;
+    conflicts: number;
+}
+export declare class SyncEngine<S extends Record<string, unknown> = Record<string, unknown>> {
+    private store;
+    private config;
+    private pendingQueue;
+    private remoteVersions;
+    private syncTimer;
+    private onlineStatusListeners;
+    private syncStateListeners;
+    private _isOnline;
+    private _isSyncing;
+    constructor(store: IStore<S>, config: SyncConfig);
+    private _getAuthToken;
+    private _setupOnlineListener;
+    private _setupStoreListener;
+    private _startAutoSync;
+    private _notifyOnlineChange;
+    private _notifyStateChange;
+    queueChange(key: string, value: unknown): void;
+    sync(): Promise<SyncResult>;
+    private _fetchRemoteVersions;
+    private _pushChange;
+    private _resolveConflict;
+    getState(): SyncState;
+    onOnlineChange(callback: (online: boolean) => void): () => void;
+    onStateChange(callback: (state: SyncState) => void): () => void;
+    flush(): Promise<SyncResult>;
+    destroy(): void;
+}
+export declare const createSyncEngine: <S extends Record<string, unknown>>(store: IStore<S>, config: SyncConfig) => SyncEngine<S>;

package/core/types.d.ts

@@ -0,0 +1,164 @@
+import type { EncryptionKey, AuditEntry, Permission, AccessRule } from './security';
+import type { SyncConfig } from './sync';
+export interface PersistOptions {
+    persist?: boolean;
+    secure?: boolean;
+    encoded?: boolean;
+    encrypted?: boolean;
+    ttl?: number;
+}
+export interface StoreMetadata {
+    version: number;
+    lastUpdated: number;
+}
+export type StoreSubscriber = () => void;
+export type Middleware<T = unknown> = (key: string, value: T, meta: StoreMetadata) => void;
+export type StateUpdater<T> = (draft: T) => void | T;
+export type ComputedSelector<T> = (get: <V>(key: string) => V | null) => T;
+export type WatcherCallback<T> = (value: T | null) => void;
+export interface PluginMethod<T = unknown> {
+    (...args: unknown[]): T;
+}
+export type PluginMethods<T extends Record<string, PluginMethod>> = T;
+export type PluginHookName = 'onInit' | 'onInstall' | 'onSet' | 'onGet' | 'onRemove' | 'onDestroy' | 'onTransaction' | 'onBeforeSet' | 'onAfterSet';
+export interface PluginContext<S extends Record<string, unknown> = Record<string, unknown>> {
+    store: IStore<S>;
+    key?: string;
+    value?: unknown;
+    version?: number;
+}
+export interface IPlugin<S extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    hooks: {
+        [K in PluginHookName]?: (context: PluginContext<S>) => void | Promise<void>;
+    };
+}
+export declare const createTypedPlugin: <T extends Record<string, PluginMethod>>(name: string, methods: T) => IPlugin & {
+    methods: T;
+};
+export interface IStore<S extends Record<string, unknown> = Record<string, unknown>> {
+    set<K extends keyof S>(key: K, valOrUp: S[K] | StateUpdater<S[K]>, options?: PersistOptions): boolean;
+    get<K extends keyof S>(key: K): S[K] | null;
+    set<T = unknown>(key: string, valOrUp: T | StateUpdater<T>, options?: PersistOptions): boolean;
+    get<T = unknown>(key: string): T | null;
+    compute<T = unknown>(key: string, selector: ComputedSelector<T>): T;
+    watch<K extends keyof S>(key: K, callback: WatcherCallback<S[K]>): () => void;
+    watch<T = unknown>(key: string, callback: WatcherCallback<T>): () => void;
+    remove(key: keyof S | string): boolean;
+    delete(key: keyof S | string): boolean;
+    deleteAll(): boolean;
+    list(): Record<string, unknown>;
+    use(m: Middleware): void;
+    transaction(fn: () => void): void;
+    destroy(): void;
+    _addPlugin(plugin: IPlugin<S>): void;
+    _removePlugin(name: string): void;
+    _subscribe(cb: StoreSubscriber, key?: string): () => void;
+    _getVersion(key: string): number;
+    _setSilently(key: string, value: unknown): void;
+    _registerMethod(pluginName: string, methodName: string, fn: (...args: unknown[]) => unknown): void;
+    getSnapshot(): S;
+    addAccessRule(pattern: string | ((key: string, userId?: string) => boolean), permissions: Permission[]): void;
+    hasPermission(key: string, action: Permission, userId?: string): boolean;
+    recordConsent(userId: string, purpose: string, granted: boolean): import('./security').ConsentRecord;
+    hasConsent(userId: string, purpose: string): boolean;
+    getConsents(userId: string): import('./security').ConsentRecord[];
+    revokeConsent(userId: string, purpose: string): import('./security').ConsentRecord | null;
+    exportUserData(userId: string): {
+        userId: string;
+        exportedAt: number;
+        consents: import('./security').ConsentRecord[];
+    };
+    deleteUserData(userId: string): {
+        success: boolean;
+        deletedConsents: number;
+    };
+    readonly isReady: boolean;
+    readonly namespace: string;
+    readonly userId?: string;
+    whenReady(): Promise<void>;
+    readonly plugins: GStatePlugins;
+}
+export interface GStatePlugins {
+    security: {
+        addAccessRule: (pattern: string | ((key: string, userId?: string) => boolean), permissions: Permission[]) => void;
+        recordConsent: (userId: string, purpose: string, granted: boolean) => import('./security').ConsentRecord;
+        hasConsent: (userId: string, purpose: string) => boolean;
+        getConsents: (userId: string) => import('./security').ConsentRecord[];
+        revokeConsent: (userId: string, purpose: string) => import('./security').ConsentRecord | null;
+        exportUserData: (userId: string) => {
+            userId: string;
+            exportedAt: number;
+            consents: import('./security').ConsentRecord[];
+        };
+        deleteUserData: (userId: string) => {
+            success: boolean;
+            deletedConsents: number;
+        };
+    };
+    undoRedo: {
+        undo: () => boolean;
+        redo: () => boolean;
+        canUndo: () => boolean;
+        canRedo: () => boolean;
+    };
+    immer: {
+        setWithProduce: <T>(key: string, updater: (draft: T) => void) => boolean;
+    };
+    cloudSync: {
+        sync: () => Promise<{
+            status: string;
+            stats: import('../plugins/official/cloud-sync.plugin').SyncStats;
+        }>;
+        getStats: () => import('../plugins/official/cloud-sync.plugin').SyncStats;
+    };
+    sync: {
+        flush: () => Promise<import('../core/sync').SyncResult>;
+        getState: () => import('../core/sync').SyncState;
+        onStateChange: (callback: (state: import('../core/sync').SyncState) => void) => () => void;
+    };
+    logger: Record<string, never>;
+    [key: string]: unknown;
+}
+export interface StoreConfig<S extends Record<string, unknown> = Record<string, unknown>> {
+    namespace?: string;
+    version?: number;
+    silent?: boolean;
+    debounceTime?: number;
+    storage?: CustomStorage | Storage;
+    migrate?: (oldState: Record<string, unknown>, oldVersion: number) => S;
+    persistByDefault?: boolean;
+    persistence?: boolean;
+    persist?: boolean;
+    onError?: (error: Error, context: {
+        operation: string;
+        key?: string;
+    }) => void;
+    maxObjectSize?: number;
+    maxTotalSize?: number;
+    encryptionKey?: EncryptionKey;
+    auditEnabled?: boolean;
+    userId?: string;
+    validateInput?: boolean;
+    encoded?: boolean;
+    accessRules?: Array<{
+        pattern: string | ((key: string, userId?: string) => boolean);
+        permissions: Permission[];
+    }>;
+    immer?: boolean;
+    sync?: SyncConfig;
+}
+export interface CustomStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    key(index: number): string | null;
+    length: number;
+}
+export interface AsyncState<T> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    updatedAt: number | null;
+}
+export type { EncryptionKey, AuditEntry, Permission, AccessRule };

package/core/utils.d.ts

@@ -0,0 +1,2 @@
+export declare const deepClone: <T>(obj: T) => T;
+export declare const isEqual: (a: unknown, b: unknown) => boolean;