@me2em/react 0.1.0-alpha.1

package/src/headless/identity-context-storage.ts

@@ -0,0 +1,205 @@
+// packages/react/src/headless/identity-context-storage.ts
+import { encryptContext, decryptContext, type ContextEnvelope } from './context-crypto.js';
+import type { IdentityContextData, IdentityContextStorage } from './identity-context-types.js';
+export type { IdentityContextData };
+
+const DB_NAME_PREFIX = 'me2em_';
+const STORE_NAME = 'context';
+const KEYS_STORE_NAME = 'cryptoKeys';
+const CACHE_KEY = 'cache';
+
+function hashToHex(data: Uint8Array): string {
+  const hexParts: string[] = [];
+  for (const byte of data) {
+    hexParts.push(byte.toString(16).padStart(2, '0'));
+  }
+  return hexParts.join('');
+}
+
+async function sha256Hex(data: Uint8Array): Promise<string> {
+  const buffer = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;
+  const digest: ArrayBuffer = await crypto.subtle.digest('SHA-256', buffer);
+  return hashToHex(new Uint8Array(digest));
+}
+
+async function dbNameForIdentity(identityId: string): Promise<string> {
+  const hash = await sha256Hex(new TextEncoder().encode(identityId));
+  return DB_NAME_PREFIX + hash.slice(0, 16);
+}
+
+export class IdentityContextIDBStorage implements IdentityContextStorage {
+  private db: IDBDatabase | null = null;
+  private currentIdentityId: string | null = null;
+  private cacheKey: CryptoKey | null = null;
+
+  private async getDb(): Promise<IDBDatabase> {
+    if (!this.db) {
+      throw new Error('Storage not opened — call open() first');
+    }
+    return this.db;
+  }
+
+  async open(identityId: string): Promise<void> {
+    if (this.currentIdentityId !== null && this.currentIdentityId !== identityId) {
+      await this.close();
+    }
+
+    this.currentIdentityId = identityId;
+    const name = await dbNameForIdentity(identityId);
+
+    return new Promise<void>((resolve, reject) => {
+      const request = indexedDB.open(name, 1);
+
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(STORE_NAME)) {
+          db.createObjectStore(STORE_NAME, { keyPath: 'key' });
+        }
+        if (!db.objectStoreNames.contains(KEYS_STORE_NAME)) {
+          db.createObjectStore(KEYS_STORE_NAME, { keyPath: 'key' });
+        }
+      };
+
+      request.onsuccess = () => {
+        this.db = request.result;
+        resolve();
+      };
+
+      request.onerror = () => {
+        reject(new Error('IndexedDB open failed: ' + request.error?.message));
+      };
+    });
+  }
+
+  async openAndLoad(identityId: string): Promise<IdentityContextData | null> {
+    await this.open(identityId);
+    const key = this.cacheKey ?? await this.loadPersistedKey();
+    if (!key) {
+      return null;
+    }
+    this.cacheKey = key;
+    return this.load();
+  }
+
+  async save(data: IdentityContextData): Promise<void> {
+    const key = this.cacheKey;
+    if (!key) {
+      throw new Error('No cache key set — call setCacheKey before save');
+    }
+    const envelope = await encryptContext(key, data);
+    const db = await this.getDb();
+    return new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readwrite');
+      const store = tx.objectStore(STORE_NAME);
+      store.put({ key: CACHE_KEY, envelope });
+
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(new Error('Save failed: ' + tx.error?.message));
+    });
+  }
+
+  async load(): Promise<IdentityContextData | null> {
+    const db = await this.getDb();
+    const key = this.cacheKey;
+    if (!key) {
+      return null;
+    }
+    return new Promise<IdentityContextData | null>((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readonly');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.get(CACHE_KEY);
+
+      request.onsuccess = () => {
+        const record = request.result;
+        if (!record || !record.envelope) {
+          resolve(null);
+          return;
+        }
+        decryptContext(key, record.envelope)
+          .then((data) => {
+            if (data.identityId !== this.currentIdentityId) {
+              resolve(null);
+              return;
+            }
+            resolve(data);
+          })
+          .catch(() => {
+            resolve(null);
+          });
+      };
+
+      request.onerror = () => reject(new Error('Load failed: ' + request.error?.message));
+    });
+  }
+
+  async clear(): Promise<void> {
+    const db = await this.getDb();
+    return new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readwrite');
+      const store = tx.objectStore(STORE_NAME);
+      store.delete(CACHE_KEY);
+
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(new Error('Clear failed: ' + tx.error?.message));
+    });
+  }
+
+  async close(): Promise<void> {
+    const db = this.db;
+    this.db = null;
+    this.currentIdentityId = null;
+    this.cacheKey = null;
+    if (db) {
+      db.close();
+    }
+  }
+
+  setCacheKey(key: CryptoKey): void {
+    this.cacheKey = key;
+  }
+
+  getCacheKey(): CryptoKey | null {
+    return this.cacheKey;
+  }
+
+  async persistCacheKey(): Promise<void> {
+    const key = this.cacheKey;
+    if (!key) {
+      throw new Error('No cache key to persist — call setCacheKey first');
+    }
+    const db = await this.getDb();
+    return new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(KEYS_STORE_NAME, 'readwrite');
+      const store = tx.objectStore(KEYS_STORE_NAME);
+      store.put({ key: 'cache', cryptoKey: key });
+
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(new Error('persistCacheKey failed: ' + tx.error?.message));
+    });
+  }
+
+  async loadPersistedKey(): Promise<CryptoKey | null> {
+    const db = this.db;
+    if (!db) {
+      return null;
+    }
+    return new Promise<CryptoKey | null>((resolve, reject) => {
+      const tx = db.transaction(KEYS_STORE_NAME, 'readonly');
+      const store = tx.objectStore(KEYS_STORE_NAME);
+      const request = store.get('cache');
+
+      request.onsuccess = () => {
+        const record = request.result;
+        if (!record || !record.cryptoKey) {
+          resolve(null);
+          return;
+        }
+        resolve(record.cryptoKey);
+      };
+
+      request.onerror = () => {
+        resolve(null);
+      };
+    });
+  }
+}

