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

package/README.md

@@ -1,12 +1,10 @@
-# @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.
+React bindings for the Me2eM protocol: identity lifecycle, seed phrase UX, and hierarchical handle derivation.
 
 ## Install
 
@@ -16,16 +14,23 @@ 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
-import { Me2emProvider, useCreateIdentity } from '@me2em/react';
+import { Me2eMProvider, useCreateIdentity } from '@me2em/react';
 
 function App() {
   return (
-    <Me2emProvider>
+    <Me2eMProvider>
       <CreateIdentityScreen />
-    </Me2emProvider>
+    </Me2eMProvider>
   );
 }
 
@@ -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 [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
+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
@@ -192,4 +221,4 @@ Each identity gets a separate IndexedDB database (name = SHA-256 hash of identit
 
 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

@@ -65,6 +65,7 @@ declare function useHandle(name: string): Handle | null;
 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;
@@ -364,4 +365,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/dist/index.js

@@ -53,7 +53,7 @@ import {
 } from "react";
 import {
   generateSeedPhrase,
-  get32ByteSeedFromMnemonic
+  get64ByteSeedFromMnemonic
 } from "@me2em/core";
 
 // src/headless/identity-flow.ts
@@ -159,7 +159,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 +198,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 +211,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) {
@@ -371,13 +371,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 +390,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 +417,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"
       }
     ),
@@ -787,13 +790,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,16 +818,22 @@ 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 useEffect5, useRef as useRef3 } 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 [context, setContext] = useState6(null);
+  const [isLoaded, setIsLoaded] = useState6(false);
+  const [error, setError] = useState6(null);
   const prevIdentityIdRef = useRef3(null);
+  const opRef = useRef3(0);
+  const identityRef = useRef3(null);
+  identityRef.current = identity;
   useEffect5(() => {
     let cancelled = false;
     if (!identity) {
@@ -839,8 +848,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,36 +863,47 @@ 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 useEffect6, useCallback as useCallback7, useRef as useRef4 } 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 [session, setSession] = useState7(null);
+  const [isLoaded, setIsLoaded] = useState7(false);
+  const [error, setError] = useState7(null);
   const timerRef = useRef4(null);
   const optionsRef = useRef4(options);
   const mountedRef = useRef4(true);
-  optionsRef.current = options;
-  const clearTimer = useCallback8(() => {
+  useEffect6(() => {
+    optionsRef.current = options;
+  });
+  const clearTimer = useCallback7(() => {
     if (timerRef.current) {
       clearTimeout(timerRef.current);
       timerRef.current = null;
@@ -895,7 +916,7 @@ function useSession(handle, options, autoRenew = true) {
       clearTimer();
     };
   }, [clearTimer]);
-  const renew = useCallback8(() => {
+  const renew = useCallback7(() => {
     clearTimer();
     const opts = optionsRef.current;
     if (!handle) {
@@ -964,25 +985,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 +1023,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 +1192,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");