zero-auth

Appearance

zero-auth API Documentation v1.2.0

zero-auth API Documentation / AuthInstance

Interface: AuthInstance ​

Defined in: src/index.ts:24

The full auth object returned by createAuth().

Properties ​

config ​

readonly config: ResolvedConfig

Defined in: src/index.ts:139

The fully resolved config (for advanced usage).

errorHandler ​

errorHandler: ErrorRequestHandler

Defined in: src/index.ts:134

Express error-handling middleware for AuthErrors. Mount after all routes with app.use(auth.errorHandler).

Example ​

ts
`app.use(auth.errorHandler);`

Methods ​

authorize() ​

authorize(allowedRoles): RequestHandler

Defined in: src/index.ts:74

Middleware: enforces role-based access. Must run after protect(). Rejects requests where req.user.role is not in allowedRoles with 403.

Parameters ​

allowedRoles ​

string[]

Returns ​

RequestHandler

Example ​

ts
`app.get("/admin", auth.protect(), auth.authorize(["admin"]), handler);`

authorizePermissions() ​

authorizePermissions(requiredPermissions): RequestHandler

Defined in: src/index.ts:81

Middleware: requires every listed permission. Must run after protect(). Rejects requests where req.user.permissions is missing a permission with 403.

Parameters ​

requiredPermissions ​

string[]

Returns ​

RequestHandler

Example ​

ts
`app.get("/users", auth.protect(), auth.authorizePermissions(["users:read"]), handler);`

clearAuth() ​

clearAuth(res): void

Defined in: src/index.ts:108

Clears both auth cookies from the response. Use on logout.

Parameters ​

res ​

Response

Returns ​

void

csrf() ​

csrf(): RequestHandler

Defined in: src/index.ts:94

Middleware: validates CSRF tokens on configured methods when auth cookies are present. Mount before state-changing routes.

Returns ​

RequestHandler

csrfToken() ​

csrfToken(res): string

Defined in: src/index.ts:111

Sets and returns a client-readable CSRF token for cookie-authenticated clients.

Parameters ​

res ​

Response

Returns ​

string

decodeToken() ​

decodeToken(token): AuthUser

Defined in: src/index.ts:58

Decodes a token without verifying the signature. Never use this method as authorization; use verifyToken() for trust decisions.

Parameters ​

token ​

string

Returns ​

AuthUser

generateAccessToken() ​

generateAccessToken(payload): Promise<string>

Defined in: src/index.ts:31

Generates a signed access token for the given payload.

Parameters ​

payload ​

JwtPayload

Returns ​

Promise<string>

Example ​

ts
`const token = await auth.generateAccessToken({ id: "user-123" });`

generateRefreshToken() ​

generateRefreshToken(payload): Promise<string>

Defined in: src/index.ts:37

Generates a signed refresh token for the given payload.

Parameters ​

payload ​

JwtPayload

Returns ​

Promise<string>

Example ​

ts
`const token = await auth.generateRefreshToken({ id: "user-123" });`

generateTokenPair() ​

generateTokenPair(payload): Promise<TokenPair>

Defined in: src/index.ts:43

Generates a matched access + refresh token pair in parallel.

Parameters ​

payload ​

JwtPayload

Returns ​

Promise<TokenPair>

Example ​

ts
`const { accessToken, refreshToken } = await auth.generateTokenPair({ id: "user-123", role: "user" });`

optional() ​

optional(): RequestHandler

Defined in: src/index.ts:88

Middleware: optionally authenticates. Never rejects — populates req.user if a valid token is present, otherwise continues as a guest.

Returns ​

RequestHandler

Example ​

ts
`app.get("/posts", auth.optional(), postsHandler);`

protect() ​

protect(): RequestHandler

Defined in: src/index.ts:67

Middleware: rejects unauthenticated requests with 401. Attaches req.user on success.

Returns ​

RequestHandler

Example ​

ts
`app.get("/profile", auth.protect(), profileHandler);`

refreshHandler() ​

refreshHandler(): RequestHandler

Defined in: src/index.ts:120

Express route handler for POST /auth/refresh. Validates the refresh token and issues a new access token.

Returns ​

RequestHandler

Example ​

ts
`app.post("/auth/refresh", auth.refreshHandler());`

rotateTokens() ​

rotateTokens(payload): Promise<TokenPair>

Defined in: src/index.ts:125

Generates a new token pair (access + refresh). Use for custom token rotation.

Parameters ​

payload ​

JwtPayload

Returns ​

Promise<TokenPair>

sendAuthTokens() ​

sendAuthTokens(res, user): Promise<TokenPair>

Defined in: src/index.ts:103

Sets both the access and refresh token as HTTP-only cookies on the response, and returns the tokens as JSON. Use after login/register.

Parameters ​

res ​

Response

user ​

JwtPayload

Returns ​

Promise<TokenPair>

Example ​

ts
`const tokens = await auth.sendAuthTokens(res, { id: "user-123" });`

verifyRefreshToken() ​

verifyRefreshToken(token): Promise<AuthUser>

Defined in: src/index.ts:52

Verifies a refresh token and returns the decoded payload.

Parameters ​

token ​

string

Returns ​

Promise<AuthUser>

verifyToken() ​

verifyToken(token): Promise<AuthUser>

Defined in: src/index.ts:49

Verifies an access token and returns the decoded payload.

Parameters ​

token ​

string

Returns ​

Promise<AuthUser>

Throws ​

AuthError when the token is missing, invalid, or expired.