Askr
Server & APIs

Model and Sessions

Use model and sessions with the current published Askr packages.

  • @askrjs/askr0.0.59

How to use model and sessions

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 model and sessions 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'),
];

Authentication context

AuthContext<P, S> is generic over your own Principal and AuthSession subtypes, so custom claims you add via the shared Claim base show up typed on ctx.auth.principal and ctx.auth.session rather than as untyped extras. Beyond the principal and session, it also carries tenant (string | null) and an optional scopes list, which is what requireScope() checks against. It's the return value of AuthResolver.resolve() and the only object requirement functions and route handlers need to look at.

Session storage

SessionStore<S> has exactly one method to implement: get(id, {request, signal}), returning S | null synchronously or as a promise. You pass it in as AuthOptions.sessions, and createAuth calls it during resolve() with the id it pulls from the configured sessionCookie. There's no built-in in-memory or database-backed implementation shipped with @askrjs/auth - you own storage, TTL, and any indexing it needs.

Cookies

AuthOptions.sessionCookie is just the cookie name createAuth reads to find a session id; @askrjs/auth never sets or clears cookies itself. Writing them is a @askrjs/server concern - ctx.setCookie(response, name, value, {httpOnly, sameSite, secure}) and ctx.clearCookie() operate on the outgoing Response and don't touch session storage or validate anything. Keeping the two apart means a route can set a cookie during login without @askrjs/auth needing to know the request ever happened.

Sign out and expiry

AuthSession carries optional expiresAt and revokedAt timestamps, which you compare against AuthOptions.clock() (Date.now by default, overridable for tests) when deciding whether a stored session is still good. There's no built-in expiry enforcement inside createAuth beyond what your SessionStore.get() implements - if it returns a session that's already past expiresAt, the resolver will still treat it as valid unless your store filters it out itself. Sign-out is likewise entirely your store's responsibility: mark the row revoked or delete it, and the next get() for that id should return null so resolve() falls back to an unauthenticated context.