@me2em/react 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -1,10 +1,8 @@
-# @me2em/react
+[![npm version](https://img.shields.io/npm/v/@me2em/react.svg)](https://www.npmjs.com/package/@me2em/react)
+[![License](https://img.shields.io/npm/l/@me2em/react.svg)](./LICENSE)
+[![Docs](https://img.shields.io/badge/docs-react.me2em.com-blue)](https://react.me2em.com)
 
-**Me2em never persists your seed.** The seed phrase exists in two
-places only: your paper and transient memory during login. This
-package stores only *derived, encrypted context caches* — losing your
-browser data never loses your identity, because your identity lives
-in your head.
+## 📦 @me2em/react — React bindings
 
 React bindings for the Me2em protocol: identity lifecycle, seed phrase UX, and hierarchical handle derivation.
 
@@ -16,6 +14,13 @@ pnpm add @me2em/react react
 
 Requires React >= 18.0.0 as a peer dependency.
 
+> 💡 This package requires [`@me2em/core`](../core/README.md) (peer
+>  dependency via workspace) and React ≥ 18. It is self-contained —
+>  for E2EE channels, X3DH, and Argon2id see
+>  [`@me2em/crypto`](../crypto/README.md). All three packages are
+>  designed to work together — see the root
+>  [README](../../README.md) for the full package map.
+
 ## Quick Start
 
 ```tsx
@@ -69,6 +74,30 @@ const state = headless.identityFlowReducer(headless.initialIdentityFlowState, {
 });
 ```
 
+---
+
+## 📖 Terminology (selected)
+
+Protocol terms are **domain-neutral**. The terms most relevant to
+this package:
+
+| Term | Definition |
+|------|------------|
+| **Identity** | Root cryptographic identity derived from a seed phrase. Constant forever. |
+| **Handle** | A derived, attested, named key representing a distinct identity context. |
+| **Session** | A stateless signed authorization token. |
+| **Transient material** | Key bytes existing only in RAM at the moment of use. |
+| **Context cache** | Per-identity encrypted storage of derived Handle context. |
+
+Full glossary (including Attestation, SubHandle, Ephemeral material):
+see the [root README](../../README.md).
+
+**This package never persists your seed.** The seed phrase exists in
+two places only — your paper and transient memory during login. What
+this package stores is derived, encrypted context caches. Losing your
+browser data never loses your identity, because your identity lives
+in your head.
+
 ## Components
 
 ### SeedPhraseDisplay

package/dist/index.d.ts

@@ -364,4 +364,4 @@ declare namespace index {
   export { type index_ContextEnvelope as ContextEnvelope, type index_DisplayEvent as DisplayEvent, type index_DisplayState as DisplayState, type index_DisplayStatus as DisplayStatus, type index_IdentityContextData as IdentityContextData, index_IdentityContextIDBStorage as IdentityContextIDBStorage, type index_IdentityContextStorage as IdentityContextStorage, type index_IdentityFlowEvent as IdentityFlowEvent, type index_IdentityFlowState as IdentityFlowState, type index_IdentityFlowStatus as IdentityFlowStatus, type index_ImportEvent as ImportEvent, type index_ImportState as ImportState, type index_ImportStatus as ImportStatus, type index_VerifyEvent as VerifyEvent, type index_VerifyState as VerifyState, type index_VerifyStatus as VerifyStatus, index_buildVerificationGrid as buildVerificationGrid, index_decryptContext as decryptContext, index_deriveCacheKey as deriveCacheKey, index_displayFlowReducer as displayFlowReducer, index_encryptContext as encryptContext, index_identityFlowReducer as identityFlowReducer, index_importFlowReducer as importFlowReducer, index_initImportState as initImportState, index_initVerifyState as initVerifyState, index_initialDisplayState as initialDisplayState, index_initialIdentityFlowState as initialIdentityFlowState, index_isGridSelectionCorrect as isGridSelectionCorrect, index_shuffleWithSeed as shuffleWithSeed, index_verifyFlowReducer as verifyFlowReducer };
 }
 
-export { Me2emProvider, PassphraseInput, type PassphraseInputProps, SeedPhraseDisplay, type SeedPhraseDisplayProps, SeedPhraseImport, type SeedPhraseImportProps, SeedPhraseVerify, type SeedPhraseVerifyProps, type UseIdentityContextResult, type UseSessionOptions, type UseSessionResult, index as headless, useCreateIdentity, useHandle, useIdentityContext, useImportSeed, useMe2emContext, useSession, useSubHandle };
+export { type Me2emContextValue, Me2emProvider, PassphraseInput, type PassphraseInputProps, SeedPhraseDisplay, type SeedPhraseDisplayProps, SeedPhraseImport, type SeedPhraseImportProps, SeedPhraseVerify, type SeedPhraseVerifyProps, type UseCreateIdentityResult, type UseIdentityContextResult, type UseImportSeedResult, type UseSessionOptions, type UseSessionResult, index as headless, useCreateIdentity, useHandle, useIdentityContext, useImportSeed, useMe2emContext, useSession, useSubHandle };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@me2em/react",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "React bindings for the Me2em protocol: identity lifecycle, seed phrase UX, hierarchical handles",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@me2em/core": "0.7.0-alpha.1"
+    "@me2em/core": "^0.7.0-alpha.2"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
@@ -46,6 +46,7 @@
     "build": "tsup",
     "test": "vitest run",
     "lint": "eslint src",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "build-docs": "typedoc"
   }
 }

package/src/react/index.ts

@@ -1,7 +1,10 @@
 export { Me2emProvider } from './Me2emProvider.js';
 export { useMe2emContext } from './context.js';
+export type { Me2emContextValue } from './context.js';
 export { useCreateIdentity } from './useCreateIdentity.js';
+export type { UseCreateIdentityResult } from './useCreateIdentity.js';
 export { useImportSeed } from './useImportSeed.js';
+export type { UseImportSeedResult } from './useImportSeed.js';
 export { useHandle } from './useHandle.js';
 export { useSubHandle } from './useSubHandle.js';
 export { SeedPhraseDisplay } from './SeedPhraseDisplay.js';

package/src/headless/context-key-store.ts

@@ -1,124 +0,0 @@
-// packages/react/src/headless/context-key-store.ts
-import type { IdentityContextData } from './identity-context-storage.js';
-
-const KEYS_PREFIX = '__keys:';
-
-export interface ContextKeyStore {
-  /** Save a persisted CryptoKey for later use. */
-  setCacheKey(key: CryptoKey): Promise<void>;
-  /** Retrieve the persisted CryptoKey, or null if not found. */
-  getCacheKey(): Promise<CryptoKey | null>;
-  /** Delete the persisted CryptoKey (called on logout). */
-  deleteCacheKey(): Promise<void>;
-  /** Persist the CryptoKey to IndexedDB for warm return after browser restart. */
-  persistCacheKey(): Promise<void>;
-  /** Load a previously persisted CryptoKey from IndexedDB. */
-  loadPersistedKey(): Promise<CryptoKey | null>;
-}
-
-/**
- * IndexedDB-backed key store. CryptoKey objects are structured-cloned
- * into an object store 'cryptoKeys' so they survive browser restarts.
- */
-export class InMemoryKeyStore implements ContextKeyStore {
-  private db: IDBDatabase | null = null;
-
-  private getDbName(identityId: string): string {
-    return `${KEYS_PREFIX}${identityId}`;
-  }
-
-  private async openOrCreate(): Promise<IDBDatabase> {
-    if (this.db) return this.db;
-
-    const name = this.getDbName('default');
-    return new Promise<IDBDatabase>((resolve, reject) => {
-      const request = indexedDB.open(name, 1);
-
-      request.onupgradeneeded = () => {
-        const db = request.result;
-        if (!db.objectStoreNames.contains('keys')) {
-          db.createObjectStore('keys', { keyPath: 'key' });
-        }
-        if (!db.objectStoreNames.contains('cryptoKeys')) {
-          db.createObjectStore('cryptoKeys', { keyPath: 'key' });
-        }
-      };
-
-      request.onsuccess = () => {
-        this.db = request.result;
-        resolve(request.result);
-      };
-
-      request.onerror = () => reject(new Error('Keys DB open failed'));
-    });
-  }
-
-  async setCacheKey(key: CryptoKey): Promise<void> {
-    this.cacheKey = key;
-    const db = await this.openOrCreate();
-    return new Promise<void>((resolve, reject) => {
-      const tx = db.transaction('cryptoKeys', 'readwrite');
-      const store = tx.objectStore('cryptoKeys');
-      store.put({ key: 'cacheKey', cryptoKey: key });
-
-      tx.oncomplete = () => resolve();
-      tx.onerror = () => reject(new Error('setCacheKey failed: ' + tx.error?.message));
-    });
-  }
-
-  private cacheKey: CryptoKey | null = null;
-
-  async getCacheKey(): Promise<CryptoKey | null> {
-    if (this.cacheKey) return this.cacheKey;
-    return this.loadPersistedKey();
-  }
-
-  async deleteCacheKey(): Promise<void> {
-    this.cacheKey = null;
-    const db = await this.openOrCreate();
-    return new Promise<void>((resolve, reject) => {
-      const tx = db.transaction('cryptoKeys', 'readwrite');
-      const store = tx.objectStore('cryptoKeys');
-      store.delete('cacheKey');
-
-      tx.oncomplete = () => resolve();
-      tx.onerror = () => reject(new Error('deleteCacheKey failed: ' + tx.error?.message));
-    });
-  }
-
-  async persistCacheKey(): Promise<void> {
-    const key = this.cacheKey;
-    if (!key) {
-      throw new Error('No cache key to persist');
-    }
-    const db = await this.openOrCreate();
-    return new Promise<void>((resolve, reject) => {
-      const tx = db.transaction('cryptoKeys', 'readwrite');
-      const store = tx.objectStore('cryptoKeys');
-      store.put({ key: 'cacheKey', cryptoKey: key });
-
-      tx.oncomplete = () => resolve();
-      tx.onerror = () => reject(new Error('persistCacheKey failed: ' + tx.error?.message));
-    });
-  }
-
-  async loadPersistedKey(): Promise<CryptoKey | null> {
-    const db = await this.openOrCreate();
-    return new Promise<CryptoKey | null>((resolve, reject) => {
-      const tx = db.transaction('cryptoKeys', 'readonly');
-      const store = tx.objectStore('cryptoKeys');
-      const request = store.get('cacheKey');
-
-      request.onsuccess = () => {
-        const record = request.result;
-        if (!record || !record.cryptoKey) {
-          resolve(null);
-          return;
-        }
-        resolve(record.cryptoKey);
-      };
-
-      request.onerror = () => resolve(null);
-    });
-  }
-}