#Auth

The settings, routes, errors and contracts of @dotpress/auth. For a guide, see Authentication.

#createAuth()

import { createAuth } from '@dotpress/auth'

const auth = createAuth({ keys, issuer: 'https://api.example.com', dataProvider })

Invalid settings make createAuth() throw; a missing issuer, a publicKey that does not match the secretKey, or a PKCS#1 key make the app fail at startup, with an explicit message.

#Cookie settings

See Cookie mode and CSRF.

#authPlugin()

authPlugin(auth, { prefix: '/auth', routes: true, jwks: false })

The plugin is named auth, provides ctx.user and ctx.auth, and declares the bearerAuth security scheme (AUTH_SECURITY_SCHEMES) for OpenAPI.

#Routes

expiresAt is the expiration of the access token; sessionExpiresAt is set when an absolute timeout applies.

#Errors

The routes answer the standard error format; the message carries the reason:

Outside the routes, the service throws an AuthError whose code is INVALID_ACCESS_TOKEN, INVALID_REFRESH_TOKEN, EXPIRED_REFRESH_TOKEN, REFRESH_TOKEN_REUSED or SESSION_REVOKED.

#Guards

A 401 gets a WWW-Authenticate: Bearer header (RFC 6750), with error="invalid_token" when the request carried an expired, revoked or invalid token. See Protecting routes.

#The service

generatePasswordHash(password, rounds?) and isPasswordTooLong(password) are also exported, without a service.

#AuthSession

ctx.auth, the data of the access token:

Access tokens follow RFC 9068: typ: at+jwt, RS256, and the iss, aud, sub, jti, iat, exp and auth_time claims. auth_time is the start of the session.

#DataProvider

interface DataProvider {
  storeRefreshToken(payload: {
    token: string
    tokenHash: string // SHA-256 of the token: store this one only
    userId: string
    jwtId: string // the access token issued with it
    familyId: string // the session
    expiresAt: Date
  }): Promise<void>
  findRefreshToken(tokenHash: string): Promise<
    | {
        userId: string
        jwtId: string
        familyId?: string | null
        expiresAt: Date
        isUsed: boolean
        usedAt?: Date | null
        revokedAt?: Date | null
      }
    | undefined
  >
  markRefreshTokenAsUsed(tokenHash: string, usedAt: Date): Promise<void>
  revokeTokens(userId: string): Promise<void> // every session of a user
  revokeTokenFamily(familyId: string): Promise<void> // one session
  findUserById(userId: string): Promise<AuthUser | undefined> // undefined for deleted or disabled accounts
  findUserIdentifiers(username: string): Promise<
    { userId: string; passwordHash: string | null; role?: string } | undefined
  >
  isSessionRevoked?(sessionId: string): Promise<boolean> // optional: immediate revocation
  updatePasswordHash?(userId: string, passwordHash: string): Promise<void> // optional: hash upgrade
}

isUsed can be derived from usedAt. Refresh tokens are 128 random bytes; only their hash is stored. See Data provider.