Askr
Server & APIs

Framework Auth Routes

Use framework auth routes with the current published Askr packages.

  • @askrjs/askr0.0.59

How to use framework auth routes

Resolve identity at the request boundary and express authorization as reusable requirements instead of component-only checks.

  1. Import the published @askrjs/askr entrypoint.
  2. Keep framework auth routes configuration next to the component, route, or server composition root that owns it.
  3. Handle pending, unavailable, cancellation, and failure states, then verify the production path.
import {
  createAuth,
  requirePermission,
  requireUser,
} from '@askrjs/auth';

export const auth = createAuth({
  sessions: sessionStore,
  principals: principalStore,
});

export const manageProjects = [
  requireUser(),
  requirePermission('projects:write'),
];

/auth/v1 contract

registerAuthRoutes(api, options) from @askrjs/server/auth attaches register, login, session, and logout endpoints onto an ApiDefinition group you create yourself with api.group(...). The package doesn't hardcode a path prefix - the /auth/v1 naming used throughout this guide is just the mount point convention, not something baked into registerAuthRoutes.

Login and callback

AuthRouteOptions.register(context, credentials) and authenticate(context, credentials) are functions you supply to create or verify a Principal from an AuthCredentials {email, password} pair - registerAuthRoutes calls whichever matches the route being hit. allowAttempt(context, operation, normalizedEmail) runs before either of them, letting you reject or throttle repeated attempts against the same address before register or authenticate ever executes.

Session and logout

On a successful register or authenticate, options.issuer.issue(principal) - a TokenIssuer<P> you provide - produces the token that gets written to the cookie described by options.cookie (standard CookieOptions plus a name). An optional redirect(context, operation, principal) callback can return a URL to send the client to instead of a bare JSON response, which is how the built-in routes support both API and browser-form flows from the same registration.

Safe redirects

safeRedirect(fallback, options?: {allowHash?}) returns a validator function that only accepts same-origin redirect targets, falling back to the given default for anything it doesn't recognize as safe - use it on a redirect or next query parameter before honoring it, since forwarding an unvalidated one is an open-redirect vulnerability. Other failures in the flow - a duplicate email on register, or a throttled attempt from allowAttempt - surface as an AuthRouteError with a fixed status of 401, 409, or 429 rather than a generic error.