@me2em/react 0.1.0-alpha.2 → 1.0.0-rc.2

package/README.md

@@ -4,7 +4,7 @@
 
 ## 📦 @me2em/react — React bindings
 
-React bindings for the Me2em protocol: identity lifecycle, seed phrase UX, and hierarchical handle derivation.
+React bindings for the Me2eM protocol: identity lifecycle, seed phrase UX, and hierarchical handle derivation.
 
 ## Install
 
@@ -24,13 +24,13 @@ Requires React >= 18.0.0 as a peer dependency.
 ## Quick Start
 
 ```tsx
-import { Me2emProvider, useCreateIdentity } from '@me2em/react';
+import { Me2eMProvider, useCreateIdentity } from '@me2em/react';
 
 function App() {
   return (
-    <Me2emProvider>
+    <Me2eMProvider>
       <CreateIdentityScreen />
-    </Me2emProvider>
+    </Me2eMProvider>
   );
 }
 
@@ -90,7 +90,7 @@ this package:
 | **Context cache** | Per-identity encrypted storage of derived Handle context. |
 
 Full glossary (including Attestation, SubHandle, Ephemeral material):
-see the [root README](../../README.md).
+see the root [GLOSSARY.md](../../GLOSSARY.md).
 
 **This package never persists your seed.** The seed phrase exists in
 two places only — your paper and transient memory during login. What
@@ -188,6 +188,15 @@ import {
 function ContextPanel() {
   const storage = useMemo(() => new IdentityContextIDBStorage(), []);
 
+  // Caller-owned lifecycle (R5): close the IDB connection on unmount.
+  // close() also drops the in-memory cache key — reopen + setCacheKey
+  // before the next use.
+  useEffect(() => {
+    return () => {
+      void storage.close();
+    };
+  }, [storage]);
+
   // At login time, derive and set the cache key:
   useEffect(() => {
     const salt = crypto.getRandomValues(new Uint8Array(32));
@@ -215,10 +224,10 @@ function ContextPanel() {
 }
 ```
 
-Each identity gets a separate IndexedDB database (name = SHA-256 hash of identity ID), guaranteeing full isolation between identities.
+Each identity gets a separate IndexedDB database (name = SHA-256 hash of identity ID), guaranteeing full isolation between identities. The storage connection is caller-owned: `close()` on unmount (as above) also drops the in-memory cache key — `open()`/`openAndLoad()` plus `setCacheKey()` are required before the next use.
 
 ## Status
 
 Alpha. API may change between 0.1.x releases. See [packages/core/README.md](../../packages/core/README.md) for the underlying protocol.
 
-Roadmap: @me2em/crypto protocol mechanisms — planned
+Roadmap: `@me2em/crypto` shipped (0.1.0-alpha.1); `@me2em/messenger` planned (BACKLOG BL-29).

package/dist/index.d.ts

@@ -7,9 +7,25 @@ declare function Me2emProvider({ children }: {
 }): react.JSX.Element;
 
 interface Me2emContextValue {
+    /**
+     * Active identity, or null. The previously active identity is
+     * disposed (key material zeroed) the moment it is replaced by a new
+     * activation or by {@link clearIdentity} — stale references fail
+     * loudly with `DisposedError` per the core contract (BL-47).
+     */
     identity: Identity | null;
     hasIdentity: boolean;
+    /**
+     * Activates an identity from raw seed bytes, replacing (and
+     * disposing) any previously active identity. Resolves `false` if
+     * derivation failed or the activation was superseded by a newer
+     * activation / `clearIdentity()` while in flight.
+     *
+     * Does not consume the seed — the caller owns the buffer and must
+     * zero it when done (BL-48).
+     */
     activateIdentity: (seed: Uint8Array) => Promise<boolean>;
+    /** Disposes the active identity (if any) and clears it. */
     clearIdentity: () => void;
 }
 declare function useMe2emContext(): Me2emContextValue;
