zero-auth

Appearance

zero-auth API Documentation v1.6.0

zero-auth API Documentation / AuthInstance

Interface: AuthInstance ​

Defined in: packages/zero-auth/src/index.ts:25

The full auth object returned by createAuth().

Properties ​

config ​

readonly config: ResolvedConfig

Defined in: packages/zero-auth/src/index.ts:158

The fully resolved config (for advanced usage).

errorHandler ​

errorHandler: ErrorRequestHandler

Defined in: packages/zero-auth/src/index.ts:153

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: packages/zero-auth/src/index.ts:75

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: packages/zero-auth/src/index.ts:82

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: packages/zero-auth/src/index.ts:109

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

Parameters ​

res ​

Response

Returns ​

void

csrf() ​

csrf(): RequestHandler

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

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: packages/zero-auth/src/index.ts:112

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

Parameters ​

res ​

Response

Returns ​

string

decodeToken() ​

decodeToken(token): AuthUser

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

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: packages/zero-auth/src/index.ts:32

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: packages/zero-auth/src/index.ts:38

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: packages/zero-auth/src/index.ts:44

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" });`

getJwks() ​

getJwks(): Promise<{ keys: Record<string, unknown>[]; }>

Defined in: packages/zero-auth/src/index.ts:136

Returns the public key(s) formatted as a JSON Web Key Set (JWKS). Can be used to serve a custom JWKS endpoint or inspect published keys. Only available when asymmetric keys are configured.

Returns ​

Promise<{ keys: Record<string, unknown>[]; }>

Example ​

ts
`const jwks = await auth.getJwks();`

jwksHandler() ​

jwksHandler(): RequestHandler

Defined in: packages/zero-auth/src/index.ts:144

Express route handler that serves the JWKS JSON. Sets Content-Type: application/json and Cache-Control headers. Only available when asymmetric keys are configured.

Returns ​

RequestHandler

Example ​

ts
`app.get("/.well-known/jwks.json", auth.jwksHandler());`

optional() ​

optional(): RequestHandler

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

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: packages/zero-auth/src/index.ts:68

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: packages/zero-auth/src/index.ts:121

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: packages/zero-auth/src/index.ts:126

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: packages/zero-auth/src/index.ts:104

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: packages/zero-auth/src/index.ts:53

Verifies a refresh token and returns the decoded payload.

Parameters ​

token ​

string

Returns ​

Promise<AuthUser>

verifyToken() ​

verifyToken(token): Promise<AuthUser>

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

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.