Authentication

All auth lives under client.auth.zk. The identity is derived on the device from a master seed — which the password (or another factor) unlocks from a per-user vault — and proven with a zero-knowledge proof. See Identity & app keys for the model.

Register

const user = await client.auth.zk.register({
  username: "ada",
  password: "correct horse battery staple",
  email: "ada@example.com", // optional
});

By default register also signs the user in (returns { username, commitment } and establishes a session). Pass login: false to register without signing in. It throws if the username is taken.

Log in

const user = await client.auth.zk.login("ada", "correct horse battery staple");
// { username: "ada", commitment: "1481…" }

On success the client holds both the session token and the derived identity, so storage and messaging work immediately.

await client.auth.zk.login("ada", pw, { rememberMe: true }); // longer-lived session

Restore a session on reload

With a persisted sessionStore, call restore() on boot. It validates the stored token with the server and returns the user, or null (clearing a stale token):

const user = await client.auth.zk.restore();
if (user) {
  // Authenticated — token-gated calls (most of storage) work.
}

Restored ≠ unlocked

restore() re-establishes the token but not the identity (it has no password). Token-authorized calls work; decrypting storage or sending E2E messages needs the identity. Re-derive it without a full re-login:

await client.auth.zk.unlock("correct horse battery staple");

unlock verifies the password by checking the derived commitment matches the session’s, then enables encryption + messaging.

Boot in one call: resume()

resume() does restore() and, when the account has a passkey that works on this origin, also unlocks the identity with it. Call it once on app start:

const { user, unlocked } = await client.auth.zk.resume();
if (user && !unlocked) {
  // Session restored, identity locked — ask for the password, then unlock().
}

Current user & sign out

client.user;             // { username, commitment } | null  (sync)
client.isAuthenticated;  // boolean (sync)

await client.auth.zk.logout(); // clears session + identity + persisted token

Multi-device

Signing in on a second device unwraps the same master seed from the vault, so it reproduces the same identity and commitment — the user transparently sees the same data. There’s no key export/import step.

Add a passkey

Once signed in, enroll a WebAuthn passkey so the user can sign in without a password. The passkey wraps the same master seed that backs the identity, so the commitment never moves.

if (client.auth.zk.passkeyAvailable() && (await client.auth.zk.passkeyPrfAvailable())) {
  await client.auth.zk.enrollPasskey({ label: "MacBook Touch ID" });
}

Gate the UI on PRF support

A browser can save passkeys yet not expose the PRF extension this requires. Always gate the passkey option on passkeyPrfAvailable() — it returns true, false, or null when it can’t be determined. Treat anything non-true as “hide the passkey option” and fall back to password.

Sign in with a passkey

Passwordless sign-in. The authenticator unwraps the seed, re-deriving the same identity as a password login — storage and messaging work immediately.

const user = await client.auth.zk.loginWithPasskey("ada", { rememberMe: true });
// { username: "ada", commitment: "1481…" }

Losing a passkey isn't losing the account

A passkey only wraps the seed; it isn’t the seed. If the user loses the authenticator device, they sign in with any other factor they still hold — password, recovery phrase, recovery email, or Google — and then enroll a new passkey. Encourage users to keep at least one device-independent factor (a recovery phrase or email) so a lost device is never a lockout.

Recovery phrase

Enroll a 24-word BIP39 recovery phrase as a “forgot password” fallback. The phrase is the seed — nothing is stored server-side — so show it once and let the user write it down.

const mnemonic = await client.auth.zk.enrollRecoveryPhrase();
// "vivid spider ... (24 words)" — display once, never persist

Regenerating just shows it again

The phrase is deterministic from the seed, so it’s the same 24 words every time. “Regenerate” simply re-displays them — it is not destructive and does not rotate anything.

To recover, the user enters their phrase. This signs them in; immediately have them set a new password:

const user = await client.auth.zk.recoverWithPhrase("ada", mnemonic);
await client.auth.zk.changePassword("a fresh strong password");

Email & Google factors

