API & specs

Status: Binding for implementers · Maturity: 0.0.x

Paths sit under your Better Auth basePath (often /api/auth). Package getting started: Packages overview.

Composition sketch

const passkeyStack = enhancePasskey(passkey, {
  rpID,
  origin,
  assertCredentialAccess, // fn | "session" | "deny"
});

plugins: [
  ...passkeyStack.plugins,
  loginFactors(),
  elevate({
    deploymentMode: "single-instance",
    passkeyCounterGuard: passkeyStack.controller,
    passwordOnlyIfNoStronger: true,
    elevatedTtlSec: 300,
  }),
  zeroAccess({
    deploymentMode: "single-instance",
    assertAccess: assertZeroAccess,
  }),
];

Client BA plugins: passkeyClient(), elevateClient(), zeroAccessClient().

Elevate

Verify methods

Enrollment for policy is server-derived — never from the client body.

Signed claim

HMAC from HKDF(BETTER_AUTH_SECRET, salt="auth-elevate", info="elevate-claim-v1"). Wire: payload.sig. Fields: userId, elevatedAt, firstElevatedAt?, expiresAt / TTL, amr[], opaque sessionBinding. Default TTL 300s. Extending requires a new successful verify — no one-shot mint/consume API.

import { requireElevate } from "@railman/auth-elevate";

// Better Auth getSession bundle: claim lives on session.session
await requireElevate(session.session.elevateClaim, {
  secret,
  userId: session.user.id,
  sessionToken: session.session.token,
  ttlSec: 300,
});

Package docs: Elevate.

Zero-access

Wrap kinds: prf_passkey · password_kdf · recovery_bip39. Password/recovery wraps require ≥ 600_000 PBKDF2 iterations.

zeroAccess({ secret?: string }) is the only persistent key-authority option. Omit it to capture Better Auth's resolved secret, or set a stable Railman-specific root to separate persistent-data lifecycle. The root derives purpose-separated non-extractable MAC and storage-ID families internally. An installed passkey guard is discovered and bound automatically by exact plugin identity.

* Rate-limited and purpose-scoped.

Package docs: Zero-access.

E2E relay

Session-gated; bodies M6-checked; persistent rows are MAC-protected.

Fingerprint: SHA-256("zero-e2e-fp-v1" ‖ signingKey ‖ identityKey) base64url. Client crypto: Zero-e2e.

M6 denylist

Reject bodies that include raw secret keys (NFKC + compacted, case-insensitive), including:

mnemonic, recoveryPhrase, rawMek, masterKey, prfSecret, plaintext, seed, privateKey, password, passphrase, authSecret, …

Wrap puts scan the full request body before snapshotting allowlisted fields. Canonical list: package m6.ts.

Privilege helpers

import { requireElevate } from "@railman/auth-elevate";
import {
  AUTH_REQUIRE_PRESETS,
  createElevateOpener,
  requireAccess,
} from "@railman/auth-login-factor";

await requireElevate(claim, { secret, userId, sessionToken });
await requireAccess({
  secret,
  session,
  map: AUTH_REQUIRE_PRESETS.privilegedAction,
  elevateOpener: createElevateOpener({
    secret,
    userId: session.userId,
    sessionToken: session.sessionToken,
    ttlSec: 300,
    maxElevatedSec: 3600,
  }),
});

requireAccess maps are server constants. Maps that inspect elevate AMR need elevateOpener from createElevateOpener (same user + session token). Browser MEK session helpers are never a server authorization signal.

Package docs: Login factor.

Client libraries

Vault client (surface)

Related

• Packages overview
• Plugin contract (short mirror)
• Use cases / compose guides
• Checklist