@@ -18,6 +34,13 @@ type IdentityFlowStatus = 'idle' | 'seed-generated' | 'verified' | 'ready' | 'im
 interface IdentityFlowState {
     status: IdentityFlowStatus;
     seedWords: string[] | null;
+    /**
+     * Raw seed material, retained in state after 'verified'/'imported'
+     * by design — the flow does NOT self-consume it (BL-48): headless
+     * consumers may still read it at this point. Reachable via devtools
+     * in this window (R15 category). An explicit `discardSeed()` action
+     * is the planned v1.1 opt-in; until then the app owns dropping it.
+     */
     identitySeed: Uint8Array | null;
     error: string | null;
 }
@@ -60,11 +83,28 @@ interface UseImportSeedResult {
 }
 declare function useImportSeed(): UseImportSeedResult;
 
+/**
+ * Derives the named Handle for the active identity.
+ *
+ * Silent-failure contract (R7): on derivation failure the hook logs
+ * via console.error and keeps returning null — there is no thrown or
+ * returned error signal. The structured `{ handle, error }` shape is
+ * a post-freeze v1.1 candidate (BL-50).
+ */
 declare function useHandle(name: string): Handle | null;
 
+/**
+ * Derives the named SubHandle under the given Handle.
+ *
+ * Silent-failure contract (R7): on derivation failure the hook logs
+ * via console.error and keeps returning null — there is no thrown or
+ * returned error signal. The structured `{ handle, error }` shape is
+ * a post-freeze v1.1 candidate (BL-50).
+ */
 declare function useSubHandle(handleName: string, subName: string): SubHandle | null;
 
 interface SeedPhraseDisplayProps {
+    /** Seed material is reachable via React DevTools in this window; by design. */
     words: string[];
     onDismiss?: () => void;
     onCopyAllowed?: () => void;
@@ -78,6 +118,15 @@ interface SeedPhraseVerifyProps {
     onVerified: () => void;
     onFailed?: (attempts: number) => void;
 }
+/**
+ * Confirmation grid for a generated seed phrase.
+ *
+ * The grid shuffle is deterministic by design (fixed base seed 42;
+ * each retry shifts it by `+retryCount + 1`) for testability and SSR
+ * stability — it is NOT a security control: decoy words come from the
+ * public wordlist, so the layout leaks nothing (BL-49). A
+ * `randomSeed` prop is deliberately not offered in the frozen 1.0 API.
+ */
 declare function SeedPhraseVerify({ realWords, gridSize, wordlist: propWordlist, onVerified, onFailed, }: SeedPhraseVerifyProps): react.JSX.Element;
 
 interface SeedPhraseImportProps {
@@ -109,6 +158,15 @@ interface IdentityContextStorage {
     save(data: IdentityContextData): Promise<void>;
     load(): Promise<IdentityContextData | null>;
     clear(): Promise<void>;
+    /**
+     * Closes the IDB connection. Caller-owned lifecycle (R5): close()
+     * also drops the in-memory cache key and the open identity binding,
+     * so every further operation throws "Storage not opened" until the
+     * storage is reopened via open()/openAndLoad() and the cache key is
+     * set again. open() with a different identityId closes the previous
+     * connection automatically; same-identity open() after close()
+     * simply opens a fresh connection.
+     */
     close(): Promise<void>;
     /** Open storage for identity and atomically load cached context. */
     openAndLoad(identityId: string): Promise<IdentityContextData | null>;
@@ -320,7 +378,9 @@ interface ContextEnvelope {
  * Raw key bytes exist only transiently during importKey.
  *
  * @param loginMaterial - high-entropy bytes available at login
- *   (derived from the seed while it is still in memory).
+ *   (derived from the seed while it is still in memory). Caller-owned:
+ *   deriveCacheKey reads but never wipes them — zero the buffer (and
+ *   the seed it came from) when done (R6).
  * @param salt - FRESH random bytes for this login. Never reuse a
  *   salt across logins: the whole point is that a compromised
  *   cacheKey from session N is useless in session N+1.

package/dist/index.js

@@ -8,7 +8,9 @@ var __export = (target, all) => {
 import {
   useState,
   useCallback,
-  useMemo
+  useMemo,
+  useEffect,
+  useRef
 } from "react";
 import { Identity } from "@me2em/core";
 
@@ -27,9 +29,18 @@ function useMe2emContext() {
 import { jsx } from "react/jsx-runtime";
 function Me2emProvider({ children }) {
   const [identity, setIdentity] = useState(null);
+  const identityRef = useRef(null);
+  const genRef = useRef(0);
   const activateIdentity = useCallback(async (seed) => {
+    const gen = ++genRef.current;
     try {
       const id = await Identity.fromSeed(seed);
+      if (gen !== genRef.current) {
+        id.dispose();
+        return false;
+      }
+      identityRef.current?.dispose();
+      identityRef.current = id;
       setIdentity(id);
       return true;
     } catch {
@@ -37,8 +48,18 @@ function Me2emProvider({ children }) {
     }
   }, []);
   const clearIdentity = useCallback(() => {
+    ++genRef.current;
+    identityRef.current?.dispose();
+    identityRef.current = null;
     setIdentity(null);
   }, []);
+  useEffect(() => {
+    return () => {
+      ++genRef.current;
+      identityRef.current?.dispose();
+      identityRef.current = null;
+    };
+  }, []);
   const value = useMemo(
     () => ({ identity, hasIdentity: identity !== null, activateIdentity, clearIdentity }),
     [identity, activateIdentity, clearIdentity]
@@ -53,7 +74,7 @@ import {
 } from "react";
 import {
   generateSeedPhrase,
-  get32ByteSeedFromMnemonic
+  get64ByteSeedFromMnemonic
 } from "@me2em/core";
 
 // src/headless/identity-flow.ts
@@ -159,7 +180,7 @@ function useCreateIdentity() {
   const generate = useCallback2(
     (opts) => {
       const words = generateSeedPhrase(opts?.strength ?? 128);
-      get32ByteSeedFromMnemonic(words).then((derivedSeed) => {
+      get64ByteSeedFromMnemonic(words).then((derivedSeed) => {
         dispatch({ type: "GENERATE", words, seed: derivedSeed });
       }).catch(() => {
         dispatch({ type: "FAIL", message: "Failed to generate seed" });
@@ -198,7 +219,7 @@ function useCreateIdentity() {
 import { useReducer as useReducer2, useCallback as useCallback3 } from "react";
 import {
   validateSeedPhrase,
-  get32ByteSeedFromMnemonic as get32ByteSeedFromMnemonic2
+  get64ByteSeedFromMnemonic as get64ByteSeedFromMnemonic2
 } from "@me2em/core";
 function useImportSeed() {
   const { activateIdentity, clearIdentity, identity } = useMe2emContext();
@@ -211,7 +232,7 @@ function useImportSeed() {
         return;
       }
       try {
-        const seed = await get32ByteSeedFromMnemonic2(words, passphrase ?? "");
+        const seed = await get64ByteSeedFromMnemonic2(words, passphrase ?? "");
         dispatch({ type: "IMPORT", seed });
         await activateIdentity(seed);
       } catch (err) {
@@ -235,11 +256,11 @@ function useImportSeed() {
 }
 
 // src/react/useHandle.ts
-import { useState as useState2, useEffect } from "react";
+import { useState as useState2, useEffect as useEffect2 } from "react";
 function useHandle(name) {
   const { identity } = useMe2emContext();
   const [handle, setHandle] = useState2(null);
-  useEffect(() => {
+  useEffect2(() => {
     let cancelled = false;
     if (!identity) {
       setHandle(null);
@@ -258,11 +279,11 @@ function useHandle(name) {
 }
 
 // src/react/useSubHandle.ts
-import { useState as useState3, useEffect as useEffect2 } from "react";
+import { useState as useState3, useEffect as useEffect3 } from "react";
 function useSubHandle(handleName, subName) {
   const { identity } = useMe2emContext();
   const [subHandle, setSubHandle] = useState3(null);
-  useEffect2(() => {
+  useEffect3(() => {
     let cancelled = false;
     if (!identity) {
       setSubHandle(null);
@@ -371,13 +392,16 @@ function displayFlowReducer(state, event) {
 
 // src/react/SeedPhraseDisplay.tsx
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+function clipboardWriteAvailable() {
+  return typeof navigator !== "undefined" && !!navigator.clipboard && typeof navigator.clipboard.writeText === "function";
+}
 function SeedPhraseDisplay({
   words,
   onDismiss,
   onCopyAllowed
 }) {
   const [state, dispatch] = useReducer3(displayFlowReducer, initialDisplayState);
-  const [copyFailed, setCopyFailed] = useState4(false);
+  const [copyError, setCopyError] = useState4(null);
   const { status, copyCount } = state;
   const handleReveal = () => {
     dispatch({ type: "REVEAL", at: Date.now() });
@@ -387,10 +411,10 @@ function SeedPhraseDisplay({
       try {
         await navigator.clipboard.writeText(words.join(" "));
         dispatch({ type: "COPY", at: Date.now() });
-        setCopyFailed(false);
+        setCopyError(null);
         onCopyAllowed?.();
       } catch {
-        setCopyFailed(true);
+        setCopyError(clipboardWriteAvailable() ? "transient" : "permanent");
       }
     }
   };
@@ -414,13 +438,13 @@ function SeedPhraseDisplay({
       },
       i
     )) }),
-    copyFailed && /* @__PURE__ */ jsx2("div", { "data-testid": "copy-error", children: "Copy failed \u2014 try again" }),
+    copyError && /* @__PURE__ */ jsx2("div", { "data-testid": "copy-error", "data-kind": copyError, children: copyError === "permanent" ? "Copy unavailable in this context \u2014 select the words manually" : "Copy failed \u2014 try again" }),
     /* @__PURE__ */ jsx2(
       "button",
       {
         "data-testid": "copy-all",
         onClick: handleCopy,
-        disabled: copyCount === 1,
+        disabled: copyCount === 1 || copyError === "permanent",
         children: copyCount === 1 ? "Copied" : "Copy all"
       }
     ),
@@ -429,7 +453,7 @@ function SeedPhraseDisplay({
 }
 
 // src/react/SeedPhraseVerify.tsx
-import { useReducer as useReducer4, useCallback as useCallback4, useState as useState5, useEffect as useEffect3, useRef } from "react";
+import { useReducer as useReducer4, useCallback as useCallback4, useState as useState5, useEffect as useEffect4, useRef as useRef2 } from "react";
 
 // src/headless/seed-words.ts
 function shuffleWithSeed(items, seed) {
@@ -579,7 +603,7 @@ function SeedPhraseVerify({
   );
   const [retryCount, setRetryCount] = useState5(0);
   const { status, grid: gridData, selected } = state;
-  const notifiedRef = useRef(false);
+  const notifiedRef = useRef2(false);
   const handleSelect = useCallback4(
     (index) => {
       if (status === "correct" || status === "incorrect") return;
@@ -588,7 +612,7 @@ function SeedPhraseVerify({
     },
     [status, selected.length, gridData.correctIndices.length]
   );
-  useEffect3(() => {
+  useEffect4(() => {
     if (notifiedRef.current) return;
     if (selected.length === gridData.correctIndices.length && selected.length > 0 && status === "collecting") {
       dispatch({ type: "CHECK" });
@@ -639,7 +663,7 @@ function SeedPhraseVerify({
 }
 
 // src/react/SeedPhraseImport.tsx
-import { useReducer as useReducer5, useEffect as useEffect4, useRef as useRef2 } from "react";
+import { useReducer as useReducer5, useEffect as useEffect5, useRef as useRef3 } from "react";
 
 // src/headless/import-flow.ts
 import { validateSeedPhrase as validateSeedPhrase2 } from "@me2em/core";
@@ -713,12 +737,12 @@ function SeedPhraseImport({
     (params) => initImportState(params.expectedCount)
   );
   const count = state.expectedCount;
-  const prevStatusRef = useRef2(state.status);
-  const lastImportedRef = useRef2(null);
-  useEffect4(() => {
+  const prevStatusRef = useRef3(state.status);
+  const lastImportedRef = useRef3(null);
+  useEffect5(() => {
     dispatch({ type: "CHECK" });
   }, [state.words]);
-  useEffect4(() => {
+  useEffect5(() => {
     const prevStatus = prevStatusRef.current;
     prevStatusRef.current = state.status;
     if (state.status === "valid" && prevStatus !== "valid") {
@@ -787,13 +811,13 @@ function SeedPhraseImport({
 }
 
 // src/react/PassphraseInput.tsx
-import { useCallback as useCallback6 } from "react";
+import { useCallback as useCallback5 } from "react";
 import { jsx as jsx5, jsxs as jsxs4 } from "react/jsx-runtime";
 function PassphraseInput({
   onPassphraseChange,
   showWarnings = true
 }) {
-  const handleChange = useCallback6(
+  const handleChange = useCallback5(
     (e) => {
       const value = e.target.value.normalize("NFKC");
       onPassphraseChange(value);
@@ -815,17 +839,23 @@ function PassphraseInput({
 }
 
 // src/react/useIdentityContext.ts
-import { useState as useState7, useCallback as useCallback7, useEffect as useEffect5, useRef as useRef3 } from "react";
+import { useState as useState6, useCallback as useCallback6, useEffect as useEffect6, useRef as useRef4 } from "react";
 function publicKeyToId(publicKey) {
   return Array.from(publicKey).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+function identityToId(identity) {
+  return identity ? publicKeyToId(identity.getPublicKey()) : null;
+}
 function useIdentityContext(storage) {
   const { identity } = useMe2emContext();
-  const [context, setContext] = useState7(null);
-  const [isLoaded, setIsLoaded] = useState7(false);
-  const [error, setError] = useState7(null);
-  const prevIdentityIdRef = useRef3(null);
-  useEffect5(() => {
+  const [context, setContext] = useState6(null);
+  const [isLoaded, setIsLoaded] = useState6(false);
+  const [error, setError] = useState6(null);
+  const prevIdentityIdRef = useRef4(null);
+  const opRef = useRef4(0);
+  const identityRef = useRef4(null);
+  identityRef.current = identity;
+  useEffect6(() => {
     let cancelled = false;
     if (!identity) {
       setContext(null);
@@ -839,8 +869,9 @@ function useIdentityContext(storage) {
       });
     }
     prevIdentityIdRef.current = identityId;
+    const op = ++opRef.current;
     storage.openAndLoad(identityId).then((data) => {
-      if (cancelled) return;
+      if (cancelled || op !== opRef.current) return;
       setContext(data);
       setIsLoaded(true);
       setError(null);
@@ -853,49 +884,60 @@ function useIdentityContext(storage) {
       cancelled = true;
     };
   }, [identity, storage]);
-  const save = useCallback7(async (data) => {
+  const save = useCallback6(async (data) => {
+    const idAtStart = identityToId(identityRef.current);
+    opRef.current += 1;
     await storage.save(data);
+    if (identityToId(identityRef.current) !== idAtStart) return;
     setContext(data);
+    setError(null);
   }, [storage]);
-  const clear = useCallback7(async () => {
+  const clear = useCallback6(async () => {
+    const idAtStart = identityToId(identityRef.current);
+    opRef.current += 1;
     await storage.clear();
+    if (identityToId(identityRef.current) !== idAtStart) return;
     setContext(null);
+    setError(null);
   }, [storage]);
-  const refresh = useCallback7(async () => {
+  const refresh = useCallback6(async () => {
     if (!identity) return;
     const identityId = publicKeyToId(identity.getPublicKey());
+    const op = ++opRef.current;
     const data = await storage.openAndLoad(identityId);
+    if (op !== opRef.current) return;
     setContext(data);
   }, [identity, storage]);
   return { context, isLoaded, error, save, clear, refresh };
 }
 
 // src/react/useSession.ts
-import { useState as useState8, useEffect as useEffect6, useCallback as useCallback8, useRef as useRef4 } from "react";
+import { useState as useState7, useEffect as useEffect7, useCallback as useCallback7, useRef as useRef5 } from "react";
 import { Session } from "@me2em/core";
 function useSession(handle, options, autoRenew = true) {
-  const { identity } = useMe2emContext();
-  const [session, setSession] = useState8(null);
-  const [isLoaded, setIsLoaded] = useState8(false);
-  const [error, setError] = useState8(null);
-  const timerRef = useRef4(null);
-  const optionsRef = useRef4(options);
-  const mountedRef = useRef4(true);
-  optionsRef.current = options;
-  const clearTimer = useCallback8(() => {
+  const [session, setSession] = useState7(null);
+  const [isLoaded, setIsLoaded] = useState7(false);
+  const [error, setError] = useState7(null);
+  const timerRef = useRef5(null);
+  const optionsRef = useRef5(options);
+  const mountedRef = useRef5(true);
+  useEffect7(() => {
+    optionsRef.current = options;
+  });
+  const clearTimer = useCallback7(() => {
     if (timerRef.current) {
       clearTimeout(timerRef.current);
       timerRef.current = null;
     }
   }, []);
-  useEffect6(() => {
+  useEffect7(() => {
     mountedRef.current = true;
     return () => {
       mountedRef.current = false;
       clearTimer();
     };
   }, [clearTimer]);
-  const renew = useCallback8(() => {
+  const renew = useCallback7(() => {
     clearTimer();
     const opts = optionsRef.current;
     if (!handle) {
@@ -929,7 +971,7 @@ function useSession(handle, options, autoRenew = true) {
       setError(err instanceof Error ? err.message : String(err));
     });
   }, [handle, autoRenew, clearTimer]);
-  useEffect6(() => {
+  useEffect7(() => {
     if (mountedRef.current) {
       renew();
     }
@@ -964,25 +1006,7 @@ __export(headless_exports, {
 });
 
 // src/headless/context-crypto.ts
-function toB64(bytes) {
-  let binary = "";
-  for (const byte of bytes) {
-    binary += String.fromCharCode(byte);
-  }
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function fromB64(s) {
-  let base64 = s.replace(/-/g, "+").replace(/_/g, "/");
-  while (base64.length % 4 !== 0) {
-    base64 += "=";
-  }
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) {
-    bytes[i] = binary.charCodeAt(i);
-  }
-  return bytes;
-}
+import { base64urlEncode, base64urlDecode } from "@me2em/core";
 async function deriveCacheKey(loginMaterial, salt) {
   const base = await crypto.subtle.importKey(
     "raw",
@@ -1020,17 +1044,17 @@ async function encryptContext(key, data) {
   );
   return {
     v: 1,
-    salt: toB64(salt),
-    iv: toB64(iv),
-    ct: toB64(new Uint8Array(ct))
+    salt: base64urlEncode(salt),
+    iv: base64urlEncode(iv),
+    ct: base64urlEncode(new Uint8Array(ct))
   };
 }
 async function decryptContext(key, envelope) {
   if (envelope.v !== 1) throw new Error("Unsupported envelope version");
   const pt = await crypto.subtle.decrypt(
-    { name: "AES-GCM", iv: fromB64(envelope.iv) },
+    { name: "AES-GCM", iv: base64urlDecode(envelope.iv) },
     key,
-    fromB64(envelope.ct)
+    base64urlDecode(envelope.ct)
   );
   return JSON.parse(new TextDecoder().decode(pt));
 }
@@ -1189,7 +1213,7 @@ var IdentityContextIDBStorage = class {
     if (!db) {
       return null;
     }
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve) => {
       const tx = db.transaction(KEYS_STORE_NAME, "readonly");
       const store = tx.objectStore(KEYS_STORE_NAME);
       const request = store.get("cache");