client.auth

Authentication is exposed through client.auth.zk. See the Authentication guide for usage.

interface AuthUser {
  username: string;
  /** Decimal-string Poseidon commitment — the user's stable id. */
  commitment: string;
}

Methods

register(params)

register(params: {
  username: string;
  password: string;
  email?: string | null;
  login?: boolean; // default: true
}): Promise<AuthUser>

Derives the identity, registers the commitment, and (unless login: false) signs in. Throws if the username is taken.

login(username, password, opts?)

login(username: string, password: string, opts?: { rememberMe?: boolean }): Promise<AuthUser>

Re-derives the identity, proves it against a fresh server challenge, and establishes the session and identity. rememberMe: true requests a longer-lived session. Throws on bad credentials / expired challenge.

restore()

restore(): Promise<AuthUser | null>

Validates a persisted session token (from the sessionStore). Returns the user when valid, or null (clearing a stale token). Does not unlock the identity — call unlock() for encryption/messaging.

unlock(password)

unlock(password: string): Promise<void>

Re-derives the identity for an already-authenticated (restored) session. Verifies the password by matching the derived commitment to the session’s; throws on mismatch.

recover()

recover(): Promise<boolean>

Silently re-mints a session token by re-proving the in-memory identity — no password prompt. Resolves true if it succeeded, false if it can’t (the identity isn’t in memory, e.g. after a reload that kept only the token). The client calls this automatically when a request hits 401; you normally use the client-level recoverSession() + onSessionExpired instead of calling it directly.

logout()

logout(): Promise<void>

Clears the session, identity, and persisted token.

Getters

Getter	Type	Description
client.auth.zk.user	AuthUser | null	Current user (sync).
client.auth.zk.token	string | null	Current session token (sync).
client.auth.zk.identity	ZkIdentity | null	Derived identity, or null when locked.
client.auth.user	AuthUser | null	Convenience alias.