@me2em/react 0.1.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,367 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Identity, SeedStrength, Handle, SubHandle, Session } from '@me2em/core';
+
+declare function Me2emProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+interface Me2emContextValue {
+    identity: Identity | null;
+    hasIdentity: boolean;
+    activateIdentity: (seed: Uint8Array) => Promise<boolean>;
+    clearIdentity: () => void;
+}
+declare function useMe2emContext(): Me2emContextValue;
+
+type IdentityFlowStatus = 'idle' | 'seed-generated' | 'verified' | 'ready' | 'imported' | 'error';
+interface IdentityFlowState {
+    status: IdentityFlowStatus;
+    seedWords: string[] | null;
+    identitySeed: Uint8Array | null;
+    error: string | null;
+}
+type IdentityFlowEvent = {
+    type: 'GENERATE';
+    words: string[];
+    seed: Uint8Array;
+} | {
+    type: 'IMPORT';
+    seed: Uint8Array;
+} | {
+    type: 'CONFIRM_WORDS';
+} | {
+    type: 'RESET';
+} | {
+    type: 'FAIL';
+    message: string;
+};
+
+interface UseCreateIdentityResult {
+    status: IdentityFlowStatus;
+    seedWords: string[] | null;
+    identity: Identity | null;
+    error: string | null;
+    generate: (opts?: {
+        strength?: SeedStrength;
+    }) => void;
+    confirmWords: () => Promise<void>;
+    reset: () => void;
+    fail: (message: string) => void;
+}
+declare function useCreateIdentity(): UseCreateIdentityResult;
+
+interface UseImportSeedResult {
+    status: IdentityFlowStatus;
+    identity: Identity | null;
+    error: string | null;
+    importWords: (words: string[], passphrase?: string) => Promise<void>;
+    reset: () => void;
+}
+declare function useImportSeed(): UseImportSeedResult;
+
+declare function useHandle(name: string): Handle | null;
+
+declare function useSubHandle(handleName: string, subName: string): SubHandle | null;
+
+interface SeedPhraseDisplayProps {
+    words: string[];
+    onDismiss?: () => void;
+    onCopyAllowed?: () => void;
+}
+declare function SeedPhraseDisplay({ words, onDismiss, onCopyAllowed, }: SeedPhraseDisplayProps): react.JSX.Element;
+
+interface SeedPhraseVerifyProps {
+    realWords: string[];
+    gridSize?: number;
+    wordlist?: readonly string[];
+    onVerified: () => void;
+    onFailed?: (attempts: number) => void;
+}
+declare function SeedPhraseVerify({ realWords, gridSize, wordlist: propWordlist, onVerified, onFailed, }: SeedPhraseVerifyProps): react.JSX.Element;
+
+interface SeedPhraseImportProps {
+    expectedCount?: 12 | 24;
+    wordlist?: readonly string[];
+    onImported: (words: string[]) => void;
+}
+declare function SeedPhraseImport({ expectedCount: propCount, wordlist: propWordlist, onImported, }: SeedPhraseImportProps): react.JSX.Element;
+
+interface PassphraseInputProps {
+    onPassphraseChange: (p: string) => void;
+    showWarnings?: boolean;
+}
+declare function PassphraseInput({ onPassphraseChange, showWarnings, }: PassphraseInputProps): react.JSX.Element;
+
+interface IdentityContextData {
+    /** base64url identity public key — владелец кэша. */
+    identityId: string;
+    /** Реестр Handle-контекстов этой Identity. */
+    handles: Array<{
+        name: string;
+        subHandles?: string[];
+        meta?: Record<string, unknown>;
+    }>;
+    savedAt: number;
+}
+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>;
+}
+
+interface UseIdentityContextResult {
+    context: IdentityContextData | null;
+    isLoaded: boolean;
+    error: string | null;
+    save: (data: IdentityContextData) => Promise<void>;
+    clear: () => Promise<void>;
+    /** Reload the cache for the current identity (after sync). */
+    refresh: () => Promise<void>;
+}
+declare function useIdentityContext(storage: IdentityContextStorage): UseIdentityContextResult;
+
+/**
+ * Options for useSession, memoized via deep comparison of
+ * `handle` and `options` refs on each render.
+ *
+ * @category Types
+ */
+interface UseSessionOptions {
+    /** Intended audience (recipient) of this session. */
+    audience: string;
+    /** Permission scopes granted in this session. */
+    scopes: string[];
+    /** Time-to-live in seconds. */
+    ttl: number;
+}
+/**
+ * Result of the useSession hook.
+ *
+ * @category Types
+ */
+interface UseSessionResult {
+    /** The active session, or null if no handle or session creation failed. */
+    session: Session | null;
+    /** Whether the session (or its absence) has been determined. */
+    isLoaded: boolean;
+    /** Error string if session creation or renewal failed. */
+    error: string | null;
+    /** Whether the current session has expired. */
+    isExpired: boolean;
+    /** Manually renew the session (creates a new one with a fresh jti). */
+    renew: () => void;
+}
+/**
+ * Hook that creates and manages a signed session token for a Handle.
+ *
+ * When `handle` is provided, creates a Session with the given options.
+ * Supports auto-renewal: when `autoRenew` is true (default), a timer
+ * fires at half the session TTL to create a fresh session with a new
+ * jti (the previous token remains valid until its own expiry, but the
+ * lineage identity is preserved through `handle`).
+ *
+ * On unmount, all timers are cleaned up to prevent state updates after
+ * the component is gone.
+ *
+ * Dependencies: `[handle, renew]` — the options object is read through
+ * a ref, so passing a fresh object literal on every render does NOT
+ * re-trigger session creation. Only changes to `handle` (or to the
+ * renewal function identity, which follows `handle`) do.
+ *
+ * @param handle - The Handle to sign the session, or null.
+ * @param options - Session options (audience, scopes, ttl).
+ * @param autoRenew - Whether to auto-renew at half-life (default: true).
+ * @returns Session state with manual `renew` control.
+ *
+ * @example
+ * ```ts
+ * const handle = useHandle('my-handle');
+ * const { session, isExpired, renew } = useSession(handle, {
+ *   audience: 'app.example.com',
+ *   scopes: ['read', 'write'],
+ *   ttl: 3600,
+ * });
+ * ```
+ */
+declare function useSession(handle: Handle | null, options: UseSessionOptions, autoRenew?: boolean): UseSessionResult;
+
+declare const initialIdentityFlowState: IdentityFlowState;
+declare function identityFlowReducer(state: IdentityFlowState, event: IdentityFlowEvent): IdentityFlowState;
+
+declare function shuffleWithSeed<T>(items: T[], seed: number): T[];
+declare function buildVerificationGrid(realWords: string[], gridSize: number, randomSeed: number, allWords: readonly string[]): {
+    words: string[];
+    correctIndices: number[];
+};
+/**
+ * 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.
+ */
+declare function isGridSelectionCorrect(grid: {
+    words: string[];
+    correctIndices: number[];
+}, selected: number[]): boolean;
+
+type DisplayStatus = 'hidden' | 'revealed' | 'copied' | 'dismissed';
+interface DisplayState {
+    status: DisplayStatus;
+    copyCount: number;
+    revealedAt: number | null;
+}
+type DisplayEvent = {
+    type: 'REVEAL';
+    at: number;
+} | {
+    type: 'COPY';
+    at: number;
+} | {
+    type: 'DISMISS';
+} | {
+    type: 'RESET';
+};
+declare const initialDisplayState: DisplayState;
+declare function displayFlowReducer(state: DisplayState, event: DisplayEvent): DisplayState;
+
+type VerifyStatus = 'collecting' | 'correct' | 'incorrect';
+interface VerifyState {
+    status: VerifyStatus;
+    grid: {
+        words: string[];
+        correctIndices: number[];
+    };
+    selected: number[];
+    attempts: number;
+}
+type VerifyEvent = {
+    type: 'SELECT';
+    index: number;
+} | {
+    type: 'DESELECT';
+    index: number;
+} | {
+    type: 'CHECK';
+} | {
+    type: 'RESET';
+    realWords: string[];
+    gridSize: number;
+    randomSeed: number;
+    allWords: readonly string[];
+};
+declare function initVerifyState(realWords: string[], gridSize: number, randomSeed: number, allWords: readonly string[]): VerifyState;
+declare function verifyFlowReducer(state: VerifyState, event: VerifyEvent): VerifyState;
+
+type ImportStatus = 'entering' | 'valid' | 'invalid';
+interface ImportState {
+    status: ImportStatus;
+    words: (string | null)[];
+    expectedCount: 12 | 24;
+}
+type ImportEvent = {
+    type: 'INIT';
+    expectedCount: 12 | 24;
+} | {
+    type: 'SET_WORD';
+    position: number;
+    word: string;
+} | {
+    type: 'CLEAR_WORD';
+    position: number;
+} | {
+    type: 'CHECK';
+} | {
+    type: 'RESET';
+};
+declare function initImportState(expectedCount: 12 | 24): ImportState;
+declare function importFlowReducer(state: ImportState, event: ImportEvent): ImportState;
+
+declare class IdentityContextIDBStorage implements IdentityContextStorage {
+    private db;
+    private currentIdentityId;
+    private cacheKey;
+    private getDb;
+    open(identityId: string): Promise<void>;
+    openAndLoad(identityId: string): Promise<IdentityContextData | null>;
+    save(data: IdentityContextData): Promise<void>;
+    load(): Promise<IdentityContextData | null>;
+    clear(): Promise<void>;
+    close(): Promise<void>;
+    setCacheKey(key: CryptoKey): void;
+    getCacheKey(): CryptoKey | null;
+    persistCacheKey(): Promise<void>;
+    loadPersistedKey(): Promise<CryptoKey | null>;
+}
+
+interface ContextEnvelope {
+    v: 1;
+    /** fresh HKDF salt этого логина (b64). Нужен только при
+     * первичной деривации; persisted CryptoKey переживает
+     * перезапуск без него. */
+    salt: string;
+    iv: string;
+    ct: string;
+}
+/**
+ * Derives a fresh, per-login cache key from login-time secret
+ * material and wraps it as a NON-EXTRACTABLE persisted CryptoKey.
+ * 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).
+ * @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.
+ */
+declare function deriveCacheKey(loginMaterial: Uint8Array, salt: Uint8Array): Promise<CryptoKey>;
+declare function encryptContext(key: CryptoKey, data: IdentityContextData): Promise<ContextEnvelope>;
+declare function decryptContext(key: CryptoKey, envelope: ContextEnvelope): Promise<IdentityContextData>;
+
+type index_ContextEnvelope = ContextEnvelope;
+type index_DisplayEvent = DisplayEvent;
+type index_DisplayState = DisplayState;
+type index_DisplayStatus = DisplayStatus;
+type index_IdentityContextData = IdentityContextData;
+type index_IdentityContextIDBStorage = IdentityContextIDBStorage;
+declare const index_IdentityContextIDBStorage: typeof IdentityContextIDBStorage;
+type index_IdentityContextStorage = IdentityContextStorage;
+type index_IdentityFlowEvent = IdentityFlowEvent;
+type index_IdentityFlowState = IdentityFlowState;
+type index_IdentityFlowStatus = IdentityFlowStatus;
+type index_ImportEvent = ImportEvent;
+type index_ImportState = ImportState;
+type index_ImportStatus = ImportStatus;
+type index_VerifyEvent = VerifyEvent;
+type index_VerifyState = VerifyState;
+type index_VerifyStatus = VerifyStatus;
+declare const index_buildVerificationGrid: typeof buildVerificationGrid;
+declare const index_decryptContext: typeof decryptContext;
+declare const index_deriveCacheKey: typeof deriveCacheKey;
+declare const index_displayFlowReducer: typeof displayFlowReducer;
+declare const index_encryptContext: typeof encryptContext;
+declare const index_identityFlowReducer: typeof identityFlowReducer;
+declare const index_importFlowReducer: typeof importFlowReducer;
+declare const index_initImportState: typeof initImportState;
+declare const index_initVerifyState: typeof initVerifyState;
+declare const index_initialDisplayState: typeof initialDisplayState;
+declare const index_initialIdentityFlowState: typeof initialIdentityFlowState;
+declare const index_isGridSelectionCorrect: typeof isGridSelectionCorrect;
+declare const index_shuffleWithSeed: typeof shuffleWithSeed;
+declare const index_verifyFlowReducer: typeof verifyFlowReducer;
+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 };