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

package/src/react/Me2emProvider.tsx

@@ -2,6 +2,8 @@ import {
   useState,
   useCallback,
   useMemo,
+  useEffect,
+  useRef,
   type ReactNode,
 } from 'react';
 import { Identity } from '@me2em/core';
@@ -10,9 +12,32 @@ import { Me2emContext, type Me2emContextValue } from './context.js';
 export function Me2emProvider({ children }: { children: ReactNode }) {
   const [identity, setIdentity] = useState<Identity | null>(null);
 
+  // BL-47 dispose parity: the ref is mutated only in event handlers and
+  // cleanup effects, always alongside setIdentity — never inside a state
+  // updater (StrictMode double-invokes updaters; dispose is a side
+  // effect). A replaced/cleared handle is disposed at the swap, so
+  // stale references fail loudly with DisposedError (core contract)
+  // instead of silently operating on zeroed key material.
+  const identityRef = useRef<Identity | null>(null);
+  // Generation ticket for in-flight Identity.fromSeed results — the
+  // same load-race class fixed for useIdentityContext in rc.1: a
+  // result landing after a newer activation, clearIdentity() or
+  // unmount disposes its own handle instead of overwriting newer
+  // state.
+  const genRef = useRef(0);
+
   const activateIdentity = useCallback(async (seed: Uint8Array): Promise<boolean> => {
+    const gen = ++genRef.current;
     try {
       const id = await Identity.fromSeed(seed);
+      if (gen !== genRef.current) {
+        // Superseded while in flight: discard this handle loudly
+        // rather than leaking it into state.
+        id.dispose();
+        return false;
+      }
+      identityRef.current?.dispose(); // zero the replaced handle
+      identityRef.current = id;
       setIdentity(id);
       return true;
     } catch {
@@ -21,9 +46,24 @@ export function Me2emProvider({ children }: { children: ReactNode }) {
   }, []);
 
   const clearIdentity = useCallback(() => {
+    ++genRef.current; // invalidate in-flight activations
+    identityRef.current?.dispose();
+    identityRef.current = null;
     setIdentity(null);
   }, []);
 
+  // Unmount: cleanup-only dispose — no side effects in render or
+  // updaters (the identity was provider state, so it is unreachable
+  // after unmount either way; dispose just zeroizes it eagerly).
+  useEffect(() => {
+    return () => {
+      // eslint-disable-next-line react-hooks/exhaustive-deps -- reading the LIVE ticket at teardown is the point: invalidate whatever activation is in flight at unmount; snapshotting it would defeat the guard
+      ++genRef.current;
+      identityRef.current?.dispose();
+      identityRef.current = null;
+    };
+  }, []);
+
   const value = useMemo<Me2emContextValue>(
     () => ({ identity, hasIdentity: identity !== null, activateIdentity, clearIdentity }),
     [identity, activateIdentity, clearIdentity]

package/src/react/PassphraseInput.tsx

@@ -1,5 +1,5 @@
 // packages/react/src/react/PassphraseInput.tsx
-import { useState, useCallback } from 'react';
+import { useCallback } from 'react';
 
 export interface PassphraseInputProps {
   onPassphraseChange: (p: string) => void;

package/src/react/SeedPhraseDisplay.tsx

@@ -6,18 +6,37 @@ import {
 } from '../headless/display-flow.js';
 
 export interface SeedPhraseDisplayProps {
+  /** Seed material is reachable via React DevTools in this window; by design. */
   words: string[];
   onDismiss?: () => void;
   onCopyAllowed?: () => void;
 }
 
+/**
+ * R8: the permanent/transient line for a failed clipboard write is
+ * "can a retry in this window ever succeed?". Without the async
+ * Clipboard API (non-secure context, unsupported browser) it cannot —
+ * the failure is permanent, the copy-all button is disabled and the
+ * user is pointed at manual word selection. With the API present any
+ * rejection (lost focus, dismissed permission prompt, OS hiccup)
+ * stays transient: the button remains enabled and a fresh attempt
+ * may go through.
+ */
+function clipboardWriteAvailable(): boolean {
+  return (
+    typeof navigator !== 'undefined' &&
+    !!navigator.clipboard &&
+    typeof navigator.clipboard.writeText === 'function'
+  );
+}
+
 export function SeedPhraseDisplay({
   words,
   onDismiss,
   onCopyAllowed,
 }: SeedPhraseDisplayProps) {
   const [state, dispatch] = useReducer(displayFlowReducer, initialDisplayState);
-  const [copyFailed, setCopyFailed] = useState(false);
+  const [copyError, setCopyError] = useState<'transient' | 'permanent' | null>(null);
 
   const { status, copyCount } = state;
 
@@ -28,12 +47,12 @@ export function SeedPhraseDisplay({
   const handleCopy = async () => {
     if (status === 'revealed' && copyCount === 0) {
       try {
-        await (navigator as any).clipboard.writeText(words.join(' '));
+        await navigator.clipboard.writeText(words.join(' '));
         dispatch({ type: 'COPY', at: Date.now() });
-        setCopyFailed(false);
+        setCopyError(null);
         onCopyAllowed?.();
       } catch {
-        setCopyFailed(true);
+        setCopyError(clipboardWriteAvailable() ? 'transient' : 'permanent');
       }
     }
   };
@@ -72,15 +91,17 @@ export function SeedPhraseDisplay({
           </li>
         ))}
       </ol>
-      {copyFailed && (
-        <div data-testid="copy-error">
-          Copy failed — try again
+      {copyError && (
+        <div data-testid="copy-error" data-kind={copyError}>
+          {copyError === 'permanent'
+            ? 'Copy unavailable in this context — select the words manually'
+            : 'Copy failed — try again'}
         </div>
       )}
       <button
         data-testid="copy-all"
         onClick={handleCopy}
-        disabled={copyCount === 1}
+        disabled={copyCount === 1 || copyError === 'permanent'}
       >
         {copyCount === 1 ? 'Copied' : 'Copy all'}
       </button>

package/src/react/SeedPhraseImport.tsx

@@ -1,5 +1,5 @@
 // packages/react/src/react/SeedPhraseImport.tsx
-import { useReducer, useCallback, useEffect, useRef } from 'react';
+import { useReducer, useEffect, useRef } from 'react';
 import {
   importFlowReducer,
   initImportState,

package/src/react/SeedPhraseVerify.tsx

@@ -3,7 +3,6 @@ import { useReducer, useCallback, useState, useEffect, useRef } from 'react';
 import {
   verifyFlowReducer,
   initVerifyState,
-  type VerifyState,
 } from '../headless/verify-flow.js';
 import { wordlist } from '@me2em/core';
 
@@ -17,6 +16,15 @@ export interface SeedPhraseVerifyProps {
 
 const DEFAULT_GRID_SIZE_OFFSET = 8;
 
+/**
+ * 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.
+ */
 export function SeedPhraseVerify({
   realWords,
   gridSize,

package/src/react/context.ts

@@ -2,9 +2,25 @@ import { createContext, useContext } from 'react';
 import type { Identity } from '@me2em/core';
 
 export 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;
 }
 

package/src/react/useCreateIdentity.ts

@@ -6,7 +6,7 @@ import {
 } from 'react';
 import {
   generateSeedPhrase,
-  get32ByteSeedFromMnemonic,
+  get64ByteSeedFromMnemonic,
   type SeedStrength,
   type Identity,
 } from '@me2em/core';
@@ -37,7 +37,7 @@ export function useCreateIdentity(): UseCreateIdentityResult {
   const generate = useCallback(
     (opts?: { strength?: SeedStrength }) => {
       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' });

package/src/react/useHandle.ts

@@ -3,6 +3,14 @@ import { useState, useEffect } from 'react';
 import { type Handle } from '@me2em/core';
 import { useMe2emContext } from './context.js';
 
+/**
+ * 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).
+ */
 export function useHandle(name: string): Handle | null {
   const { identity } = useMe2emContext();
   const [handle, setHandle] = useState<Handle | null>(null);
@@ -10,6 +18,7 @@ export function useHandle(name: string): Handle | null {
   useEffect(() => {
     let cancelled = false;
     if (!identity) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- clearing the stale async result when identity is gone; set-during-render refactor is a tracked post-rc.2 follow-up
       setHandle(null);
       return;
     }

package/src/react/useIdentityContext.ts

@@ -1,5 +1,6 @@
 // packages/react/src/react/useIdentityContext.ts
 import { useState, useCallback, useEffect, useRef } from 'react';
+import type { Identity } from '@me2em/core';
 import type { IdentityContextStorage, IdentityContextData } from '../headless/identity-context-types.js';
 import { useMe2emContext } from './context.js';
 
@@ -9,6 +10,10 @@ function publicKeyToId(publicKey: Uint8Array): string {
     .join('');
 }
 
+function identityToId(identity: Identity | null): string | null {
+  return identity ? publicKeyToId(identity.getPublicKey()) : null;
+}
+
 export interface UseIdentityContextResult {
   context: IdentityContextData | null;
   isLoaded: boolean;
@@ -28,11 +33,23 @@ export function useIdentityContext(
   const [error, setError] = useState<string | null>(null);
 
   const prevIdentityIdRef = useRef<string | null>(null);
+  // Generation ticket for async state transitions. Load (identity
+  // change / `refresh()`), `save()` and `clear()` each take a ticket;
+  // a resolution may only commit state while its ticket is the newest
+  // one. Without this, an in-flight load started before a save could
+  // resolve after it and clobber the just-saved state with pre-save
+  // data (out-of-order async update — observed as a rare CI flake in
+  // the rerender spec; pinned there by a gated-storage test).
+  const opRef = useRef(0);
+  const identityRef = useRef<Identity | null>(null);
+  // eslint-disable-next-line react-hooks/refs -- render-time mirror of the latest identity: save()/clear() are stable callbacks (storage-only deps) and must verify at commit time, after their await, that the identity they started for is still the active one
+  identityRef.current = identity;
 
   useEffect(() => {
     let cancelled = false;
 
     if (!identity) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- clearing the stale async state when identity is gone (generation-ticket effect from the load-race fix); set-during-render refactor is a tracked post-rc.2 follow-up
       setContext(null);
       setIsLoaded(true);
       setError(null);
@@ -49,9 +66,10 @@ export function useIdentityContext(
     prevIdentityIdRef.current = identityId;
 
     // Open storage for this identity and load cached context (atomic)
+    const op = ++opRef.current;
     storage.openAndLoad(identityId)
       .then((data) => {
-        if (cancelled) return;
+        if (cancelled || op !== opRef.current) return;
         setContext(data);
         setIsLoaded(true);
         setError(null);
@@ -68,19 +86,37 @@ export function useIdentityContext(
   }, [identity, storage]);
 
   const save = useCallback(async (data: IdentityContextData): Promise<void> => {
+    const idAtStart = identityToId(identityRef.current);
+    opRef.current += 1; // invalidate any in-flight load/refresh
     await storage.save(data);
+    // If the identity switched while the write was in flight, state
+    // ownership has moved to the new identity's load effect — committing
+    // here would surface identity A's context under identity B. The
+    // generation ticket above only orders this op against in-flight
+    // loads; it does not know about identity switches.
+    if (identityToId(identityRef.current) !== idAtStart) return;
     setContext(data);
+    setError(null);
   }, [storage]);
 
   const clear = useCallback(async (): Promise<void> => {
+    const idAtStart = identityToId(identityRef.current);
+    opRef.current += 1; // invalidate any in-flight load/refresh
     await storage.clear();
+    // Same ownership rule as save(): a clear() resolving after an
+    // identity switch must not blank the new identity's freshly
+    // loaded context.
+    if (identityToId(identityRef.current) !== idAtStart) return;
     setContext(null);
+    setError(null);
   }, [storage]);
 
   const refresh = useCallback(async (): Promise<void> => {
     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]);
 

package/src/react/useImportSeed.ts

@@ -2,7 +2,7 @@
 import { useReducer, useCallback, type Reducer } from 'react';
 import {
   validateSeedPhrase,
-  get32ByteSeedFromMnemonic,
+  get64ByteSeedFromMnemonic,
   type Identity,
 } from '@me2em/core';
 import {
@@ -34,7 +34,7 @@ export function useImportSeed(): UseImportSeedResult {
         return;
       }
       try {
-        const seed = await get32ByteSeedFromMnemonic(words, passphrase ?? '');
+        const seed = await get64ByteSeedFromMnemonic(words, passphrase ?? '');
         dispatch({ type: 'IMPORT', seed });
         await activateIdentity(seed);
       } catch (err) {

package/src/react/useSession.ts

@@ -1,8 +1,7 @@
 // packages/react/src/react/useSession.ts
 import { useState, useEffect, useCallback, useRef } from 'react';
 import type { Handle } from '@me2em/core';
-import { Session, type SessionOptions, type SessionPayload } from '@me2em/core';
-import { useMe2emContext } from './context.js';
+import { Session } from '@me2em/core';
 
 /**
  * Options for useSession, memoized via deep comparison of
@@ -74,7 +73,6 @@ export function useSession(
   options: UseSessionOptions,
   autoRenew: boolean = true
 ): UseSessionResult {
-  const { identity } = useMe2emContext();
   const [session, setSession] = useState<Session | null>(null);
   const [isLoaded, setIsLoaded] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -82,8 +80,11 @@ export function useSession(
   const optionsRef = useRef(options);
   const mountedRef = useRef(true);
 
-  // Update options ref without triggering re-renders
-  optionsRef.current = options;
+  // Mirror the latest options into the ref after every commit —
+  // ref writes belong in effects, not during render (react-hooks/refs).
+  useEffect(() => {
+    optionsRef.current = options;
+  });
 
   const clearTimer = useCallback(() => {
     if (timerRef.current) {
@@ -128,6 +129,7 @@ export function useSession(
         const halfLife = Math.floor((s.expiresAt * 1000 - Date.now()) / 2);
         if (halfLife > 0) {
           timerRef.current = setTimeout(() => {
+            // eslint-disable-next-line react-hooks/immutability -- self-rescheduling renewal timer: the timer is cleared and re-created whenever renew itself changes (deps + clearTimer), so the captured binding is always the current one
             renew();
           }, Math.max(halfLife, 1000));
         }

package/src/react/useSubHandle.ts

@@ -2,6 +2,14 @@ import { useState, useEffect } from 'react';
 import { type SubHandle } from '@me2em/core';
 import { useMe2emContext } from './context.js';
 
+/**
+ * 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).
+ */
 export function useSubHandle(
   handleName: string,
   subName: string
@@ -12,6 +20,7 @@ export function useSubHandle(
   useEffect(() => {
     let cancelled = false;
     if (!identity) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- clearing the stale async result when identity is gone; set-during-render refactor is a tracked post-rc.2 follow-up
       setSubHandle(null);
       return;
     }