package/src/headless/identity-context-types.ts

@@ -0,0 +1,30 @@
+// packages/react/src/headless/identity-context-types.ts
+export interface IdentityContextData {
+  /** base64url identity public key — владелец кэша. */
+  identityId: string;
+  /** Реестр Handle-контекстов этой Identity. */
+  handles: Array<{
+    name: string;
+    subHandles?: string[];
+    meta?: Record<string, unknown>;
+  }>;
+  savedAt: number;
+}
+
+export interface IdentityContextStorage {
+  open(identityId: string): Promise<void>;
+  save(data: IdentityContextData): Promise<void>;
+  load(): Promise<IdentityContextData | null>;
+  clear(): Promise<void>;
+  close(): Promise<void>;
+  /** Open storage for identity and atomically load cached context. */
+  openAndLoad(identityId: string): Promise<IdentityContextData | null>;
+  /** Set the persisted cache key (called at login). */
+  setCacheKey(key: CryptoKey): void;
+  /** Get the currently set cache key, or null. */
+  getCacheKey(): CryptoKey | null;
+  /** 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>;
+}

package/src/headless/identity-flow.ts

@@ -0,0 +1,106 @@
+import type { IdentityFlowState, IdentityFlowEvent } from './types.js';
+
+export const initialIdentityFlowState: IdentityFlowState = {
+  status: 'idle',
+  seedWords: null,
+  identitySeed: null,
+  error: null,
+};
+
+const UNEXPECTED_EVENTS: Record<string, string> = {
+  CONFIRM_WORDS: 'CONFIRM_WORDS called from idle — no seed to confirm',
+  RESET: 'RESET called from idle — nothing to reset',
+};
+
+export function identityFlowReducer(
+  state: IdentityFlowState,
+  event: IdentityFlowEvent
+): IdentityFlowState {
+  const { type } = event;
+
+  switch (state.status) {
+    case 'idle': {
+      if (type === 'GENERATE') {
+        return {
+          status: 'seed-generated',
+          seedWords: event.words,
+          identitySeed: event.seed,
+          error: null,
+        };
+      }
+      if (type === 'IMPORT') {
+        return {
+          status: 'imported',
+          seedWords: null,
+          identitySeed: event.seed,
+          error: null,
+        };
+      }
+      if (type === 'FAIL') {
+        return {
+          status: 'error',
+          seedWords: null,
+          identitySeed: null,
+          error: event.message,
+        };
+      }
+      if (UNEXPECTED_EVENTS[type]) {
+        console.warn(UNEXPECTED_EVENTS[type]);
+        return state;
+      }
+      return state;
+    }
+
+    case 'seed-generated': {
+      if (type === 'CONFIRM_WORDS') {
+        return {
+          status: 'verified',
+          seedWords: null,
+          identitySeed: state.identitySeed,
+          error: null,
+        };
+      }
+      if (type === 'FAIL') {
+        return {
+          status: 'error',
+          seedWords: null,
+          identitySeed: null,
+          error: event.message,
+        };
+      }
+      if (type === 'RESET') {
+        return initialIdentityFlowState;
+      }
+      console.warn(`Unexpected event ${type} in seed-generated`);
+      return state;
+    }
+
+    case 'verified':
+    case 'imported': {
+      if (type === 'RESET') {
+        return initialIdentityFlowState;
+      }
+      if (type === 'FAIL') {
+        return {
+          status: 'error',
+          seedWords: null,
+          identitySeed: null,
+          error: event.message,
+        };
+      }
+      console.warn(`Unexpected event ${type} in ${state.status}`);
+      return state;
+    }
+
+    case 'error': {
+      if (type === 'RESET') {
+        return initialIdentityFlowState;
+      }
+      console.warn(`Unexpected event ${type} in error`);
+      return state;
+    }
+
+    default:
+      return state;
+  }
+}

package/src/headless/import-flow.ts

@@ -0,0 +1,82 @@
+// packages/react/src/headless/import-flow.ts
+import { validateSeedPhrase, type SeedStrength } from '@me2em/core';
+
+export type ImportStatus = 'entering' | 'valid' | 'invalid';
+
+export interface ImportState {
+  status: ImportStatus;
+  words: (string | null)[];
+  expectedCount: 12 | 24;
+}
+
+export type ImportEvent =
+  | { type: 'INIT'; expectedCount: 12 | 24 }
+  | { type: 'SET_WORD'; position: number; word: string }
+  | { type: 'CLEAR_WORD'; position: number }
+  | { type: 'CHECK' }
+  | { type: 'RESET' };
+
+export function initImportState(expectedCount: 12 | 24): ImportState {
+  return {
+    status: 'entering',
+    words: Array(expectedCount).fill(null),
+    expectedCount,
+  };
+}
+
+export function importFlowReducer(
+  state: ImportState,
+  event: ImportEvent
+): ImportState {
+  const { type } = event;
+
+  if (type === 'INIT') {
+    return initImportState(event.expectedCount);
+  }
+
+  if (type === 'RESET') {
+    return initImportState(state.expectedCount);
+  }
+
+  if (type === 'SET_WORD') {
+    const { position, word } = event;
+    if (position < 0 || position >= state.expectedCount) {
+      console.warn(`SET_WORD: position ${position} out of bounds`);
+      return state;
+    }
+    const normalized = word.toLowerCase().trim();
+    const newWords = [...state.words] as (string | null)[];
+    newWords[position] = normalized;
+    return { ...state, words: newWords, status: 'entering' };
+  }
+
+  if (type === 'CLEAR_WORD') {
+    const { position } = event;
+    if (position < 0 || position >= state.expectedCount) {
+      console.warn(`CLEAR_WORD: position ${position} out of bounds`);
+      return state;
+    }
+    const newWords = [...state.words] as (string | null)[];
+    newWords[position] = null;
+    return { ...state, words: newWords, status: 'entering' };
+  }
+
+  if (type === 'CHECK') {
+    const { words } = state;
+    const nullIdx = words.findIndex((w) => w === null);
+    if (nullIdx !== -1) {
+      return {
+        ...state,
+        status: 'invalid',
+      };
+    }
+    const result = validateSeedPhrase(words as string[]);
+    return {
+      ...state,
+      status: result.isValid ? 'valid' : 'invalid',
+    };
+  }
+
+  console.warn(`Unexpected event ${type} in import-flow`);
+  return state;
+}

package/src/headless/index.ts

@@ -0,0 +1,53 @@
+export { identityFlowReducer, initialIdentityFlowState } from './identity-flow.js';
+export type {
+  IdentityFlowState,
+  IdentityFlowStatus,
+  IdentityFlowEvent,
+} from './types.js';
+export {
+  buildVerificationGrid,
+  isGridSelectionCorrect,
+  shuffleWithSeed,
+} from './seed-words.js';
+export {
+  displayFlowReducer,
+  initialDisplayState,
+} from './display-flow.js';
+export type {
+  DisplayState,
+  DisplayStatus,
+  DisplayEvent,
+} from './display-flow.js';
+export {
+  verifyFlowReducer,
+  initVerifyState,
+} from './verify-flow.js';
+export type {
+  VerifyState,
+  VerifyStatus,
+  VerifyEvent,
+} from './verify-flow.js';
+export {
+  importFlowReducer,
+  initImportState,
+} from './import-flow.js';
+export type {
+  ImportState,
+  ImportStatus,
+  ImportEvent,
+} from './import-flow.js';
+export {
+  IdentityContextIDBStorage,
+} from './identity-context-storage.js';
+export type {
+  IdentityContextData,
+  IdentityContextStorage,
+} from './identity-context-types.js';
+export {
+  deriveCacheKey,
+  encryptContext,
+  decryptContext,
+} from './context-crypto.js';
+export type {
+  ContextEnvelope,
+} from './context-crypto.js';

package/src/headless/seed-words.ts

@@ -0,0 +1,75 @@
+// packages/react/src/headless/seed-words.ts
+
+export function shuffleWithSeed<T>(items: T[], seed: number): T[] {
+  const arr = [...items];
+  let currentSeed = seed;
+  function nextRand(): number {
+    currentSeed = (currentSeed * 1664525 + 1013904223) >>> 0;
+    return currentSeed;
+  }
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = nextRand() % (i + 1);
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+  }
+  return arr;
+}
+
+export function buildVerificationGrid(
+  realWords: string[],
+  gridSize: number,
+  randomSeed: number,
+  allWords: readonly string[]
+): { words: string[]; correctIndices: number[] } {
+  if (gridSize < realWords.length) {
+    throw new Error(
+      `gridSize (${gridSize}) must be >= realWords.length (${realWords.length})`
+    );
+  }
+
+  const shuffled = shuffleWithSeed(realWords, randomSeed);
+  const realSet = new Set(realWords);
+  const available = allWords.filter((w) => !realSet.has(w));
+  const shuffledDecoys = shuffleWithSeed(available, randomSeed + 1);
+
+  const needed = gridSize - realWords.length;
+  const decoys = shuffledDecoys.slice(0, needed);
+
+  const words = [...shuffled, ...decoys];
+  if (words.length !== gridSize) {
+    throw new Error(
+      `Cannot fill grid: wordlist too small (got ${words.length}, need ${gridSize})`
+    );
+  }
+
+  // Map each word occurrence to a DISTINCT grid position, so
+  // repeated words in the phrase get their own cells.
+  const positions = new Map<string, number[]>();
+  words.forEach((w, i) => {
+    const list = positions.get(w);
+    if (list) list.push(i);
+    else positions.set(w, [i]);
+  });
+
+  const correctIndices = realWords.map((w) => {
+    const list = positions.get(w);
+    if (!list || list.length === 0) {
+      throw new Error(`Internal error: word "${w}" missing from grid`);
+    }
+    return list.shift() as number;
+  });
+
+  return { words, correctIndices };
+}
+
+/**
+ * Selection is compared IN ORDER: selected[i] must equal
+ * correctIndices[i]. The i-th click must be the i-th word of the
+ * phrase. Repeated phrase words map to distinct grid cells.
+ */
+export function isGridSelectionCorrect(
+  grid: { words: string[]; correctIndices: number[] },
+  selected: number[]
+): boolean {
+  if (selected.length !== grid.correctIndices.length) return false;
+  return selected.every((v, i) => v === grid.correctIndices[i]);
+}

package/src/headless/types.ts

@@ -0,0 +1,21 @@
+export type IdentityFlowStatus =
+  | 'idle'
+  | 'seed-generated'
+  | 'verified'
+  | 'ready'
+  | 'imported'
+  | 'error';
+
+export interface IdentityFlowState {
+  status: IdentityFlowStatus;
+  seedWords: string[] | null;
+  identitySeed: Uint8Array | null;
+  error: string | null;
+}
+
+export type IdentityFlowEvent =
+  | { type: 'GENERATE'; words: string[]; seed: Uint8Array }
+  | { type: 'IMPORT'; seed: Uint8Array }
+  | { type: 'CONFIRM_WORDS' }
+  | { type: 'RESET' }
+  | { type: 'FAIL'; message: string };

package/src/headless/verify-flow.ts

@@ -0,0 +1,112 @@
+// packages/react/src/headless/verify-flow.ts
+import {
+  buildVerificationGrid,
+  isGridSelectionCorrect,
+} from './seed-words.js';
+
+export type VerifyStatus = 'collecting' | 'correct' | 'incorrect';
+
+export interface VerifyState {
+  status: VerifyStatus;
+  grid: { words: string[]; correctIndices: number[] };
+  selected: number[];
+  attempts: number;
+}
+
+export type VerifyEvent =
+  | { type: 'SELECT'; index: number }
+  | { type: 'DESELECT'; index: number }
+  | { type: 'CHECK' }
+  | {
+      type: 'RESET';
+      realWords: string[];
+      gridSize: number;
+      randomSeed: number;
+      allWords: readonly string[];
+    };
+
+export function initVerifyState(
+  realWords: string[],
+  gridSize: number,
+  randomSeed: number,
+  allWords: readonly string[]
+): VerifyState {
+  const grid = buildVerificationGrid(realWords, gridSize, randomSeed, allWords);
+  return {
+    status: 'collecting',
+    grid,
+    selected: [],
+    attempts: 0,
+  };
+}
+
+export function verifyFlowReducer(
+  state: VerifyState,
+  event: VerifyEvent
+): VerifyState {
+  const { type } = event;
+
+  if (type === 'RESET') {
+    return initVerifyState(
+      event.realWords,
+      event.gridSize,
+      event.randomSeed,
+      event.allWords
+    );
+  }
+
+  // Terminal states: only RESET allowed
+  if (state.status === 'correct' || state.status === 'incorrect') {
+    console.warn(
+      `Cannot ${type} in ${state.status} state — use RESET to retry`
+    );
+    return state;
+  }
+
+  // collecting state
+  if (type === 'SELECT') {
+    const { index } = event;
+    const { grid, selected } = state;
+    if (selected.includes(index)) {
+      console.warn(`Index ${index} already selected — use DESELECT`);
+      return state;
+    }
+    if (index < 0 || index >= grid.words.length) {
+      console.warn(`Index ${index} out of grid bounds`);
+      return state;
+    }
+    return { ...state, selected: [...selected, index] };
+  }
+
+  if (type === 'DESELECT') {
+    const { index } = event;
+    const idx = state.selected.indexOf(index);
+    if (idx === -1) {
+      console.warn(`Index ${index} not selected`);
+      return state;
+    }
+    return {
+      ...state,
+      selected: state.selected.filter((_, i) => i !== idx),
+    };
+  }
+
+  if (type === 'CHECK') {
+    const { grid, selected, attempts } = state;
+    if (selected.length !== grid.correctIndices.length) {
+      console.warn(
+        `Cannot check: selected ${selected.length}, need ${grid.correctIndices.length}`
+      );
+      return state;
+    }
+    const correct = isGridSelectionCorrect(grid, selected);
+    return {
+      ...state,
+      status: correct ? 'correct' : 'incorrect',
+      attempts: attempts + 1,
+    };
+  }
+
+  console.warn(`Unexpected event ${type} in collecting`);
+  return state;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './react/index.js';
+export * as headless from './headless/index.js';