zero-auth

Appearance

zero-auth API Documentation v1.6.0

zero-auth API Documentation / AuthConfig

Interface: AuthConfig ​

Defined in: packages/zero-auth/src/types/auth.ts:29

Configuration passed to createAuth().

Properties ​

accessExpiresIn? ​

optional accessExpiresIn?: string

Defined in: packages/zero-auth/src/types/auth.ts:87

Expiry for access tokens. Accepts zeit/ms strings like "15m", "1h".

Default ​

ts
"15m"

accessSecret? ​

optional accessSecret?: string

Defined in: packages/zero-auth/src/types/auth.ts:34

Secret used to sign access tokens (HS256/symmetric). Min 32 chars recommended. Required when using symmetric algorithms unless asymmetric keys are provided.

algorithm? ​

optional algorithm?: SupportedAlgorithm

Defined in: packages/zero-auth/src/types/auth.ts:45

JWT signing and verification algorithm. Supports symmetric (HS256, HS384, HS512) and asymmetric (RS256, ES256, EdDSA, etc.).

Default ​

ts
"HS256"

cookies? ​

optional cookies?: CookieConfig

Defined in: packages/zero-auth/src/types/auth.ts:91

Cookie configuration. If provided, token cookies are enabled.

csrf? ​

optional csrf?: CsrfConfig

Defined in: packages/zero-auth/src/types/auth.ts:93

Optional CSRF protection for cookie-authenticated state-changing requests.

csrfSecret? ​

optional csrfSecret?: string

Defined in: packages/zero-auth/src/types/auth.ts:72

Symmetric secret for signing double-submit CSRF tokens when JWTs use asymmetric keys. Defaults to accessSecret if provided; otherwise required when CSRF is enabled with cookies.

jwks? ​

optional jwks?: RemoteJwksConfig

Defined in: packages/zero-auth/src/types/auth.ts:83

Optional configuration for remote JWKS fetching, caching, and timeouts.

jwksUri? ​

optional jwksUri?: string | URL

Defined in: packages/zero-auth/src/types/auth.ts:79

Remote JSON Web Key Set (JWKS) URL. When provided, verification keys are fetched dynamically from this URL with caching and cooldown. Sets verifier-only mode (token signing is disabled).

Example ​

ts
"https://auth.example.com/.well-known/jwks.json"

jwt? ​

optional jwt?: JwtValidationConfig

Defined in: packages/zero-auth/src/types/auth.ts:85

Optional JWT claim validation policy shared by access and refresh tokens.

keyId? ​

optional keyId?: string

Defined in: packages/zero-auth/src/types/auth.ts:67

Optional Key ID (kid) added to the protected header of signed JWTs.

privateKey? ​

optional privateKey?: KeyInput

Defined in: packages/zero-auth/src/types/auth.ts:50

Private key for signing access tokens (and refresh tokens if not overridden). Accepts PKCS#8 PEM string, CryptoKey, or KeyLike.

publicKey? ​

optional publicKey?: KeyInput

Defined in: packages/zero-auth/src/types/auth.ts:55

Public key for verifying access tokens (and refresh tokens if not overridden). Accepts SPKI PEM string, CryptoKey, or KeyLike.

refreshExpiresIn? ​

optional refreshExpiresIn?: string

Defined in: packages/zero-auth/src/types/auth.ts:89

Expiry for refresh tokens. Accepts zeit/ms strings like "7d", "30d".

Default ​

ts
"7d"

refreshOptions? ​

optional refreshOptions?: object

Defined in: packages/zero-auth/src/types/auth.ts:97

Optional refresh behavior configuration

consumeRefreshToken? ​

optional consumeRefreshToken?: (oldJti, ctx?) => boolean | Promise<boolean>

Atomically consume the old refresh token before issuing replacements. Return true only when this call marks the jti for the first time; return false when it was already consumed. Use an atomic store operation such as Redis SET NX for multi-instance deployments.

Parameters ​
oldJti ​

string

ctx? ​

RefreshTokenContext

Returns ​

boolean | Promise<boolean>

isRevoked? ​

optional isRevoked?: (jti) => boolean | Promise<boolean>

Parameters ​
jti ​

string

Returns ​

boolean | Promise<boolean>

Deprecated ​

Use consumeRefreshToken for concurrency-safe rotation.

onRefreshReuse? ​

optional onRefreshReuse?: (ctx) => void | Promise<void>

Called when a revoked refresh token is presented (reuse detected). Use this to revoke the entire token family / force re-login.

Parameters ​
ctx ​

RefreshReuseContext

Returns ​

void | Promise<void>

registerRefreshToken? ​

optional registerRefreshToken?: (newJti, ctx) => void | Promise<void>

Called after a new refresh token is issued so stores can track the new jti under its family (needed for family revocation on reuse).

Parameters ​
newJti ​

string

ctx ​

RefreshTokenContext

Returns ​

void | Promise<void>

resolveUser? ​

optional resolveUser?: (claims, ctx) => JwtPayload | Promise<JwtPayload | null> | null

Reloads current application-owned user claims before a refresh succeeds. Return null to reject deleted, disabled, or otherwise ineligible users.

Parameters ​
claims ​

JwtPayload

ctx ​

RefreshTokenContext

Returns ​

JwtPayload | Promise<JwtPayload | null> | null

revokeRefreshToken? ​

optional revokeRefreshToken?: (oldJti, ctx?) => void | Promise<void>

Called with the old refresh token jti before new tokens are issued.

Parameters ​
oldJti ​

string

ctx? ​

RefreshTokenContext

Returns ​

void | Promise<void>

Deprecated ​

Use consumeRefreshToken for concurrency-safe rotation. Failures abort the refresh (fail closed). Optional second ctx includes userId and familyId for family-aware stores.

rotate? ​

optional rotate?: boolean

When true, issue a new refresh token alongside the new access token. Use consumeRefreshToken for atomic replay protection. In 1.1.x, the legacy hook pair remains accepted with a warning. A stable fid (family id) claim is auto-injected when missing.

Default ​
ts
false

refreshPrivateKey? ​

optional refreshPrivateKey?: KeyInput

Defined in: packages/zero-auth/src/types/auth.ts:59

Optional dedicated private key for signing refresh tokens.

refreshPublicKey? ​

optional refreshPublicKey?: KeyInput

Defined in: packages/zero-auth/src/types/auth.ts:63

Optional dedicated public key for verifying refresh tokens.

refreshSecret? ​

optional refreshSecret?: string

Defined in: packages/zero-auth/src/types/auth.ts:39

Secret used to sign refresh tokens (HS256/symmetric). Min 32 chars recommended. Required when using symmetric algorithms unless asymmetric keys are provided.

refreshStore? ​

optional refreshStore?: RefreshTokenStore

Defined in: packages/zero-auth/src/types/auth.ts:95

Atomic refresh-token store used automatically when rotation is enabled.