@rajeev02/vault 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,142 @@
+# @rajeev02/vault
+
+[![npm version](https://img.shields.io/npm/v/@rajeev02/vault.svg)](https://www.npmjs.com/package/@rajeev02/vault)
+[![license](https://img.shields.io/npm/l/@rajeev02/vault.svg)](https://github.com/Rajeev02/rajeev-sdk/blob/main/LICENSE)
+
+**AES-256-GCM encrypted key-value storage** with namespaces, expiry, hashing, and biometric gating — powered by Rust for maximum performance and security.
+
+Part of [Rajeev SDK](https://github.com/Rajeev02/rajeev-sdk) — cross-platform infrastructure libraries for building apps that work everywhere.
+
+## Why use this?
+
+- **Bank-grade encryption** — AES-256-GCM (the same standard used by banks and governments)
+- **Rust-powered** — Crypto logic runs in native Rust, not JavaScript. No key exposure in JS memory.
+- **Offline-first** — SQLite-backed storage works without network. Data persists across app restarts.
+- **Biometric gating** — Optionally require Face ID / Touch ID / fingerprint before reading sensitive keys
+- **Namespaces + expiry** — Organize keys by context, auto-expire tokens after TTL
+- **Truly cross-platform** — Same API on iOS, Android, Web (WASM), watchOS, and Wear OS
+
+## Platform Support
+
+| Platform     | Engine            | Status |
+| ------------ | ----------------- | ------ |
+| iOS 16+      | Rust → UniFFI     | ✅     |
+| Android 7+   | Rust → UniFFI JNI | ✅     |
+| Web          | Rust → WASM       | ✅     |
+| watchOS 9+   | Rust → UniFFI     | ✅     |
+| Wear OS      | Rust → UniFFI     | ✅     |
+| Android Auto | Rust → UniFFI     | ✅     |
+
+## Installation
+
+```bash
+npm install @rajeev02/vault
+
+# iOS (after install)
+cd ios && pod install
+```
+
+### Peer Dependencies
+
+- `react` >= 18.3.0
+- `react-native` >= 0.84.0
+- `expo` >= 54.0.0 _(optional)_
+
+## Quick Start
+
+```typescript
+import { Vault } from "@rajeev02/vault";
+
+// Create an encrypted vault
+const vault = await Vault.create({
+  appId: "my-app",
+  encryption: "AES-256-GCM",
+});
+
+// Store and retrieve secrets
+await vault.set("auth_token", "eyJhbGciOi…");
+const token = await vault.get("auth_token"); // → 'eyJhbGciOi…'
+
+// JSON convenience
+await vault.setJSON("profile", { name: "Rajeev", lang: "hi" });
+const profile = await vault.getJSON<{ name: string }>("profile");
+
+// Namespaces — isolate data by context
+const userVault = vault.namespace("user-123");
+await userVault.set("preferences", "dark-mode");
+
+// Expiry — auto-delete after TTL
+await vault.set("otp", "483921", { expiry: "5m" });
+
+// Biometric gating (iOS Face ID / Android fingerprint)
+await vault.set("bank_pin", "8491", { biometricRequired: true });
+const pin = await vault.get("bank_pin"); // triggers biometric prompt
+
+// Hashing — one-way hash for password verification
+const hash = await vault.hash("my-password");
+const matches = await vault.verifyHash("my-password", hash); // → true
+
+// Bulk operations
+await vault.setMany([
+  { key: "a", value: "1" },
+  { key: "b", value: "2" },
+]);
+const all = await vault.getAll(); // → Map of all key-value pairs
+
+// Cleanup
+await vault.delete("auth_token");
+await vault.clear(); // Remove all keys
+```
+
+## React Hooks
+
+```typescript
+import { useVault, useVaultValue } from "@rajeev02/vault";
+
+function SecureComponent() {
+  const vault = useVault({ appId: "my-app" });
+  const [token, setToken] = useVaultValue(vault, "auth_token");
+
+  return <Text>{token ?? "No token"}</Text>;
+}
+```
+
+## API Reference
+
+| Method                           | Returns                   | Description                     |
+| -------------------------------- | ------------------------- | ------------------------------- |
+| `Vault.create(config)`           | `Promise<Vault>`          | Create encrypted vault instance |
+| `vault.set(key, value, opts?)`   | `Promise<void>`           | Store encrypted value           |
+| `vault.get(key)`                 | `Promise<string \| null>` | Retrieve decrypted value        |
+| `vault.setJSON(key, obj, opts?)` | `Promise<void>`           | Store JSON object               |
+| `vault.getJSON<T>(key)`          | `Promise<T \| null>`      | Retrieve parsed JSON            |
+| `vault.delete(key)`              | `Promise<void>`           | Delete a key                    |
+| `vault.clear()`                  | `Promise<void>`           | Delete all keys                 |
+| `vault.has(key)`                 | `Promise<boolean>`        | Check if key exists             |
+| `vault.keys()`                   | `Promise<string[]>`       | List all keys                   |
+| `vault.getAll()`                 | `Promise<Map>`            | Get all key-value pairs         |
+| `vault.namespace(ns)`            | `Vault`                   | Create namespaced sub-vault     |
+| `vault.hash(input)`              | `Promise<string>`         | One-way hash                    |
+| `vault.verifyHash(input, hash)`  | `Promise<boolean>`        | Verify hash match               |
+
+## Architecture
+
+```
+TypeScript API (this package)
+    ↓
+Native Bridge (auto-generated by UniFFI)
+    ↓
+Rust Core (rajeev-vault-core)
+  ├── AES-256-GCM encryption (aes-gcm 0.10)
+  ├── SQLite storage (rusqlite 0.38)
+  ├── Key derivation (PBKDF2 / Argon2)
+  └── Secure random (rand 0.9)
+```
+
+## Full Documentation
+
+📖 [Complete API docs with platform-specific examples](https://github.com/Rajeev02/rajeev-sdk/blob/main/docs/usage/VAULT.md)
+
+## License
+
+MIT © 2026 [Rajeev Kumar Joshi](https://rajeev02.github.io)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rajeev02/vault",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Universal secure storage for React Native — AES-256-GCM encrypted, cross-platform",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -8,7 +8,7 @@
     "build": "tsc",
     "clean": "rm -rf lib",
     "test": "jest",
-    "prepublishOnly": "yarn build"
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "react-native",
@@ -24,7 +24,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/Rajeev02/rajeev-sdk",
-    "directory": "packages/vault"
+    "directory": "packages/vault/ts-wrapper"
   },
   "peerDependencies": {
     "react": ">=18.3.0",
@@ -44,10 +44,7 @@
   },
   "files": [
     "lib/",
-    "android/",
-    "ios/",
-    "rust-core/",
-    "rajeev-vault.podspec",
+    "src/",
     "README.md"
   ],
   "publishConfig": {

package/src/hooks.ts

@@ -0,0 +1,169 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Vault } from './vault';
+import type { VaultConfig, StoreOptions, VaultStats } from './types';
+
+/**
+ * React hook to create and manage a Vault instance.
+ *
+ * @param config - Vault configuration
+ * @returns Vault instance and loading state
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { vault, isReady, error } = useVault({ appId: 'com.myapp' });
+ *
+ *   if (!isReady) return <LoadingScreen />;
+ *   if (error) return <ErrorScreen error={error} />;
+ *
+ *   return <MainApp vault={vault!} />;
+ * }
+ * ```
+ */
+export function useVault(config: VaultConfig) {
+  const [vault, setVault] = useState<Vault | null>(null);
+  const [isReady, setIsReady] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const initRef = useRef(false);
+
+  useEffect(() => {
+    if (initRef.current) return;
+    initRef.current = true;
+
+    Vault.create(config)
+      .then((v) => {
+        setVault(v);
+        setIsReady(true);
+      })
+      .catch((e) => {
+        setError(e);
+        setIsReady(true);
+      });
+  }, [config.appId]);
+
+  return { vault, isReady, error };
+}
+
+/**
+ * React hook to read a value from the vault reactively.
+ * Re-reads when the key or namespace changes.
+ *
+ * @param vault - Vault instance
+ * @param key - Key to read
+ * @param namespace - Optional namespace
+ * @returns Value, loading state, and refresh function
+ *
+ * @example
+ * ```tsx
+ * function TokenDisplay({ vault }: { vault: Vault }) {
+ *   const { value, isLoading, refresh } = useVaultValue(vault, 'auth_token');
+ *
+ *   if (isLoading) return <Text>Loading...</Text>;
+ *
+ *   return (
+ *     <View>
+ *       <Text>Token: {value ?? 'Not set'}</Text>
+ *       <Button title="Refresh" onPress={refresh} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useVaultValue(
+  vault: Vault | null,
+  key: string,
+  namespace?: string,
+) {
+  const [value, setValue] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const refresh = useCallback(async () => {
+    if (!vault) return;
+    setIsLoading(true);
+    try {
+      const result = await vault.get(key, namespace);
+      setValue(result);
+      setError(null);
+    } catch (e) {
+      setError(e as Error);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [vault, key, namespace]);
+
+  useEffect(() => {
+    refresh();
+  }, [refresh]);
+
+  return { value, isLoading, error, refresh };
+}
+
+/**
+ * React hook to read a JSON value from the vault.
+ *
+ * @example
+ * ```tsx
+ * interface UserProfile {
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * function Profile({ vault }: { vault: Vault }) {
+ *   const { data, isLoading } = useVaultJSON<UserProfile>(vault, 'profile');
+ *
+ *   if (isLoading) return <Text>Loading...</Text>;
+ *   return <Text>Hello, {data?.name ?? 'Guest'}</Text>;
+ * }
+ * ```
+ */
+export function useVaultJSON<T = unknown>(
+  vault: Vault | null,
+  key: string,
+  namespace?: string,
+) {
+  const { value, isLoading, error, refresh } = useVaultValue(vault, key, namespace);
+
+  const data = value ? (JSON.parse(value) as T) : null;
+
+  return { data, isLoading, error, refresh };
+}
+
+/**
+ * React hook to get vault statistics.
+ *
+ * @example
+ * ```tsx
+ * function VaultInfo({ vault }: { vault: Vault }) {
+ *   const { stats, isLoading } = useVaultStats(vault);
+ *
+ *   return (
+ *     <Text>
+ *       Entries: {stats?.totalEntries ?? 0}
+ *       Size: {stats?.storageBytes ?? 0} bytes
+ *     </Text>
+ *   );
+ * }
+ * ```
+ */
+export function useVaultStats(vault: Vault | null) {
+  const [stats, setStats] = useState<VaultStats | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  const refresh = useCallback(async () => {
+    if (!vault) return;
+    setIsLoading(true);
+    try {
+      const s = await vault.stats();
+      setStats(s);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [vault]);
+
+  useEffect(() => {
+    refresh();
+  }, [refresh]);
+
+  return { stats, isLoading, refresh };
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * @rajeev02/vault
+ *
+ * Universal Secure Storage for React Native
+ * AES-256-GCM encrypted, cross-platform (Android, iOS, Web, Watch, Auto, IoT)
+ *
+ * Built with Rust core for maximum security and performance.
+ *
+ * @author Rajeev Kumar Joshi (https://github.com/Rajeev02)
+ * @license MIT
+ *
+ * @example
+ * ```typescript
+ * import { Vault } from '@rajeev02/vault';
+ *
+ * const vault = await Vault.create({ appId: 'com.myapp' });
+ *
+ * // Store
+ * await vault.set('token', 'my-secret', { expiry: '24h' });
+ *
+ * // Retrieve
+ * const token = await vault.get('token');
+ *
+ * // Namespaces
+ * const payments = vault.namespace('payments');
+ * await payments.set('upi_pin', '1234', { biometricRequired: true });
+ *
+ * // JSON helpers
+ * await vault.setJSON('user', { name: 'Rajeev', role: 'admin' });
+ * const user = await vault.getJSON<User>('user');
+ * ```
+ */
+
+// Core
+export { Vault } from './vault';
+
+// Types
+export {
+  VaultConfig,
+  StoreOptions,
+  VaultStats,
+  VaultError,
+  VaultErrorCode,
+} from './types';
+
+// React Hooks
+export {
+  useVault,
+  useVaultValue,
+  useVaultJSON,
+  useVaultStats,
+} from './hooks';

package/src/native-bridge.ts

@@ -0,0 +1,33 @@
+import { NativeModules, Platform } from 'react-native';
+import type { NativeVaultModule } from './types';
+
+/**
+ * Get the native vault module for the current platform.
+ *
+ * Android: Uses JNI → Rust .so library
+ * iOS: Uses C FFI → Rust .a static library
+ * Web: Uses WASM → Rust compiled to WebAssembly
+ */
+function getNativeModule(): NativeVaultModule {
+  const { RajeevVault } = NativeModules;
+
+  if (!RajeevVault) {
+    throw new Error(
+      `@rajeev02/vault: Native module not found. ` +
+        `Make sure you have run 'pod install' (iOS) or rebuilt the app (Android).\n\n` +
+        `Platform: ${Platform.OS}\n` +
+        `If you're on web, import from '@rajeev02/vault/web' instead.`,
+    );
+  }
+
+  return RajeevVault as NativeVaultModule;
+}
+
+export const NativeBridge = {
+  /**
+   * Get the native module, lazy-loaded and cached
+   */
+  get module(): NativeVaultModule {
+    return getNativeModule();
+  },
+};

package/src/types.ts

@@ -0,0 +1,131 @@
+/**
+ * @rajeev02/vault - Type Definitions
+ *
+ * Universal secure storage for React Native, Web, Watch, Auto, IoT
+ * Built by Rajeev Kumar Joshi (https://github.com/Rajeev02)
+ */
+
+/** Configuration for creating a vault instance */
+export interface VaultConfig {
+  /** Unique app identifier (e.g., 'com.myapp') */
+  appId: string;
+
+  /** Custom database path. Defaults to app-specific location */
+  dbPath?: string;
+
+  /** Encryption algorithm. Default: 'AES-256-GCM' */
+  encryption?: 'AES-256-GCM';
+
+  /** Whether biometric auth is available on this device */
+  biometricAvailable?: boolean;
+}
+
+/** Options when storing a value */
+export interface StoreOptions {
+  /**
+   * When the value should expire and auto-delete.
+   * Format: "30m" (minutes), "24h" (hours), "7d" (days), "4w" (weeks)
+   * Default: null (never expires)
+   */
+  expiry?: string | null;
+
+  /**
+   * Whether biometric authentication is required to read this value.
+   * Default: false
+   */
+  biometricRequired?: boolean;
+
+  /**
+   * Whether this entry can be exported/backed up.
+   * Set to false for highly sensitive data like PINs.
+   * Default: true
+   */
+  exportable?: boolean;
+
+  /**
+   * Namespace to group related entries.
+   * e.g., 'auth', 'payments', 'health'
+   * Default: 'default'
+   */
+  namespace?: string;
+}
+
+/** Statistics about the vault */
+export interface VaultStats {
+  /** Total number of stored entries */
+  totalEntries: number;
+
+  /** Number of distinct namespaces */
+  totalNamespaces: number;
+
+  /** Number of expired entries pending cleanup */
+  expiredEntries: number;
+
+  /** Approximate storage used in bytes */
+  storageBytes: number;
+}
+
+/** Error codes returned by the vault */
+export enum VaultErrorCode {
+  ENCRYPTION_FAILED = 'ENCRYPTION_FAILED',
+  DECRYPTION_FAILED = 'DECRYPTION_FAILED',
+  KEY_NOT_FOUND = 'KEY_NOT_FOUND',
+  KEY_EXPIRED = 'KEY_EXPIRED',
+  STORAGE_ERROR = 'STORAGE_ERROR',
+  INVALID_CONFIG = 'INVALID_CONFIG',
+  BIOMETRIC_REQUIRED = 'BIOMETRIC_REQUIRED',
+  BIOMETRIC_FAILED = 'BIOMETRIC_FAILED',
+  NOT_INITIALIZED = 'NOT_INITIALIZED',
+}
+
+/** Custom error class for vault operations */
+export class VaultError extends Error {
+  public readonly code: VaultErrorCode;
+
+  constructor(code: VaultErrorCode, message?: string) {
+    super(message || code);
+    this.name = 'VaultError';
+    this.code = code;
+  }
+}
+
+/** Internal native module interface (platform-specific) */
+export interface NativeVaultModule {
+  create(config: {
+    appId: string;
+    dbPath?: string;
+    encryptionAlgo: string;
+    biometricAvailable: boolean;
+  }): Promise<void>;
+
+  store(
+    key: string,
+    value: string,
+    expiry: string | null,
+    biometricRequired: boolean,
+    exportable: boolean,
+    namespace: string | null,
+  ): Promise<void>;
+
+  retrieve(key: string, namespace: string | null): Promise<string | null>;
+  delete(key: string, namespace: string | null): Promise<boolean>;
+  exists(key: string, namespace: string | null): Promise<boolean>;
+  listKeys(namespace: string | null): Promise<string[]>;
+  listNamespaces(): Promise<string[]>;
+  wipeNamespace(namespace: string): Promise<void>;
+  wipeAll(): Promise<void>;
+  getStats(): Promise<VaultStats>;
+  cleanupExpired(): Promise<void>;
+  exportEntry(key: string, namespace: string | null): Promise<string | null>;
+  importEntry(
+    key: string,
+    encryptedData: string,
+    expiry: string | null,
+    biometricRequired: boolean,
+    exportable: boolean,
+    namespace: string | null,
+  ): Promise<void>;
+  generateKey(): Promise<string>;
+  hash(input: string): Promise<string>;
+  verifyHash(input: string, hash: string): Promise<boolean>;
+}

package/src/vault.ts

@@ -0,0 +1,396 @@
+import { NativeBridge } from './native-bridge';
+import {
+  VaultConfig,
+  StoreOptions,
+  VaultStats,
+  VaultError,
+  VaultErrorCode,
+} from './types';
+
+/**
+ * 🔐 Rajeev Vault — Universal Secure Storage
+ *
+ * AES-256-GCM encrypted storage that works across all platforms.
+ * Built with Rust core for maximum security and performance.
+ *
+ * @example
+ * ```typescript
+ * import { Vault } from '@rajeev02/vault';
+ *
+ * // Create vault
+ * const vault = await Vault.create({ appId: 'com.myapp' });
+ *
+ * // Store securely
+ * await vault.set('token', 'my-secret-value', { expiry: '24h' });
+ *
+ * // Retrieve
+ * const token = await vault.get('token');
+ *
+ * // Use namespaces
+ * await vault.namespace('payments').set('upi_pin', '1234', {
+ *   biometricRequired: true,
+ *   exportable: false,
+ * });
+ * ```
+ *
+ * @author Rajeev Kumar Joshi (https://github.com/Rajeev02)
+ */
+export class Vault {
+  private initialized = false;
+  private config: VaultConfig;
+  private currentNamespace: string | null = null;
+
+  private constructor(config: VaultConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Create a new Vault instance.
+   * This is the main entry point — use this instead of `new Vault()`.
+   *
+   * @param config - Vault configuration
+   * @returns Initialized Vault instance
+   *
+   * @example
+   * ```typescript
+   * const vault = await Vault.create({
+   *   appId: 'com.myapp',
+   *   biometricAvailable: true,
+   * });
+   * ```
+   */
+  static async create(config: VaultConfig): Promise<Vault> {
+    const vault = new Vault(config);
+
+    try {
+      await NativeBridge.module.create({
+        appId: config.appId,
+        dbPath: config.dbPath,
+        encryptionAlgo: config.encryption || 'AES-256-GCM',
+        biometricAvailable: config.biometricAvailable ?? false,
+      });
+      vault.initialized = true;
+    } catch (error) {
+      throw new VaultError(
+        VaultErrorCode.INVALID_CONFIG,
+        `Failed to initialize vault: ${error}`,
+      );
+    }
+
+    return vault;
+  }
+
+  /**
+   * Ensure the vault is initialized before any operation
+   */
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new VaultError(
+        VaultErrorCode.NOT_INITIALIZED,
+        'Vault not initialized. Call Vault.create() first.',
+      );
+    }
+  }
+
+  // ─── Core Operations ─────────────────────────────────────────────
+
+  /**
+   * Store a value securely.
+   *
+   * @param key - Unique key for the value
+   * @param value - String value to encrypt and store
+   * @param options - Storage options (expiry, biometric, namespace)
+   *
+   * @example
+   * ```typescript
+   * // Simple store
+   * await vault.set('token', 'eyJhbG...');
+   *
+   * // With expiry
+   * await vault.set('otp', '4829', { expiry: '5m' });
+   *
+   * // With biometric protection
+   * await vault.set('pin', '1234', {
+   *   biometricRequired: true,
+   *   exportable: false,
+   * });
+   *
+   * // Store JSON
+   * await vault.set('user', JSON.stringify({ name: 'Rajeev', role: 'admin' }));
+   * ```
+   */
+  async set(key: string, value: string, options?: StoreOptions): Promise<void> {
+    this.ensureInitialized();
+
+    const ns = options?.namespace ?? this.currentNamespace;
+
+    await NativeBridge.module.store(
+      key,
+      value,
+      options?.expiry ?? null,
+      options?.biometricRequired ?? false,
+      options?.exportable ?? true,
+      ns,
+    );
+  }
+
+  /**
+   * Retrieve a decrypted value.
+   * Returns null if the key doesn't exist or has expired.
+   *
+   * @param key - Key to retrieve
+   * @param namespace - Optional namespace override
+   * @returns Decrypted value or null
+   *
+   * @example
+   * ```typescript
+   * const token = await vault.get('token');
+   * if (token) {
+   *   console.log('Got token:', token);
+   * } else {
+   *   console.log('Token not found or expired');
+   * }
+   *
+   * // Get JSON
+   * const userJson = await vault.get('user');
+   * const user = userJson ? JSON.parse(userJson) : null;
+   * ```
+   */
+  async get(key: string, namespace?: string): Promise<string | null> {
+    this.ensureInitialized();
+    const ns = namespace ?? this.currentNamespace;
+    return NativeBridge.module.retrieve(key, ns);
+  }
+
+  /**
+   * Get a value, parsed as JSON.
+   * Convenience method that combines get() + JSON.parse().
+   *
+   * @param key - Key to retrieve
+   * @param namespace - Optional namespace override
+   * @returns Parsed object or null
+   */
+  async getJSON<T = unknown>(key: string, namespace?: string): Promise<T | null> {
+    const raw = await this.get(key, namespace);
+    if (raw === null) return null;
+
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Store a value as JSON.
+   * Convenience method that combines JSON.stringify() + set().
+   */
+  async setJSON<T>(key: string, value: T, options?: StoreOptions): Promise<void> {
+    const serialized = JSON.stringify(value);
+    await this.set(key, serialized, options);
+  }
+
+  /**
+   * Delete a key from the vault.
+   *
+   * @param key - Key to delete
+   * @param namespace - Optional namespace override
+   * @returns true if the key was deleted, false if not found
+   */
+  async delete(key: string, namespace?: string): Promise<boolean> {
+    this.ensureInitialized();
+    const ns = namespace ?? this.currentNamespace;
+    return NativeBridge.module.delete(key, ns);
+  }
+
+  /**
+   * Check if a key exists (and is not expired).
+   *
+   * @param key - Key to check
+   * @param namespace - Optional namespace override
+   * @returns true if key exists and is valid
+   */
+  async has(key: string, namespace?: string): Promise<boolean> {
+    this.ensureInitialized();
+    const ns = namespace ?? this.currentNamespace;
+    return NativeBridge.module.exists(key, ns);
+  }
+
+  // ─── Namespace Operations ─────────────────────────────────────────
+
+  /**
+   * Create a namespace-scoped vault view.
+   * All operations on the returned object are scoped to this namespace.
+   *
+   * @param name - Namespace name
+   * @returns Namespace-scoped vault
+   *
+   * @example
+   * ```typescript
+   * const payments = vault.namespace('payments');
+   * await payments.set('upi_pin', '1234');
+   * await payments.set('card_last4', '4242');
+   *
+   * const health = vault.namespace('health');
+   * await health.set('blood_group', 'O+');
+   *
+   * // Keys don't collide across namespaces
+   * await vault.namespace('a').set('key', 'value-a');
+   * await vault.namespace('b').set('key', 'value-b');
+   * ```
+   */
+  namespace(name: string): NamespacedVault {
+    this.ensureInitialized();
+    return new NamespacedVault(this, name);
+  }
+
+  /**
+   * List all keys in a namespace.
+   *
+   * @param namespace - Namespace to list (default namespace if not specified)
+   * @returns Array of key names
+   */
+  async keys(namespace?: string): Promise<string[]> {
+    this.ensureInitialized();
+    const ns = namespace ?? this.currentNamespace;
+    return NativeBridge.module.listKeys(ns);
+  }
+
+  /**
+   * List all namespaces in the vault.
+   *
+   * @returns Array of namespace names
+   */
+  async namespaces(): Promise<string[]> {
+    this.ensureInitialized();
+    return NativeBridge.module.listNamespaces();
+  }
+
+  // ─── Destructive Operations ───────────────────────────────────────
+
+  /**
+   * Delete all entries in a namespace.
+   *
+   * @param namespace - Namespace to wipe
+   */
+  async wipeNamespace(namespace: string): Promise<void> {
+    this.ensureInitialized();
+    await NativeBridge.module.wipeNamespace(namespace);
+  }
+
+  /**
+   * ⚠️ Delete EVERYTHING in the vault. Cannot be undone.
+   * Typically used during logout.
+   *
+   * @example
+   * ```typescript
+   * async function logout() {
+   *   await vault.wipeAll();
+   *   navigation.reset('LoginScreen');
+   * }
+   * ```
+   */
+  async wipeAll(): Promise<void> {
+    this.ensureInitialized();
+    await NativeBridge.module.wipeAll();
+  }
+
+  // ─── Utility Operations ───────────────────────────────────────────
+
+  /**
+   * Get storage statistics.
+   *
+   * @returns Stats including entry count, namespaces, storage size
+   */
+  async stats(): Promise<VaultStats> {
+    this.ensureInitialized();
+    return NativeBridge.module.getStats();
+  }
+
+  /**
+   * Clean up expired entries. Call periodically to reclaim space.
+   */
+  async cleanup(): Promise<void> {
+    this.ensureInitialized();
+    await NativeBridge.module.cleanupExpired();
+  }
+
+  // ─── Static Utilities ─────────────────────────────────────────────
+
+  /**
+   * Generate a cryptographically secure random key.
+   * Useful for creating encryption keys, API tokens, etc.
+   *
+   * @returns Base64-encoded random key
+   */
+  static async generateKey(): Promise<string> {
+    return NativeBridge.module.generateKey();
+  }
+
+  /**
+   * Hash a value (one-way). Useful for storing passwords.
+   *
+   * @param input - Value to hash
+   * @returns Salted hash string
+   */
+  static async hash(input: string): Promise<string> {
+    return NativeBridge.module.hash(input);
+  }
+
+  /**
+   * Verify a value against a hash.
+   *
+   * @param input - Value to verify
+   * @param hash - Hash to verify against
+   * @returns true if the value matches the hash
+   */
+  static async verifyHash(input: string, hash: string): Promise<boolean> {
+    return NativeBridge.module.verifyHash(input, hash);
+  }
+}
+
+/**
+ * A namespace-scoped view of the vault.
+ * All operations are automatically scoped to the namespace.
+ */
+class NamespacedVault {
+  private vault: Vault;
+  private name: string;
+
+  constructor(vault: Vault, name: string) {
+    this.vault = vault;
+    this.name = name;
+  }
+
+  async set(key: string, value: string, options?: Omit<StoreOptions, 'namespace'>): Promise<void> {
+    return this.vault.set(key, value, { ...options, namespace: this.name });
+  }
+
+  async get(key: string): Promise<string | null> {
+    return this.vault.get(key, this.name);
+  }
+
+  async getJSON<T = unknown>(key: string): Promise<T | null> {
+    return this.vault.getJSON<T>(key, this.name);
+  }
+
+  async setJSON<T>(key: string, value: T, options?: Omit<StoreOptions, 'namespace'>): Promise<void> {
+    return this.vault.setJSON(key, value, { ...options, namespace: this.name });
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.vault.delete(key, this.name);
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.vault.has(key, this.name);
+  }
+
+  async keys(): Promise<string[]> {
+    return this.vault.keys(this.name);
+  }
+
+  async wipe(): Promise<void> {
+    return this.vault.wipeNamespace(this.name);
+  }
+}