Errors

duck-auth throws one class, AuthError. Each carries a code, the HTTP status that code maps to, and a typed meta.

AuthError

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

try {
  await auth.flows.signIn({ providerId: 'password', input })
} catch (err) {
  if (err instanceof AuthError && err.code === 'AUTH_RATE_LIMITED') {
    err.status // 429
    err.meta.retryAfter // seconds, typed from the code
  }
  throw err
}

err.message is the bare code. Anything a code needs to say rides on meta, typed per code, so toThrow(/detail/) in a test never matches; assert on err.meta instead.

asAuthError(err, fallbackCode) from @gentleduck/auth/core/errors passes an AuthError through and wraps anything else under the fallback, with the original on cause.

Answers

Calls that look something up answer an Answer: a promise that throws when awaited, with readers that take the failure as a value.

const identity = await auth.identities.getByEmail(email) // throws AUTH_IDENTITY_NOT_FOUND
const maybe = await auth.identities.getByEmail(email).orNull() // null when there is no row
const named = await auth.identities.getByEmail(email).orDefault(guest) // guest when there is no row
const { data, error } = await auth.identities.getByEmail(email).wrap() // never throws

orNull and orDefault absorb only the codes that mean "no row", and rethrow everything else, so a database that is down never reads as a free email address:

AUTH_CREDENTIAL_NOT_FOUND, AUTH_IDEMPOTENCY_MISS, AUTH_IDENTITY_NOT_FOUND, AUTH_IMPERSONATE_WINDOW_CLOSED, AUTH_JWT_INVALID, AUTH_JWT_KEY_UNKNOWN, AUTH_MEMBERSHIP_NOT_FOUND, AUTH_ORG_NOT_FOUND, AUTH_SESSION_EXPIRED, AUTH_SESSION_REVOKED.

The set is exported as ABSENT. A few codes stay out of it on purpose: AUTH_SESSION_IDENTITY_ERASED, AUTH_ANOMALY_DENIED and AUTH_TENANT_SCOPE_VIOLATION are refusals or integrity failures, and must not quietly become an anonymous request.

orNull(promise) does the same for a plain promise, such as a store call:

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

const findIdentityByEmail = (email: string) => orNull(stores.identities.find({ email }))

On the wire

errorToHttp(err) from @gentleduck/auth/server/generic is what every server adapter answers with:

errorToHttp(new AuthError('AUTH_RATE_LIMITED', { retryAfter: 30 }))
// { status: 429, body: { ok: false, error: { code: 'AUTH_RATE_LIMITED', status: 429, retryAfter: 30 } } }

• An AuthError answers its status, with its meta spread into error. Meta keys that look like secrets are scrubbed.
• Anything else answers 500 with detail: 'internal error', and is logged rather than described.
• A page reads error.code from this body, so the browser sees the server's code.

Codes

The registry is exported as AUTH_ERRORS from @gentleduck/auth/core/errors, keyed by code.