Production hardening

AuthEngine.strict()

strict() is the boot-time validator. Call it after construction; it runs synchronously, no I/O.

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

It is a hard error to omit this call in production - there is no way to guess your intent without it, and every production deploy of duck-auth should pin the configuration through this gate.

The gates

In production mode, strict rejects:

Transport gates

• CookieTransport.secure: false - cookies must be sent only over HTTPS.
• CookieTransport.sameSite: 'none' without secure: true.
• JwtTransport with a single key (no rotation overlap possible).
• JwtTransport HS256 secret shorter than 32 bytes.
• JwtTransport.ttlMs > 24 hours (refresh-token rotation is the right mechanism for long-lived access).

Storage gates

• AuthMemoryAdapter (the dev/test in-process adapter).
• AuthMemoryLimiter (or no limiter at all).
• A AuthSession.IStore that is not durable across process restarts.
• An events.IBus that doesn't fan out across replicas, unless you've explicitly opted out of multi-replica.

Observability gates

• No listener attached to the lockout event. At minimum you should be paging on or auditing every lockout.
• No AuthWebhookDeliverer configured under SOC2 / HIPAA presets.

Compliance gates

• HIPAA / FIPS without AuthArgon2idHasher.
• FIPS with HS256 or RS256 JWTs.
• HIPAA / FIPS without dataAtRest encryption.
• HIPAA without an audit-hooked channel.
• FIPS without mfa.enforced: true.

Provider gates

• A configured baseUrl that doesn't match any registered provider's redirectUri host (https://app.example.com baseUrl + a https://localhost Google redirect would catch this).
• An OAuth provider with stateSigningSecret shorter than 32 bytes.

The threat model

duck-auth's THREAT-MODEL.md is a STRIDE-mapped enumeration of every threat the library mitigates and every threat the host application must own. Highlights:

Static-analysis safety net

The duck-auth source tree runs 12 grep-style assertions at test time that enforce security invariants Python-style linters can't catch. Source: src/__tests__/static-analysis.test.ts. Examples:

• No Math.random() in core/, providers/, oidc/, transport/. Allowed elsewhere only when used for non-cryptographic instance IDs.
• No === comparison on field names matching tokenHash / secretHash / clientSecret / codeChallenge / code_verifier / verifier in security paths.
• No console.log in security paths (console.error for caught throws is OK).
• OIDC OP code generation uses randomToken, never Date.now or Math.random.
• OAuth state and nonce paths free of Math.random.
• CookieTransport defaults assert HttpOnly, Secure, SameSite.
• JwtTransport verify path pins alg against the registered verify key (defense vs RFC 8725 section 3.1 alg-confusion attacks).

If a refactor introduces one of the above patterns, this suite fails at PR time before the change can reach main.

Dependency audit

bun audit is run before every release and the result is checked in at AUDIT-RESULTS.md. Current advisories live entirely in dev / build / example tooling (vite, postcss, esbuild, storybook, uuid, qs, jsonpath-plus). None affect the runtime path of @gentleduck/auth. Re-run locally with:

bun audit

OWASP Top 10 mapping

Recommended production posture

import Redis from 'ioredis'
import {
  AuthArgon2idHasher,
  ARGON2ID_COMPLIANCE,
  AuthEngine,
  authCsrfGuard,
  hipaa,
  authImpossibleTravelDetector,
  AuthWebhookDeliverer,
} from '@gentleduck/auth/core'
import { JwtTransport } from '@gentleduck/auth/core/transport'
import {
  AuthRedisDPoPNonceStore,
  AuthRedisEvents,
  AuthRedisLimiter,
  AuthRedisSessionStore,
} from '@gentleduck/auth/adapters/redis'
import { authCreateSqlStores } from '@gentleduck/auth/adapters/sql'
import { createDrizzlePgBridge } from '@gentleduck/auth/adapters/drizzle/pg'

const redis = new Redis(process.env.REDIS_URL!)
const drizzleBridge = createDrizzlePgBridge(db, schema)
const sql = authCreateSqlStores({ bridge: drizzleBridge })

export const auth = new AuthEngine({
  ...hipaa({
    stores: {
      identities: sql.identities,
      credentials: sql.credentials,
      sessions: new AuthRedisSessionStore(redis),
    },
    events: new AuthRedisEvents(redis),
    channels: { email: new AuthSesChannel({ ... }) },
  }),
  baseUrl: 'https://api.example.com',
  transport: new JwtTransport({
    signKey: { kid: process.env.JWT_KID!, key: process.env.JWT_KEY! },
    verifyKeys: [
      { kid: process.env.JWT_KID!, key: process.env.JWT_KEY! },
      { kid: process.env.JWT_KID_PREV!, key: process.env.JWT_KEY_PREV! },
    ],
    issuer: 'https://api.example.com',
    ttlMs: 15 * 60 * 1000,
    refresh: { cookieName: '__Host-duck-refresh', ttlMs: 30 * 24 * 60 * 60 * 1000 },
  }),
  limiter: new AuthRedisLimiter(redis),
  passwords: { hasher: new AuthArgon2idHasher(ARGON2ID_COMPLIANCE) },
})

auth.anomaly.register(authImpossibleTravelDetector({ ... }))
auth.events.on('lockout', alertOpsTeam)

const webhook = new AuthWebhookDeliverer({
  url: 'https://audit.example.com/auth',
  secret: process.env.WEBHOOK_SECRET!,
})
auth.events.onAny((type, event) => webhook.deliver({ type, ...event }))

auth.strict({ env: 'production' })   // throws if any gate fails