@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

Entry	Owns	Does not own
@askrjs/auth	Principal, auth contexts and requirements, bearer/cookie/session request resolution	Users, organizations, credential storage, password hashing
@askrjs/auth/jwt	RS256/ES256 issuance and validation, claims, JWKS rollover	Token persistence or revocation lists
@askrjs/auth/oidc	Discovery, authorization-code PKCE, callback correlation, verified ID-token-to-Principal exchange	Provider UI, account linking, refresh-token storage
@askrjs/auth/server	Server-owned provider transactions, sealed session cookies, refresh families and application hooks	Application users/policy and HTTP adapter ownership
@askrjs/auth/providers/auth0	Native Auth0 provider policy and API audiences	Browser SDKs and application routes
@askrjs/auth/providers/microsoft	Tenant-bound Microsoft provider and explicit API permissions	Multi-tenant inference and application routes
@askrjs/auth/providers/google	Google provider, hosted-domain policy and explicit API permissions	Workspace administration and application routes
@askrjs/auth/providers/apple	Apple web sign-in and daily account checks	API access-token grants and application routes
@askrjs/auth/saml	SP metadata and requests, signed/encrypted response validation, request correlation	IdP operation, SLO, IdP-initiated SAML, external CA trust policy
@askrjs/auth/mfa	TOTP and WebAuthn registration/authentication verification	Credential storage, recovery policy, enrollment UI

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.