Core overview

What is AuthEngine?

AuthEngine is the runtime entry point for duck-auth. You instantiate it once at boot, wire it with the transport, stores, and providers you want, and hand the instance to your framework adapter.

import { AuthEngine } from '@gentleduck/auth/core'

export const auth = new AuthEngine({ /* config */ })

Every concern is exposed as a typed facet on the instance. There is no hidden global, no module-level state, no implicit singleton.

The 14 facets

Constructor at a glance

import { AuthEngine, AuthInMemoryEvents, AuthScryptHasher } from '@gentleduck/auth/core'
import { CookieTransport } from '@gentleduck/auth/core/transport'
import { AuthMemoryAdapter } from '@gentleduck/auth/adapters/memory'
import { AuthMemoryLimiter } from '@gentleduck/auth/limiters/memory'

const adapter = new AuthMemoryAdapter()

export const auth = new AuthEngine({
  baseUrl: 'http://localhost:3000',
  transport: new CookieTransport({ secure: false }),
  stores: {
    identities: adapter.identities,
    sessions: adapter.sessions,
    credentials: adapter.credentials,
    // orgs is optional - pass adapter.orgs to enable the orgs facet
  },
  events: new AuthInMemoryEvents(),
  limiter: new AuthMemoryLimiter({ max: 5, windowMs: 60_000 }),
  passwords: { hasher: new AuthScryptHasher() },
})

The request lifecycle

const ctx = await auth.resolveSession(req, {
  expectedTenantId: 'org-123',          // optional cross-tenant guard
  requestSnapshot: { ip, userAgent },   // optional, drives anomaly detectors
})

if (!ctx) {
  return new Response('Unauthorized', { status: 401 })
}

// ctx.session, ctx.identity, ctx.anomaly?  <- all typed

If anomaly detectors are wired and requestSnapshot is provided, ctx.anomaly.decision is one of allow / deny / step-up.

Strict mode

AuthEngine.strict() is a boot-time validator. Call it after construction to catch misconfigurations early.

auth.strict({ env: 'development' })  // warns only
auth.strict({ env: 'production' })   // throws AUTH/MISCONFIGURED

In production, strict rejects:

• CookieTransport.secure: false
• AuthMemoryAdapter (the in-memory dev store)
• AuthMemoryLimiter (the in-memory dev limiter) or no limiter at all
• No listeners attached to the lockout event
• Insecure JWT keys (short HS256 secret, missing kid)
• Compliance preset violations (HIPAA/FIPS require Argon2 + dataAtRest)
• A registered provider with no callback URL when baseUrl is set

See Production hardening for the full list of gates.

Typed generics

AuthEngine<Profile, Tenant, OrgMeta> is parameterised by three shapes:

type Profile = { displayName: string; avatarUrl?: string }
type Tenant = { region: 'eu' | 'us'; tier: 'free' | 'pro' }
type OrgMeta = { plan: 'team' | 'enterprise' }

export const auth = new AuthEngine<Profile, Tenant, OrgMeta>({
  /* config */
})

The generics propagate everywhere: auth.identities.findById(id) returns Identity<Profile>, auth.orgs.list(identityId) returns Membership<OrgMeta>[], and provider hooks see Profile on every payload.

Where each facet lives

• Sessions -> - the 7-row rotation matrix.
• Identities -> - CRUD, linking, GDPR.
• Passwords -> - AuthScryptHasher, AuthArgon2idHasher.
• Transports -> - Cookie, Bearer, JWT, Composite, DPoP.
• Events -> - AuthInMemoryEvents, AuthRedisEvents, AuthWebhookDeliverer.
• Anomaly -> - detectors and the step-up decision.
• Compliance -> - gdpr, hipaa, soc2, fips.
• Errors -> - every AUTH/* code and its status.