Email and Google are verification-gated factors: unlike a password or passkey, they carry no user-held secret. The wrapped seed is released, by keys Muhkoo holds, only after the user proves control of the channel (an emailed one-time code, or a verified Google ID token). They’re the mainstream “I have my email / my Google account, get me back in” recovery paths — and the same machinery powers “Sign in with Google”.

Disclose the custody trade-off

Gated factors trade custody for recoverability. Muhkoo operates the key services that protect them, so for any account with an email or Google factor, Muhkoo could technically recover the account’s seed — and with it everything encrypted under it. Password, passkey, recovery phrase and paired browsers and machines (device factors) remain fully non-custodial: Muhkoo can’t unwrap those copies (though a weak password can still be guessed offline by someone holding the OPRF key, so ask for a strong one).

The hosted sign-in (auth.muhkoo.dev) shows users this note. If your app has its own enroll UI, show equivalent disclosure, for example:

Convenient, but less secure than a password, passkey or recovery phrase. Muhkoo holds the keys that protect this method, so we could technically recover your account. Learn more

Enrolling an email sends a one-time code, then a confirm continuation finishes:

const { confirm } = await client.auth.zk.enrollEmailFactor("me@example.com");
await confirm(codeFromInbox); // signed-in only

Recovering with email is the “forgot password” path — it sends a code to the stored address and signs the user in; follow with a new password:

const { confirm } = await client.auth.zk.recoverWithEmail("ada");
const user = await confirm(codeFromInbox);
await client.auth.zk.changePassword("a fresh strong password");

Google works the same way. Obtain a fresh ID token via Google Identity Services (the SDK never renders Google UI), then link, sign in, or register passwordless:

await client.auth.zk.enrollGoogleFactor(idToken);              // link (signed-in)
await client.auth.zk.loginWithGoogle("ada", idToken);          // sign in / recover
await client.auth.zk.registerWithGoogle("ada", idToken);       // new passwordless account

Most apps should use hosted auth instead

The factor APIs above are for apps that build their own auth UI. Most apps should use hosted authentication — auth.muhkoo.dev ships every factor (email, Google, passkeys, phrase) and its enroll/recover UX for you, including the Google OAuth setup, so you never wire these calls up directly.

Change your password

The password is a factor that wraps the seed — not the source of keys. Changing it re-wraps the unchanged seed, so the identity and commitment never move and no data needs re-encrypting.

await client.auth.zk.changePassword("a fresh strong password");

Wrap app data to the seed, not the password

For per-user app data (e.g. chat keys), wrap it under the master seed, not the password, so it survives password changes and unlocks under passwordless passkey login:

const seed = client.auth.zk.seedBase64; // string | null (null when locked)
if (seed) {
  // derive an app key from `seed` and encrypt your per-user data with it
}

Manage login methods

List the user’s enrolled factors (metadata only) and remove ones they no longer want:

const factors = await client.auth.zk.listFactors();
// [{ id, type: "password" | "passkey" | "phrase-marker" | "email" | "google" | "device",
//    label?, createdAt?, masked?, rpId? }, …]  // masked: "m•••@gmail.com" for email/google

await client.auth.zk.removeFactor(factors[0].id);

device entries are remembered browsers and paired machines (see Staying signed in). Removing one takes effect immediately — that browser or machine holds only a key to a blob the vault stores, so withdrawing the blob withdraws the access.

Caution

You can’t remove the last remaining factor — the user must always keep at least one way to sign in. removeFactor throws if you try.

When the vault is unreachable

login and unlock read the wrapped seed from the per-user vault. If the vault can’t be reached (network blip, 5xx, rate-limit) they throw VaultUnavailableError — distinct from a wrong password. Surface “try again” rather than asking the user to re-enter their password:

import { VaultUnavailableError } from "@muhkoo/connect";

try {
  await client.auth.zk.login("ada", pw);
} catch (err) {
  if (err instanceof VaultUnavailableError) {
    // Transient — tell the user to retry, don't blame the password.
  }
}

Legacy accounts migrate automatically

Pre-vault accounts are migrated to the vault transparently on their first vault-aware login/unlock — the commitment is preserved, no action needed.

A vault that refuses the OPRF protocol this SDK speaks throws VaultProtocolMismatchError instead — that one never resolves by retrying; the app (or server) needs updating. Passkey sign-in throws PasskeyOriginError when the account’s passkey belongs to another origin; fall back to another factor.

Handling errors

Login throws on failure; the message tells you what to surface:

try {
  await client.auth.zk.login(username, password);
} catch (err) {
  const msg = (err as Error).message;
  if (/commitment mismatch|incorrect password/.test(msg)) {
    // Wrong password — or a legacy/incompatible account.
  } else if (/User not found/.test(msg)) {
    // No account with that username.
  } else if (/challenge/i.test(msg)) {
    // Auth challenge expired/replayed — just retry.
  }
}

See client.auth reference for the full method list.

Hosted authentication

Instead of embedding the login UI and the proving circuits (~6 MiB) in your app, redirect to the Muhkoo-hosted sign-in page at auth.muhkoo.dev. It owns registration, sign-in, recovery, and every factor (password, passkey, email, Google) — then calls your app back with a session and the master seed.

This is the simplest path for most apps, and it means “Sign in with Google” works with no per-app OAuth origin setup — Google only ever sees one origin. Embedded zero-knowledge auth (client.auth.zk, above) stays available when you want the login UX fully in-app.

Flow

1. The user clicks “Continue with Muhkoo” in your app.
2. client.auth.hosted.login(...) redirects to auth.muhkoo.dev/authorize with PKCE + a CSRF state.
3. The user signs in / registers / recovers on the hosted page.
4. The hosted page redirects back to your redirectUri with a one-time code (and the sealed-seed key in the URL fragment).
5. client.auth.hosted.handleCallback() exchanges the code, unseals the seed, establishes the session, and scrubs the URL.

Setup

Register your callback URL once in the developer portal (App Detail → Hosted sign-in) — exact match, https only (localhost may use http), no wildcards. Copy your app id.

// Start sign-in (e.g. on a button click):
await client.auth.hosted.login({
  appId: "<your-app-id>",
  redirectUri: "https://yourapp.com/auth/callback",
});

// On your callback route:
if (client.auth.hosted.isCallback()) {
  const { username, commitment, returnTo } = await client.auth.hosted.handleCallback();
  // session + identity established — same as embedded auth from here on
}

To land the user back where they started, pass a same-origin path as returnTo to login() (returnTo: "/settings"); handleCallback() hands it back. Anything that isn’t a same-origin path (starting with /, not //) is refused.

authBaseUrl on the Client overrides the hosted origin (default https://auth.muhkoo.dev; set https://auth.staging.muhkoo.dev for staging).

Sealed-seed handoff

The master seed can’t be put on the wire server-readable, so the hosted page seals it under a one-time key carried only in the URL fragment (which never reaches a server) and hands back a single-use code. Your app exchanges the code (PKCE) and decrypts the seed with the fragment key, then strips it. It’s trust-equivalent to deriving the key in your app — only the credential entry moved to the Muhkoo origin.

Identity vs. session. A restored session and an unlocked identity differ. handleCallback() establishes both; after a page reload the session restores but the seed isn’t persisted, so gate “signed in” on client.auth.zk.identity and prompt a one-tap re-sign-in when it’s missing.

See client.auth reference for client.auth.hosted.

Staying signed in

The master seed is memory-only by design: nothing writes it to disk. The cost is that a fresh page load has nothing to restore, so without help every reload, every restored tab, and every link from one app to another means typing the password again. Two apps sharing a registrable domain doesn’t help either — localStorage is per-origin, and the seed isn’t in it anyway.

The hosted page solves that on its own origin. Sign-in offers “Keep me signed in on this browser” — opt-in, unchecked by default, because a durable credential should be something the user chose. Ticking it enrolls a vault device factor: a random key is generated in the browser, the master seed is wrapped under it, and only the ciphertext goes to the vault. The key stays on auth.muhkoo.dev, where no app can read it.

Something durable does now sit on that browser, and that is the trade being made deliberately. What sits there is a key that is useless without the vault’s half, revocable from anywhere, and dropped after 30 days — none of which a stored seed could ever be, since nothing can reach out and un-store a secret already on a disk.

Nothing to adopt

Any app already using hosted auth has it. A user who ticked the box on one Muhkoo sign-in arrives at your /authorize redirect already signed in — no SDK upgrade, no option to pass, no callback change. What you do need to handle is sign-out, below.

What the user sees on that second visit depends on who is asking:

Redirect target	What happens
A Muhkoo-owned surface (the portal, the IDE)	Silent hand-off — the page completes and redirects with nothing shown.
Your app	A “Continue as ada?” screen: no password, but a deliberate click, plus a “Use a different account” escape.

Being remembered must never mean that any app the user has registered can take the seed unannounced, which is what that confirmation buys. The server decides which category a redirect URI falls in (GET /api/auth/first-party), and the decision is UX only — the grant endpoint validates redirect URIs independently, so a wrong answer costs a click, never a boundary.

This is a different thing from rememberMe on login(), which asks for a longer-lived session token. A session token can’t decrypt anything; a device pairing restores the seed as well, which is why it can stand in for signing in.

Sign-out has to be able to say so

Single sign-on means the hosted page still knows the user after your app has signed them out locally. Pass prompt: "login" to ask for credentials anyway:

await client.auth.zk.logout(); // clears this app's session + identity

// …later, when the user clicks "Sign in" again:
await client.auth.hosted.login({
  appId: "<your-app-id>",
  redirectUri: "https://yourapp.com/auth/callback",
  prompt: "login", // don't resume the remembered pairing
});

Without it, the click right after a sign-out resumes the remembered browser and lands the same user straight back in your app — to them, the sign-out looks like it did nothing. Use it for “sign out”, “switch account”, and any re-authentication step you want to be real. Omit it everywhere else, which is most places.

prompt needs @muhkoo/connect@0.14.0-alpha.5 or later. Everything above it on this page is the hosted page’s own behaviour and needs no particular SDK version.

Revoking a remembered browser

Paired browsers sit alongside paired machines (the CLI pairs itself on the first command that needs your files, not at muhkoo login) in the account’s login methods on auth.muhkoo.dev/security, labelled Paired browser or machine, and can be removed from there or with muhkoo devices rm <factorId>. Removal is immediate: the browser’s key is useless without the wrapped seed the vault stores.

The 30-day lapse is local to the browser, so a pairing that has aged out stops working but stays in that list until someone removes it. An old entry there is normal, not a sign that something is still signed in.

Not the same as a paired TV

The paired devices on that page are a separate mechanism with the opposite revocation story: a TV is sent a copy of the seed and stores it, so removing it means “ask for approval again next time”, not “locked out”. A device factor holds only a key to a server-held blob, so removing it does lock that browser or machine out. Don’t describe them with the same words in your own UI.

If you build your own sign-in page instead of using the hosted one, the same primitives are on client.auth.zk — enrollDevice(label) to pair, and loginWithDevice(username, factorId, deviceKey) to sign in with the stored key (unlockWithDevice recovers the seed only, which is right for a CLI that already holds a session token). You then own the key: keep it on your origin, and handle DeviceRevokedError by discarding it and falling back to a password.

Keyboard-less devices

A TV or set-top box can’t run the redirect flow — no keyboard, no WebAuthn, and no redirect URL to come back to. Hosted auth extends to those devices with device pairing: the device shows a short code, the user approves it from a browser where they’re already signed in, and the same sealed-seed handoff delivers the master seed to that device alone (the seal key is derived by ECDH instead of riding a URL fragment, and the redirect becomes a poll).

See the TV & device pairing guide.

Account & security management

Don’t build a per-app security/settings screen. Point a “Manage account” button at the hosted page and it handles everything — passkeys, recovery email, Google, recovery phrase, change password, and removing login methods — consistently across every Muhkoo app:

await client.auth.hosted.manageAccount({ returnUri: window.location.href });
// → auth.muhkoo.dev/security; the page has a "Back to app" button.

The user signs in there to unlock their identity (the master seed isn’t persisted at rest), then manages factors. Changes apply to the same identity your app already uses — nothing to sync.