local-lite 0.0.12 → 0.0.15

package/README.md

@@ -19,9 +19,11 @@ Built around the **Transactional Outbox Pattern**, `local-lite` ensures instant,
 * **[Configuration Reference](https://georgechitechi.github.io/local-lite/#/configuration)** - Options for `defineSyncConfig()`, retries, and loggers
 * **[Local SQLite Adapters](https://georgechitechi.github.io/local-lite/#/adapters-local)** - Expo SQLite, OP-SQLite, better-sqlite3, node:sqlite, and LibSQL
 * **[Remote Cloud Adapters](https://georgechitechi.github.io/local-lite/#/adapters-remote)** - Supabase, Convex, Cloud Firestore, and custom adapters
-* **[Database Backups](https://georgechitechi.github.io/local-lite/#/adapters-local?id=database-backups)** - SQLite snapshots with a Google Drive OAuth/PKCE client
-* **[React & Expo Hooks](https://georgechitechi.github.io/local-lite/#/react-hooks)** - `useLiveQuery()` and `useSyncStatus()`
-* **[Conflict Resolution](https://georgechitechi.github.io/local-lite/#/conflict-resolution)** - LWW, Client-Wins, Server-Wins, and custom resolvers
+* **[Authentication (Google, Microsoft, GitHub, Apple)](https://georgechitechi.github.io/local-lite/#/auth)** - Direct PKCE & native Apple authentication clients & hooks
+* **[Database Backups & Encryption](https://georgechitechi.github.io/local-lite/#/backups)** - Google Drive, OneDrive, and Zero-Knowledge AES-256-GCM snapshots
+* **[Conflict Resolution & Field Merge](https://georgechitechi.github.io/local-lite/#/conflict-resolution)** - 3-Way field merging, LWW, Client-Wins, and Server-Wins
+* **[Maintenance & Data Portability](https://georgechitechi.github.io/local-lite/#/maintenance-portability)** - VACUUM, WAL checkpoints, outbox pruning, and JSON/CSV export/import
+* **[React & Expo Hooks](https://georgechitechi.github.io/local-lite/#/react-hooks)** - `useLiveQuery()`, `useSyncStatus()`, and auth hooks
 
 ---
 

package/dist/access/client.d.ts

@@ -0,0 +1,9 @@
+import { AccessGuard } from './guard.js';
+/**
+ * Wraps a LocalFirstClient with an AccessGuard.
+ * Intercepts CRUD queries and mutations, asserting permissions before writes and
+ * filtering unauthorized rows or restricted fields on reads.
+ */
+export declare function withAccess<T extends {
+    [key: string]: any;
+}>(client: T, guard: AccessGuard): T;

package/dist/access/client.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAccess = withAccess;
+/**
+ * Wraps a LocalFirstClient with an AccessGuard.
+ * Intercepts CRUD queries and mutations, asserting permissions before writes and
+ * filtering unauthorized rows or restricted fields on reads.
+ */
+function withAccess(client, guard) {
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            if (prop === 'insert') {
+                return async (tableName, rowIdOrPayload, payloadOrOptions, options) => {
+                    const payload = typeof rowIdOrPayload === 'string'
+                        ? payloadOrOptions || {}
+                        : rowIdOrPayload || {};
+                    guard.assertCan('create', tableName, payload);
+                    return target.insert(tableName, rowIdOrPayload, payloadOrOptions, options);
+                };
+            }
+            if (prop === 'update') {
+                return async (tableName, rowId, payload, options) => {
+                    guard.assertCan('update', tableName, { id: rowId, ...payload });
+                    return target.update(tableName, rowId, payload, options);
+                };
+            }
+            if (prop === 'delete') {
+                return async (tableName, rowId, options) => {
+                    guard.assertCan('delete', tableName, { id: rowId });
+                    return target.delete(tableName, rowId, options);
+                };
+            }
+            if (prop === 'findById') {
+                return async (tableName, id, options) => {
+                    const record = await target.findById(tableName, id, options);
+                    if (!record)
+                        return null;
+                    if (!guard.can('read', tableName, record)) {
+                        return null;
+                    }
+                    return guard.filterAllowedFields('read', tableName, record, record);
+                };
+            }
+            if (prop === 'findMany') {
+                return async (tableName, options) => {
+                    const records = await target.findMany(tableName, options);
+                    return guard.filterRows('read', tableName, records);
+                };
+            }
+            if (prop === 'accessGuard') {
+                return guard;
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}

package/dist/access/engine.d.ts

@@ -0,0 +1,2 @@
+import { AccessPolicyDefinition, AccessEngine } from './types.js';
+export declare function defineAccessRules<TUser = any>(policy: AccessPolicyDefinition<TUser>): AccessEngine<TUser>;

package/dist/access/engine.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAccessRules = defineAccessRules;
+const guard_js_1 = require("./guard.js");
+class RuleBuilderImpl {
+    rules = [];
+    addRule(inverted, actions, subjects, arg3, arg4) {
+        const actionList = Array.isArray(actions) ? actions : [actions];
+        const subjectList = Array.isArray(subjects) ? subjects : [subjects];
+        let options;
+        let predicate;
+        if (typeof arg3 === 'function') {
+            predicate = arg3;
+        }
+        else if (arg3 && typeof arg3 === 'object') {
+            options = arg3;
+            predicate = arg4;
+        }
+        this.rules.push({
+            inverted,
+            actions: actionList,
+            subjects: subjectList,
+            predicate,
+            fields: options?.fields,
+            description: options?.description,
+        });
+        return this;
+    }
+    can(action, subject, arg3, arg4) {
+        return this.addRule(false, action, subject, arg3, arg4);
+    }
+    cannot(action, subject, arg3, arg4) {
+        return this.addRule(true, action, subject, arg3, arg4);
+    }
+}
+function defineAccessRules(policy) {
+    const createGuard = (user) => {
+        const builder = new RuleBuilderImpl();
+        policy(builder, user);
+        return new guard_js_1.AccessGuard(user, builder.rules);
+    };
+    return {
+        createGuard,
+        for: createGuard,
+    };
+}

package/dist/access/errors.d.ts

@@ -0,0 +1,14 @@
+export declare class AccessDeniedError extends Error {
+    readonly action: string;
+    readonly subject: string;
+    readonly fields?: string[];
+    readonly record?: any;
+    readonly reason?: string;
+    constructor(options: {
+        action: string;
+        subject: string;
+        fields?: string[];
+        record?: any;
+        reason?: string;
+    });
+}

package/dist/access/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessDeniedError = void 0;
+class AccessDeniedError extends Error {
+    action;
+    subject;
+    fields;
+    record;
+    reason;
+    constructor(options) {
+        const fieldsText = options.fields && options.fields.length > 0 ? ` (fields: ${options.fields.join(', ')})` : '';
+        const message = options.reason ||
+            `Access denied: cannot perform action '${options.action}' on subject '${options.subject}'${fieldsText}.`;
+        super(message);
+        this.name = 'AccessDeniedError';
+        this.action = options.action;
+        this.subject = options.subject;
+        this.fields = options.fields;
+        this.record = options.record;
+        this.reason = options.reason;
+    }
+}
+exports.AccessDeniedError = AccessDeniedError;

package/dist/access/guard.d.ts

@@ -0,0 +1,24 @@
+import { AccessAction, AccessRule, AccessSubject } from './types.js';
+export declare class AccessGuard<TUser = any> {
+    readonly user: TUser | null;
+    readonly rules: AccessRule<TUser>[];
+    constructor(user: TUser | null, rules: AccessRule<TUser>[]);
+    /**
+     * Evaluates if the current user has permission to perform an action on a subject.
+     */
+    can(action: AccessAction, subject: AccessSubject, record?: any): boolean;
+    cannot(action: AccessAction, subject: AccessSubject, record?: any): boolean;
+    assertCan(action: AccessAction, subject: AccessSubject, record?: any): void;
+    /**
+     * Check if a specific field is accessible for an action.
+     */
+    canAccessField(action: AccessAction, subject: AccessSubject, field: string, record?: any): boolean;
+    /**
+     * Strips restricted fields from an object based on rules.
+     */
+    filterAllowedFields<T extends Record<string, any>>(action: AccessAction, subject: AccessSubject, data: T, record?: any): Partial<T>;
+    /**
+     * Filters an array of rows, removing unauthorized records and stripping forbidden fields.
+     */
+    filterRows<T extends Record<string, any>>(action: AccessAction, subject: AccessSubject, rows: T[]): T[];
+}

package/dist/access/guard.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessGuard = void 0;
+const errors_js_1 = require("./errors.js");
+class AccessGuard {
+    user;
+    rules;
+    constructor(user, rules) {
+        this.user = user;
+        this.rules = rules;
+    }
+    /**
+     * Evaluates if the current user has permission to perform an action on a subject.
+     */
+    can(action, subject, record) {
+        let allowed = false;
+        for (const rule of this.rules) {
+            const actionMatches = rule.actions.includes('manage') ||
+                rule.actions.includes('all') ||
+                rule.actions.includes(action);
+            const subjectMatches = rule.subjects.includes('all') ||
+                rule.subjects.includes(subject);
+            if (!actionMatches || !subjectMatches) {
+                continue;
+            }
+            if (rule.predicate) {
+                try {
+                    if (!rule.predicate(record, this.user)) {
+                        continue;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            // If cannot rule matches (with no field filter), reject immediately
+            if (rule.inverted && (!rule.fields || rule.fields.length === 0)) {
+                return false;
+            }
+            // If can rule matches, mark allowed
+            if (!rule.inverted) {
+                allowed = true;
+            }
+        }
+        return allowed;
+    }
+    cannot(action, subject, record) {
+        return !this.can(action, subject, record);
+    }
+    assertCan(action, subject, record) {
+        if (!this.can(action, subject, record)) {
+            throw new errors_js_1.AccessDeniedError({ action, subject, record });
+        }
+    }
+    /**
+     * Check if a specific field is accessible for an action.
+     */
+    canAccessField(action, subject, field, record) {
+        if (!this.can(action, subject, record)) {
+            return false;
+        }
+        for (const rule of this.rules) {
+            if (!rule.inverted || !rule.fields || !rule.fields.includes(field)) {
+                continue;
+            }
+            const actionMatches = rule.actions.includes('manage') ||
+                rule.actions.includes('all') ||
+                rule.actions.includes(action);
+            const subjectMatches = rule.subjects.includes('all') ||
+                rule.subjects.includes(subject);
+            if (actionMatches && subjectMatches) {
+                if (!rule.predicate || rule.predicate(record, this.user)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    /**
+     * Strips restricted fields from an object based on rules.
+     */
+    filterAllowedFields(action, subject, data, record) {
+        if (!data || typeof data !== 'object')
+            return data;
+        const result = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (this.canAccessField(action, subject, key, record || data)) {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * Filters an array of rows, removing unauthorized records and stripping forbidden fields.
+     */
+    filterRows(action, subject, rows) {
+        if (!Array.isArray(rows))
+            return [];
+        return rows
+            .filter((row) => this.can(action, subject, row))
+            .map((row) => this.filterAllowedFields(action, subject, row, row));
+    }
+}
+exports.AccessGuard = AccessGuard;

package/dist/access/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './guard.js';
+export * from './engine.js';
+export * from './client.js';

package/dist/access/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./guard.js"), exports);
+__exportStar(require("./engine.js"), exports);
+__exportStar(require("./client.js"), exports);

package/dist/access/react/index.d.ts

@@ -0,0 +1,32 @@
+import React, { ReactNode } from 'react';
+import { AccessGuard } from '../guard.js';
+import { AccessAction, AccessSubject } from '../types.js';
+export interface AccessContextValue<TUser = any> {
+    guard: AccessGuard<TUser> | null;
+    user: TUser | null;
+    can: (action: AccessAction, subject: AccessSubject, record?: any) => boolean;
+    cannot: (action: AccessAction, subject: AccessSubject, record?: any) => boolean;
+    assertCan: (action: AccessAction, subject: AccessSubject, record?: any) => void;
+}
+export interface AccessProviderProps<TUser = any> {
+    guard: AccessGuard<TUser>;
+    children: ReactNode;
+}
+export declare function AccessProvider<TUser = any>({ guard, children, }: AccessProviderProps<TUser>): React.JSX.Element;
+export declare function useAccess<TUser = any>(): AccessContextValue<TUser>;
+export interface CanProps {
+    I: AccessAction;
+    a: AccessSubject;
+    this?: any;
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+export declare function Can({ I, a, this: record, fallback, children }: CanProps): React.JSX.Element;
+export interface CannotProps {
+    I: AccessAction;
+    a: AccessSubject;
+    this?: any;
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+export declare function Cannot({ I, a, this: record, fallback, children }: CannotProps): React.JSX.Element;

package/dist/access/react/index.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessProvider = AccessProvider;
+exports.useAccess = useAccess;
+exports.Can = Can;
+exports.Cannot = Cannot;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const AccessContext = (0, react_1.createContext)(null);
+function AccessProvider({ guard, children, }) {
+    const value = (0, react_1.useMemo)(() => {
+        return {
+            guard,
+            user: guard.user,
+            can: (action, subject, record) => guard.can(action, subject, record),
+            cannot: (action, subject, record) => guard.cannot(action, subject, record),
+            assertCan: (action, subject, record) => guard.assertCan(action, subject, record),
+        };
+    }, [guard]);
+    return (0, jsx_runtime_1.jsx)(AccessContext.Provider, { value: value, children: children });
+}
+function useAccess() {
+    const context = (0, react_1.useContext)(AccessContext);
+    if (!context) {
+        throw new Error('useAccess must be used within an <AccessProvider>');
+    }
+    return context;
+}
+function Can({ I, a, this: record, fallback = null, children }) {
+    const { can } = useAccess();
+    if (can(I, a, record)) {
+        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children });
+    }
+    return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: fallback });
+}
+function Cannot({ I, a, this: record, fallback = null, children }) {
+    const { cannot } = useAccess();
+    if (cannot(I, a, record)) {
+        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children });
+    }
+    return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: fallback });
+}

package/dist/access/types.d.ts

@@ -0,0 +1,26 @@
+export type AccessAction = 'create' | 'read' | 'update' | 'delete' | 'manage' | (string & {});
+export type AccessSubject = 'all' | (string & {});
+export type AccessPredicate<TRecord = any, TUser = any> = (record?: TRecord, user?: TUser | null) => boolean;
+export interface RuleOptions {
+    fields?: string[];
+    description?: string;
+}
+export interface AccessRule<TUser = any> {
+    inverted: boolean;
+    actions: string[];
+    subjects: string[];
+    predicate?: AccessPredicate<any, TUser>;
+    fields?: string[];
+    description?: string;
+}
+export interface AccessRuleBuilder<TUser = any> {
+    can(action: AccessAction | AccessAction[], subject: AccessSubject | AccessSubject[], predicate?: AccessPredicate<any, TUser>): this;
+    can(action: AccessAction | AccessAction[], subject: AccessSubject | AccessSubject[], options: RuleOptions, predicate?: AccessPredicate<any, TUser>): this;
+    cannot(action: AccessAction | AccessAction[], subject: AccessSubject | AccessSubject[], predicate?: AccessPredicate<any, TUser>): this;
+    cannot(action: AccessAction | AccessAction[], subject: AccessSubject | AccessSubject[], options: RuleOptions, predicate?: AccessPredicate<any, TUser>): this;
+}
+export type AccessPolicyDefinition<TUser = any> = (builder: AccessRuleBuilder<TUser>, user: TUser | null) => void;
+export interface AccessEngine<TUser = any> {
+    createGuard(user: TUser | null): any;
+    for(user: TUser | null): any;
+}

package/dist/access/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/apple.d.ts

@@ -0,0 +1,91 @@
+export declare const APPLE_AUTHORIZATION_ENDPOINT = "https://appleid.apple.com/auth/authorize";
+export declare const APPLE_TOKEN_ENDPOINT = "https://appleid.apple.com/auth/token";
+export declare const DEFAULT_APPLE_AUTH_SCOPES: string[];
+export interface AppleUser {
+    id: string;
+    email: string;
+    name: string;
+    givenName?: string;
+    familyName?: string;
+    identityToken?: string;
+    authorizationCode?: string;
+}
+export interface AppleAuthTokens {
+    accessToken?: string;
+    refreshToken?: string;
+    idToken: string;
+    expiresAt?: number;
+    tokenType?: string;
+}
+export interface AppleAuthTokenStore {
+    getTokens(): Promise<AppleAuthTokens | null>;
+    setTokens(tokens: AppleAuthTokens): Promise<void>;
+    removeTokens(): Promise<void>;
+    getUser(): Promise<AppleUser | null>;
+    setUser(user: AppleUser | null): Promise<void>;
+}
+export interface AppleAuthKeyValueStorage {
+    getItem(key: string): Promise<unknown>;
+    setItem(key: string, value: unknown): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export interface AppleAuthorizationRequest {
+    authorizationUrl: string;
+    redirectUri: string;
+    state: string;
+    nonce: string;
+}
+export interface AppleAuthorizationResponse {
+    code?: string;
+    id_token?: string;
+    state?: string;
+    user?: {
+        name?: {
+            firstName?: string;
+            lastName?: string;
+        };
+        email?: string;
+    };
+}
+export interface AppleNativeCredential {
+    user: string;
+    email?: string | null;
+    fullName?: {
+        givenName?: string | null;
+        familyName?: string | null;
+    } | null;
+    identityToken?: string | null;
+    authorizationCode?: string | null;
+}
+export interface AppleAuthClientOptions {
+    clientId: string;
+    redirectUri?: string;
+    scopes?: ('name' | 'email' | string)[];
+    authorize?: (request: AppleAuthorizationRequest) => Promise<AppleAuthorizationResponse | null>;
+    tokenStore?: AppleAuthTokenStore;
+    storage?: AppleAuthKeyValueStorage;
+    randomBytes?: (length: number) => Uint8Array;
+    fetch?: typeof fetch;
+}
+export declare function createInMemoryAppleTokenStore(): AppleAuthTokenStore;
+export declare function createAppleAuthTokenStore(storage: AppleAuthKeyValueStorage, prefix?: string): AppleAuthTokenStore;
+export declare class AppleAuthClient {
+    private readonly options;
+    private readonly tokenStore;
+    private readonly listeners;
+    private currentUser;
+    constructor(options: AppleAuthClientOptions);
+    onAuthStateChange(listener: (user: AppleUser | null) => void): () => void;
+    private notify;
+    /**
+     * Signs in with Apple.
+     * If a native credential object (from expo-apple-authentication or native ASAuthorizationAppleIDCredential)
+     * is passed, processes and verifies it directly.
+     * Otherwise, launches the PKCE web/browser authorization flow.
+     */
+    signIn(nativeCredential?: AppleNativeCredential): Promise<AppleUser | null>;
+    private processNativeCredential;
+    signOut(): Promise<void>;
+    isSignedIn(): Promise<boolean>;
+    getUser(): Promise<AppleUser | null>;
+}