@askrjs/auth

Framework-owned, domain-neutral authentication primitives for Askr. Server sessions require Node.js 24 or newer. The low-level OIDC and passkey client entries retain their explicit Web Crypto/Fetch or Credentials API boundaries.

Feature matrix

Replay prevention stays with the application’s durable storage boundary. SAML requires atomic requestStore.consume(). TOTP returns the accepted counter so it can be atomically marked used. WebAuthn returns the verified new signature counter so it can be atomically persisted.

Request authentication

createAuth() resolves Bearer JWTs, JWT cookies, and opaque session cookies into one auth context. Invalid, expired, or malformed JWTs are treated consistently as unauthenticated and resolution continues to the next configured credential source. Operational failures from tenant, principal, or session stores still reject resolve() so callers can handle unavailable dependencies.

OIDC

exchangeCode() accepts the callback and the stored authorization request separately. It checks state before network access, then validates the required ID token against discovery and JWKS before returning { tokens, principal }. ID-token audiences must identify only this client; any explicit azp must match the configured client ID. Additional-audience trust is not part of this client profile.

The OIDC entrypoint also runs in browsers with Web Crypto, Fetch, and UTF-8 encoding support. JWT decoding uses browser-native bytes and needs no Node Buffer polyfill. Browser clients omit clientSecret; retain the authorization request for callback correlation. This entry is a low-level protocol primitive; it does not replace server-owned application sign-in or retain session tokens in the browser. For application sessions use the server contract and the 0.5 migration.

import { createOidcClient } from "@askrjs/auth/oidc";

const client = createOidcClient({ issuer, clientId, clientSecret, redirectUri });
const request = await client.createAuthorizationRequest();
const result = await client.exchangeCode({ code: callback.code, state: callback.state, request });

Provider application sessions

Configure the shared createProviderSession engine from @askrjs/auth/server with one or more native providers, then bind it to the provider-auth mode in @askrjs/server. The server owns authorization/callback transport, sealed cookies, refresh tokens and per-resource token grants. createSessionAuth from @askrjs/askr/router binds the public session snapshot to an SSR or SPA application; provider tokens and client secrets stay server-side. See the committed ownership/API contract and setup for Auth0, Microsoft, Google or Apple.

@askrjs/auth/browser and the develop-only @askrjs/auth/auth0 SDK adapter are removed in 0.5. There is no replacement browser-held session/SDK path. The published 0.4.2 browser lifecycle requires the explicit server-session migration.

MFA

import { generateTotpSecret, verifyTotpCode } from "@askrjs/auth/mfa";

const secret = generateTotpSecret();
const result = await verifyTotpCode({ secret, code });
if (result.valid) await counters.consume(result.counter); // application-owned atomic replay guard

TOTP defaults to SHA-1, six digits, 30-second periods, and a one-step window. SHA-256, SHA-512, and eight-digit codes are supported. WebAuthn uses exact base64url challenges, exact origin allowlists, one RP ID, and user verification by default. It accepts ES256, RS256 (RSA 2048-bit or larger), and EdDSA/Ed25519 keys. Registration accepts none and cryptographically verified packed self-attestation only; certificate-backed attestation is deliberately rejected. Verification also applies explicit byte limits to client data, credential IDs, challenges, attestation objects, authenticator data, and signatures before parsing or cryptographic work.

SAML

The server-only @askrjs/auth/saml entrypoint provides a narrow SP-initiated SAML 2.0 flow: metadata generation, signed or unsigned HTTP-Redirect AuthnRequests, signed assertion validation, optional signed responses, encrypted assertions, request correlation, and atomic replay protection. It is intentionally separate from createAuth() and the package root.

import { createSamlServiceProvider } from "@askrjs/auth/saml";

const saml = createSamlServiceProvider({
  entityId: "https://app.example.com/saml/metadata",
  acsUrl: "https://app.example.com/saml/acs",
  idp: {
    entityId: "https://idp.example.com",
    ssoUrl: "https://idp.example.com/sso",
    certificates: [idpCertificate],
  },
  requestStore, // save/get plus an atomic consume operation
});

const { url } = await saml.createAuthnRequest({ relayState: "return-to" });
const principal = await saml.validateResponse({ samlResponse, relayState: "return-to" });

The request store is a security boundary: consume(id) must atomically return false for a missing, expired, or previously consumed ID. The validator defaults to a 10-minute request TTL, a five-minute assertion age, and 60 seconds of clock skew. Assertions are always signed; requireSignedResponse additionally requires the outer response signature.

JWT issuance and validation support RS256 with RSA keys and ES256 with EC P-256 keys. A JWK's alg may be omitted and inferred from its key shape; when present, it must match the key.

Install

npm install @askrjs/auth

0.5.0 preparation

See the complete API decisions and migration and hardening evidence. The browser passkey helpers remain at @askrjs/auth/webauthn-client; CBOR/COSE parsing and base64url conversion are private. Application stores retain replay, credential and policy ownership.