@muhkoo/connect 0.6.0-alpha.1 → 0.6.0-alpha.11

package/dist/connect.d.ts

@@ -1812,6 +1812,16 @@ interface AuthSuccess {
     token: string;
     username: string;
 }
+/** A vault factor record (M1.0). Wrap/iv are base64 AES-GCM; absent for phrase. */
+interface VaultFactor {
+    id: string;
+    type: "password" | "passkey" | "phrase-marker";
+    wrap?: string;
+    iv?: string;
+    params?: Record<string, unknown>;
+    label?: string;
+    createdAt?: number;
+}
 interface AuthClientOptions {
     /** Absolute URL of the accelerator worker (no trailing slash required). */
     baseUrl: string;
@@ -1836,6 +1846,28 @@ declare class AuthClient {
     verify(token: string): Promise<{
         username: string;
     }>;
+    /** Blinded OPRF evaluation — the server-gated half of a password/recovery wrap key. */
+    oprfEvaluate(username: string, blinded: string): Promise<{
+        evaluated: string;
+    }>;
+    /** Read a factor record for `username` (returns an indistinguishable decoy if absent). */
+    vaultRead(username: string, factorType: VaultFactor["type"]): Promise<{
+        factor: VaultFactor | null;
+    }>;
+    /** Add/replace a factor (session-authed; the seed is already wrapped client-side). */
+    vaultPutFactor(token: string, factor: VaultFactor): Promise<{
+        ok: boolean;
+        id: string;
+    }>;
+    /** List the user's factor metadata (no ciphertext). Session-authed. */
+    vaultFactors(token: string): Promise<{
+        factors: VaultFactor[];
+        migrated: boolean;
+    }>;
+    /** Remove a factor by id (can't remove the last one). Session-authed. */
+    vaultDeleteFactor(token: string, id: string): Promise<{
+        deleted: boolean;
+    }>;
     private json;
     private parse;
 }
@@ -1882,6 +1914,23 @@ interface ZkIdentity {
  * devices.
  */
 declare function deriveIdentity(username: string, password: string): Promise<ZkIdentity>;
+/**
+ * Legacy master-seed derivation: `PBKDF2(password, "muhkoo-zk-v1:"||username)`.
+ *
+ * This was the *only* path pre-vault, where the identity descended directly from
+ * the password. It's kept so existing accounts still re-derive their seed (and
+ * the vault can adopt that exact seed on migration, preserving the commitment).
+ * New accounts use a random seed (`vault.randomSeed`) instead, so their identity
+ * is no longer a function of the password.
+ */
+declare function deriveMasterSeedFromPassword(username: string, password: string): Promise<Uint8Array>;
+/**
+ * Derive the (unchanged) ZK identity from a 32-byte **master seed**. The seed is
+ * HKDF-expanded into secret/salt + the P-256 ECDSA & ECDH keypairs exactly as
+ * before — so the resulting commitment is byte-identical for a given seed. The
+ * vault wraps THIS seed under each recovery factor.
+ */
+declare function deriveIdentityFromSeed(seed: Uint8Array): Promise<ZkIdentity>;
 
 /**
  * Poseidon hash wrapper used by the ZK auth flow.
@@ -2083,6 +2132,10 @@ declare function defaultSessionStore(keyPrefix?: string): SessionStore;
 declare class SessionState {
     private session;
     private _identity;
+    /** The 32-byte master seed, in-memory only (never persisted). Held after
+     *  login/register so additional recovery factors (passkey, phrase) can be
+     *  enrolled, and a password can be changed, without re-deriving. */
+    private _seed;
     private readonly store;
     constructor(store?: SessionStore);
     /** True once a token-bearing session exists (regardless of identity). */
@@ -2099,6 +2152,10 @@ declare class SessionState {
     setSession(session: StoredSession): Promise<void>;
     /** Attach derived identity material to the current session. */
     setIdentity(identity: ZkIdentity): void;
+    /** The in-memory master seed (or null when locked / not held). */
+    get seed(): Uint8Array | null;
+    /** Hold the master seed in memory (set on login/register when available). */
+    setSeed(seed: Uint8Array | null): void;
     /** Load a persisted session (used by `restore()`); identity stays null. */
     loadPersisted(): Promise<StoredSession | null>;
     /** Drop all session + identity state and clear persistence. */
@@ -2122,6 +2179,17 @@ declare class SessionState {
  * at-rest encryption and the messaging ratchet without re-deriving.
  */
 
+/**
+ * Thrown when the identity vault can't be reached to unlock the seed — a network
+ * failure, a 5xx, or the per-user rate limit (429). This is distinct from a wrong
+ * password, and is surfaced so `login`/`unlock` do NOT silently fall back to the
+ * legacy password derivation (which, for a vault account, yields a misleading
+ * "commitment mismatch"). Callers should ask the user to retry, not re-enter a
+ * password.
+ */
+declare class VaultUnavailableError extends Error {
+    constructor(cause?: unknown);
+}
 /** What the auth methods resolve to — the stable, non-secret user facts. */
 interface AuthUser {
     username: string;
@@ -2152,17 +2220,26 @@ declare class ZkAuth {
     private readonly deps;
     constructor(deps: ZkAuthDeps);
     /**
-     * Register a new user, then (by default) sign them in. The identity is
-     * derived deterministically from `(username, password)` — the same inputs
-     * reproduce it on any device, so there's no key material to ship around.
+     * Register a new user, then (by default) sign them in.
+     *
+     * M1.0: the identity now descends from a **random master seed** (not the
+     * password), so it's recoverable + the password can be changed. We register
+     * the commitment, sign in with the in-memory identity to get a token, then
+     * enroll the OPRF-gated **password factor** (the seed wrapped under a key the
+     * server can't derive offline). Future logins unlock the seed via that factor.
      */
     register(params: RegisterParams): Promise<AuthUser>;
     /**
-     * Sign in: re-derive the identity, prove knowledge of it against a fresh
-     * server challenge, and trade the proof for a session token. On success
-     * both the session and the identity are stored on the client.
+     * Sign in. M1.0 is **vault-first**: read the password factor and OPRF-unwrap
+     * the master seed → identity. If that fails (a pre-vault account, whose factor
+     * is absent so the server returns a decoy, or a wrong password), fall back to
+     * the legacy password-derived identity. Either way we then prove knowledge of
+     * the identity and trade it for a session token.
      */
     login(username: string, password: string, opts?: LoginOptions): Promise<AuthUser>;
+    /** Enroll the password factor for a legacy (pre-vault) account. Idempotent +
+     *  best-effort; failure just means we retry on the next login. */
+    private migrateLegacyPasswordFactor;
     /**
      * Silently re-authenticate the current user without prompting for a
      * password. Only possible while the client is **unlocked** — i.e. the
@@ -2200,6 +2277,60 @@ declare class ZkAuth {
      * the password by checking the derived commitment matches the session's.
      */
     unlock(password: string): Promise<void>;
+    /**
+     * Generate a 24-word **recovery phrase** that encodes the master seed, and
+     * record a marker in the vault so the UI knows one exists. Show the returned
+     * phrase to the user ONCE — it's never stored server-side (the phrase *is* the
+     * seed). Requires being signed in (the seed must be held in memory).
+     */
+    enrollRecoveryPhrase(): Promise<string>;
+    /**
+     * Recover an account with its recovery phrase (the "forgot password" path).
+     * Decodes the phrase to the master seed → identity → session. After this,
+     * call {@link changePassword} to set a new password. No server lookup needed.
+     */
+    recoverWithPhrase(username: string, mnemonic: string, opts?: LoginOptions): Promise<AuthUser>;
+    /**
+     * Change the password — re-wraps the (unchanged) master seed under the new
+     * password's OPRF-gated key. The identity/commitment never moves. Requires
+     * being signed in (or freshly recovered) so the seed is held.
+     */
+    changePassword(newPassword: string): Promise<void>;
+    /** Whether this browser can use passkeys (WebAuthn) at all. */
+    passkeyAvailable(): boolean;
+    /**
+     * Whether this browser's authenticator can do the **PRF extension** our
+     * passkey factor requires. A browser may support passkeys generally but not
+     * PRF — in which case enrolling one would fail. Resolves `true`/`false`, or
+     * `null` when it can't be determined (no capabilities API). Use this to gate
+     * the passkey UI so users don't hit a dead-end error.
+     */
+    passkeyPrfAvailable(): Promise<boolean | null>;
+    /**
+     * Add a **passkey** recovery factor. Creates a WebAuthn passkey with PRF,
+     * wraps the master seed under its PRF output, and stores the factor. The
+     * passkey (synced via the platform's keychain) then unlocks the account on
+     * any device — no password. Requires being signed in (seed held in memory).
+     */
+    enrollPasskey(opts?: {
+        rpId?: string;
+        rpName?: string;
+        label?: string;
+    }): Promise<void>;
+    /**
+     * Sign in with a passkey (no password). Reads the passkey factor, evaluates
+     * its PRF, unwraps the master seed → identity → session.
+     */
+    loginWithPasskey(username: string, opts?: LoginOptions): Promise<AuthUser>;
+    /** List the user's enrolled login methods (metadata only). Session-authed. */
+    listFactors(): Promise<Array<{
+        id: string;
+        type: string;
+        label?: string;
+        createdAt?: number;
+    }>>;
+    /** Remove a login method by id (can't remove your only one). Session-authed. */
+    removeFactor(id: string): Promise<void>;
     /** Sign out: clears the session, identity, and persisted token. */
     logout(): Promise<void>;
     /** The signed-in user, or `null`. Synchronous read of current state. */
@@ -2213,8 +2344,43 @@ declare class ZkAuth {
     get identity(): ZkIdentity | null;
     /** The current session token, or `null` when signed out. */
     get token(): string | null;
+    /**
+     * The master seed as base64, or `null` when locked. The host app uses this to
+     * wrap app-level data (e.g. chat ratchet keys) to the **seed** instead of the
+     * password — so that data survives password changes and can be unlocked by a
+     * passwordless (passkey) login, both of which recover the same seed.
+     */
+    get seedBase64(): string | null;
     /** Poseidon commitment for an identity — the value the server stores. */
     private commitmentFor;
+    /**
+     * Derive the OPRF-gated wrap key for the password factor: `scrypt(password)`
+     * is blinded, evaluated by the server's secret OPRF key (so it can't be
+     * derived offline), unblinded, then HKDF'd into an AES-GCM key.
+     */
+    private passwordWrapKey;
+    /**
+     * Try to recover the master seed from the password factor.
+     *
+     * Returns `null` only when the vault read SUCCEEDS but the seed can't be
+     * unwrapped — i.e. there's no real factor (a pre-vault/legacy account, whose
+     * read returns a decoy that won't unwrap) or the password is wrong. The caller
+     * then legitimately falls back to the legacy password-derived identity.
+     *
+     * Throws {@link VaultUnavailableError} when the vault itself can't be reached
+     * (network / 5xx / rate-limit) — so a *transient* failure is NOT silently
+     * turned into a legacy fallback (which would surface as "commitment mismatch").
+     */
+    private tryUnlockSeed;
+    /**
+     * Enroll/replace the password factor for `username` — wraps `seed` under the
+     * OPRF-gated key and stores it (needs a session `token`).
+     *
+     * Retries: this is the step that persists the (otherwise in-memory-only)
+     * master seed. If it fails after a fresh registration the account would be
+     * unrecoverable, so we retry a few times before surfacing the error.
+     */
+    private enrollPasswordFactor;
 }
 /** `client.auth` — the auth namespace. Strategies hang off here. */
 declare class AuthNamespace {
@@ -3842,5 +4008,5 @@ declare class KeyringClient implements KeyringTransport {
     fetchMetadata(): Promise<SpaceMetadata | null>;
 }
 
-export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, ejectAgentPrompt, ejectAgentTools, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, shardHash, signMessage, toField, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
-export type { ACL, ACLEntry, AgentConfig, AgentCreateInput, AgentDbToolMode, AgentProvisioned, AgentScopeOpts, AgentSkill, AgentToolsConfig, AgentTrigger, AgentTriggerType, AgentUpdateInput, AgentsNamespaceDeps, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, DehydratedKeypair, DehydratedKeys, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EphemeralEvent, EpochKeyProvider, FileManifest, FileNamespaceDeps, FileStat, FileStorageOptions, FunctionCaps, FunctionConfig, FunctionDeployInput, FunctionScopeOpts, FunctionTrigger, FunctionTriggerType, FunctionTriggers, FunctionUpdateInput, FunctionsNamespaceDeps, Groth16Proof, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, KvNamespaceDeps, LoginOptions, MessageBody, MessageDeletedEvent, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOptions, MessageSubscription, MuhkooAgentMeta, MuhkooAgentToolsConfig, MuhkooAppDescriptor, MuhkooDBAccess, MuhkooDBMeta, MuhkooFunctionMeta, MuhkooMessageEvent, MuhkooSpaceMeta, OAuthProvider, PacketCipher, PacketHeaders, PacketOptions, Participant, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, PublicKeyJWK, RatchetState, ReceiveResult, RegisterParams, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardClientOptions, SharedSpaceClientOptions, SnarkProof, SpaceChannelLike, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, StorageChangeEvent, StoredSession, Subscription, UserIdentity, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload, WriteFileInput, WriteFileOptions, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };
+export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, VaultUnavailableError, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, shardHash, signMessage, toField, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
+export type { ACL, ACLEntry, AgentConfig, AgentCreateInput, AgentDbToolMode, AgentProvisioned, AgentScopeOpts, AgentSkill, AgentToolsConfig, AgentTrigger, AgentTriggerType, AgentUpdateInput, AgentsNamespaceDeps, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, DehydratedKeypair, DehydratedKeys, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EphemeralEvent, EpochKeyProvider, FileManifest, FileNamespaceDeps, FileStat, FileStorageOptions, FunctionCaps, FunctionConfig, FunctionDeployInput, FunctionScopeOpts, FunctionTrigger, FunctionTriggerType, FunctionTriggers, FunctionUpdateInput, FunctionsNamespaceDeps, Groth16Proof, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, KvNamespaceDeps, LoginOptions, MessageBody, MessageDeletedEvent, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOptions, MessageSubscription, MuhkooAgentMeta, MuhkooAgentToolsConfig, MuhkooAppDescriptor, MuhkooDBAccess, MuhkooDBMeta, MuhkooFunctionMeta, MuhkooMessageEvent, MuhkooSpaceMeta, OAuthProvider, PacketCipher, PacketHeaders, PacketOptions, Participant, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, PublicKeyJWK, RatchetState, ReceiveResult, RegisterParams, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardClientOptions, SharedSpaceClientOptions, SnarkProof, SpaceChannelLike, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, StorageChangeEvent, StoredSession, Subscription, UserIdentity, VaultFactor, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload, WriteFileInput, WriteFileOptions, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };