@auth/sdk

JavaScript client for the auth-system server. Plain fetch, zero runtime dependencies, cookie-based auth.

Install

pnpm add @auth/sdk        # workspace

Quick start (browser)

import { AuthClient, MfaRequiredError } from "@auth/sdk";

const auth = new AuthClient({ baseUrl: "" }); // same-origin / rewrite

await auth.signup({ email, password });

try {
  await auth.login({ email, password });
} catch (err) {
  if (err instanceof MfaRequiredError) {
    const code = prompt("6-digit code:");
    await auth.submitMfaChallenge({ mfaToken: err.mfaToken, code });
  } else throw err;
}

const { user } = await auth.me();

Server-side use (Next.js server actions)

Cookies don't auto-flow when the request originates in Node. Provide a defaultHeaders function that synthesises the Cookie header:

import { cookies } from "next/headers";
import { AuthClient } from "@auth/sdk";

export async function getServerAuth() {
  const c = await cookies();
  return new AuthClient({
    baseUrl: process.env.AUTH_API_URL,
    defaultHeaders: () => ({
      Cookie: c.toString(),
    }),
    getCookie: (name) => c.get(name)?.value ?? null,
  });
}

Errors

Every non-2xx response throws one of:

| Class | Origin | Notable fields | |---|---|---| | MfaRequiredError | login when MFA enrolled | mfaToken | | RateLimitError | HTTP 429 | retryAfter (sec) | | UnauthorizedError | HTTP 401 / 403 | code | | ValidationError | HTTP 400 | code, body | | AuthError | other failures | status, code, body |

Branch with instanceof; check error.code for the backend's machine-readable label (invalid_credentials, csrf_invalid, …).

Methods

| | | |---|---| | signup({email, password}) | Create account | | login({email, password}) | Throws MfaRequiredError if MFA enrolled | | submitMfaChallenge({mfaToken, code?, backupCode?}) | Complete MFA | | logout() | End session | | me() | Current user | | verifyEmail({token}) | Confirm email | | resendVerification({email}) | Re-send verification | | forgotPassword({email}) | Trigger reset email | | resetPassword({token, password}) | Set new password | | changePassword({currentPassword, newPassword}) | While authenticated | | enrollTotp() | Begin MFA enrollment | | verifyTotpEnrollment({code}) | Confirm + receive backup codes | | disableTotp({currentPassword, code}) | Turn MFA off | | backupCodeCount() | { total, remaining } | | regenerateBackupCodes() | New 10-code set | | oauthStartUrl(provider) | URL to navigate to | | listAccounts() | Linked providers | | unlinkAccount(provider) | Remove a link | | auditLog({limit?}) | User's own audit history |