Hooks Reference

Organized by intent, not alphabetically.

Identity & Session

Handle registration, login, and logout without leaking keys or managing crypto state manually.

useIdentity()

Returns authentication state and actions.

const {
  isAuthenticated,  // boolean
  isLoading,        // boolean
  did,              // string | null (decentralized identifier)
  register,         // (password: string) => Promise<{ recoveryCode: string }>
  login,            // (password: string) => Promise<void>
  logout,           // () => void
  recover,          // (code: string, newPassword: string) => Promise<void>
} = useIdentity();

Behavior:

• register creates a new identity and returns a recovery code. Store it offline.
• login derives the master key and unlocks the vault.
• logout zeroizes keys from WASM memory and locks the vault.
• State updates trigger re-renders automatically.

---

Encrypted State

Secrets behave like local state, but are encrypted at rest and unavailable when the vault is locked.

useSecret(key)

Read and write a single encrypted value.

const [value, setValue, { isLoading, error }] = useSecret("stripe_key");

Parameters:

• key — unique identifier for the secret (string)

Returns:

• value — decrypted value (string | null)
• setValue — function to encrypt and persist a new value
• isLoading — true while loading or saving
• error — Error object if operation failed

Behavior:

• Auto-loads when vault unlocks
• Returns null when vault is locked
• setValue(null) deletes the secret

useSecrets()

Access all secrets as a reactive map.

const { secrets, set, remove, isLoading } = useSecrets();

// secrets: Record<string, string>
// set: (key: string, value: string) => Promise<void>
// remove: (key: string) => Promise<void>

Use for listing or batch operations.

---

Vault Lifecycle

useVault()

Low-level access to the Vault instance. Use only when hooks don’t cover your use case.

const { vault, isReady, error } = useVault();

// vault: IVault | null
// isReady: boolean (WASM loaded and initialized)
// error: Error | null

Warning: Direct vault access bypasses React’s reactivity. Prefer useSecret for most cases.

useVaultStatus()

Read-only vault state for UI indicators.

const { isReady, isLocked, isLoading } = useVaultStatus();

Useful for showing loading spinners or lock icons without triggering re-renders on secret changes.

---

Common Patterns

Conditional rendering based on auth

function App() {
  const { isAuthenticated, isLoading } = useIdentity();

  if (isLoading) return <Spinner />;
  if (!isAuthenticated) return <LoginForm />;

  return <Dashboard />;
}

Storing API keys

function ApiKeyInput() {
  const [key, setKey, { isLoading }] = useSecret("openai_key");

  return (
    <input
      value={key ?? ""}
      onChange={(e) => setKey(e.target.value)}
      disabled={isLoading}
      placeholder="sk-..."
    />
  );
}

Auto-lock on inactivity

function AutoLock({ timeout = 300000 }) {
  const { logout, isAuthenticated } = useIdentity();

  useEffect(() => {
    if (!isAuthenticated) return;

    let timer: number;
    const reset = () => {
      clearTimeout(timer);
      timer = setTimeout(logout, timeout);
    };

    window.addEventListener("mousemove", reset);
    window.addEventListener("keypress", reset);
    reset();

    return () => {
      clearTimeout(timer);
      window.removeEventListener("mousemove", reset);
      window.removeEventListener("keypress", reset);
    };
  }, [isAuthenticated, logout, timeout]);

  return null;
}

---

Failure Modes

Wrong password

login() throws an error. The vault remains locked. No data is corrupted.

try {
  await login(password);
} catch (e) {
  // e.message: "Invalid passphrase"
}

Corrupt storage

If IndexedDB data is corrupted, useSecret returns an error. Recovery requires the recovery code.

WASM load failure

If the WASM module fails to load, useVault() returns error and isReady: false. Check browser console for details. Common causes: missing COEP/COOP headers, blocked by CSP.