@nxgt/janus 0.1.0

package/docs/guide/passwords.md

@@ -0,0 +1,136 @@
+# Password hashing
+
+This page is for choosing a password hasher, moving from one to another, and
+importing hashes written by another system. The login and the length policy
+are on the [users](users.md#options) page.
+
+```ts
+import { z } from 'zod';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+
+const User = z.object({ email: z.email() });
+const store = createMemoryStores();
+
+const auth = janus({
+	user: User,
+	password: { login: 'email' },
+	store,
+	hasher: scryptHasher(), // N = 2^17, r = 8, p = 1
+});
+```
+
+The examples below reuse `User` and `store`.
+
+A user type with a password and no `hasher` is refused at wiring with a
+`TypeError`. There is no silent fallback.
+
+## The two hashers
+
+| Hasher | Runs on | Hash | Parameters |
+| --- | --- | --- | --- |
+| `scryptHasher({ cost? })` | Node and Bun, no dependency | `$scrypt$ln=17,r=8,p=1$<salt>$<key>` | OWASP's: `cost` is log2(N), `17` by default, `10` to `20`; about 128 MiB per hash |
+| `bunHasher()` | Bun only, through `Bun.password` | `$argon2id$v=19$m=65536,t=2,p=1$…` | Pinned, so a change of default in a Bun release is not inherited silently |
+
+`bunHasher()` throws a `TypeError` when called outside Bun; the package still
+imports cleanly under Node, because nothing reads `Bun` until then.
+
+Lower `cost` only in tests — `10` is fast and still exercises every line:
+
+```ts
+const hasher = scryptHasher({ cost: 10 });
+```
+
+## Hashes describe themselves
+
+Every hash starts with its hasher's `prefix`, and carries its parameters. So
+**every wired hasher can verify, and exactly one hashes**: `hasher` writes new
+hashes, and `verifiers` only read the ones a database was written with before.
+
+```ts
+import { bunHasher, scryptHasher } from '@nxgt/janus';
+
+const auth = janus({
+	user: User,
+	password: { login: 'email' },
+	store,
+	hasher: bunHasher(),          // new hashes: argon2id
+	verifiers: [scryptHasher()],  // existing scrypt hashes still verify
+});
+```
+
+Two hashers claiming the same prefix are refused at wiring: which one verified
+would depend on the order they were listed in. A stored hash whose prefix no
+wired hasher claims is `HASH_UNSUPPORTED` at sign-in, and the error reports
+the prefix, never the hash.
+
+## Rehash on sign-in
+
+When a password matches a **stale** hash, `signIn` rewrites it with `hasher`.
+A hash is stale when:
+
+- a `verifiers` hasher wrote it, or
+- `hasher` wrote it with other parameters than it uses now — a raised scrypt
+  `cost`, or argon2id parameters other than the pinned ones.
+
+Moving off a hasher, or raising its cost, therefore reaches every active user
+with no migration to run. The password's `updatedAt` is kept, since the
+password did not change; the user's `version` moves. The write is conditional
+on the version just read: if a concurrent update wins, the sign-in still
+succeeds and the next one tries again. An outage on that write fails the
+sign-in with `STORE_FAILED`.
+
+That `version` move is why a user object read **before** a sign-in, then passed
+as `ifVersion`, can get `VERSION_CONFLICT`. Read the user again.
+
+## Importing hashes from another system
+
+A `PasswordHasher` is four members, and a verifier for a foreign format is a
+small object:
+
+```ts
+interface PasswordHasher {
+	readonly prefix: string;            // every hash it writes starts with this
+	hash(plain: string): Promise<string>;
+	verify(plain: string, hash: string): Promise<boolean>;
+	needsRehash?(hash: string): boolean; // its own hash, written with outdated parameters
+}
+```
+
+```ts
+import { type PasswordHasher, scryptHasher } from '@nxgt/janus';
+
+// Your bcrypt library's compare — bcryptjs's `compare`, for one.
+declare function compareBcrypt(plain: string, hash: string): Promise<boolean>;
+
+const legacyBcrypt: PasswordHasher = {
+	prefix: '$2b$',
+	hash: () => Promise.reject(new Error('bcrypt only verifies here')), // never called: it is not `hasher`
+	verify: (plain, hash) => compareBcrypt(plain, hash),
+};
+
+const auth = janus({
+	user: User,
+	password: { login: 'email' },
+	store,
+	hasher: scryptHasher(),
+	verifiers: [legacyBcrypt],
+});
+```
+
+Write each imported user's hash as their `PasswordRecord` with your store's
+`insertUser` — `janus()` has no call that takes a hash — and each one moves to
+scrypt the first time they sign in. Wire one verifier
+per prefix the old system wrote (`$2a$`, `$2b$`, `$2y$` for bcrypt).
+
+## What never happens
+
+- The plain password is never stored, and never appears in an error message.
+- The hash never reaches a `User` — `hasPassword` says whether there is one.
+- `signIn` compares against a dummy hash when nobody holds the login, so the
+  time taken does not reveal which accounts exist. The store's own latency
+  still can, and that limit is stated rather than denied.
+
+## See also
+
+- [Users](users.md) — `signIn`, `setPassword`, `changePassword`
+- [Errors](errors.md) — `CREDENTIALS_INVALID` and its `reason`

package/docs/guide/permissions.md

@@ -0,0 +1,347 @@
+# Permissions — `@nxgt/janus/permissions`
+
+This page is for modelling who may do what, and asking: `defineModel`,
+`fromField`, `when`, then `can`, `list`, `grant` and `revoke`. It is
+Zanzibar's model — relations between objects and subjects, permissions
+computed from them — **without its infrastructure**: the tuples live in your
+database, so a read follows a write and there is nothing to cache.
+
+```ts
+import { z } from 'zod';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+import { createMemoryRelations, defineModel, permissions } from '@nxgt/janus/permissions';
+
+const relations = createMemoryRelations();
+
+const auth = janus({
+	users: {
+		staff: { schema: z.object({ username: z.string() }), password: { login: 'username' } },
+	},
+	store: createMemoryStores(),
+	relations, // deleting a user deletes every tuple naming them
+	hasher: scryptHasher(),
+});
+
+const model = defineModel({
+	subjects: auth.types, // 'staff': a user type is a subject type
+	types: {
+		team: {
+			relations: { member: ['staff', 'team#member'], lead: ['staff'] },
+			permissions: { manage: ['lead'], view: ['member', 'manage'] },
+		},
+	},
+});
+
+const access = permissions({ model, store: relations });
+
+const grace = await auth.staff.create({ username: 'grace' });
+const team = { type: 'team', id: 't1' } as const;
+
+await access.grant(team, 'lead', grace);
+await access.can(grace, 'view', team);   // true: view includes manage, which includes lead
+await access.revoke(team, 'lead', grace);
+await access.can(grace, 'view', team);   // false
+```
+
+## The model
+
+```ts
+function defineModel<const C extends ModelConfig>(config: C & CheckedModel<C>): PermissionModel<C>;
+
+interface ModelConfig {
+	readonly subjects: readonly string[]; // pass auth.types
+	readonly types: {
+		readonly [objectType: string]: {
+			readonly relations?: { readonly [name: string]: readonly string[] | FromField };
+			readonly permissions?: { readonly [name: string]: readonly (string | When)[] };
+		};
+	};
+}
+```
+
+**A relation** lists who may hold it:
+
+| Holder | Means |
+| --- | --- |
+| `'staff'` | one user of type `staff` |
+| `'team'` | one object of type `team` — what an arrow follows |
+| `'team#member'` | a **subject set**: every member of a team |
+| `fromField('doctorId', 'staff')` | read from the object's own data — see [`fromField`](#fromfield) |
+
+**A permission** is the union of its rules:
+
+| Rule | Means |
+| --- | --- |
+| `'member'` | a relation of the same object |
+| `'manage'` | another permission of the same object |
+| `'team->view'` | an **arrow**: whoever holds `view` on the object's `team` |
+| `when('doctor', (ctx: { onShift: boolean }) => ctx.onShift)` | a rule under a condition — see [`when`](#when) |
+
+A permission may be asked of `can` and `list` like a relation, and a relation
+like a permission.
+
+### What the compiler refuses
+
+A relation naming a type that does not exist, a rule naming nothing, an arrow
+to a permission its target lacks, a name that is both a relation and a
+permission: each is a compile error **on the offending key**, and the error
+lists what you could have written.
+
+```ts
+defineModel({
+	subjects: ['staff'],
+	types: {
+		team: {
+			// @ts-expect-error — '"staf" is not a subject type or a subject set; name one of' …
+			relations: { member: ['staf'] },
+		},
+	},
+});
+```
+
+### What `defineModel` refuses at run time
+
+With a `TypeError`, when the model is defined — never at a check:
+
+- a name that is not camelCase;
+- an object type named like a user type;
+- a permission that reaches itself without crossing a relation (`view:
+  ['edit'], edit: ['view']`) — no data could ever end that loop;
+- a subject set or an arrow that would have to read **another** object's
+  `fromField` — only the object passed to `can()` carries its data. Store that
+  relation instead.
+
+A loop that crosses a relation — a folder viewable through its parent — is
+fine: the data ends it.
+
+## `fromField`
+
+```ts
+function fromField(field, subjectType): FromField;
+function fromField(field, subjectType, { lookup }): ReversibleFromField;
+type Lookup = (subjectId: string) => Promise<readonly string[]>;
+```
+
+A relation read from the object's own data — a record's `doctorId` — rather
+than a tuple kept in sync with it. Nothing is stored, and `grant` refuses it at
+compile time. `can()` is given the object, and the compiler requires every
+field a `fromField` of its type reads:
+
+```ts
+const model = defineModel({
+	subjects: ['staff'],
+	types: {
+		record: {
+			relations: { doctor: fromField('doctorId', 'staff') },
+			permissions: { view: ['doctor'] },
+		},
+	},
+});
+const access = permissions({ model, store: createMemoryRelations() });
+
+const record = { id: 'r1', doctorId: grace.id, title: 'Chart' }; // as your database answered it
+await access.can(grace, 'view', { type: 'record', ...record });
+```
+
+**Spread the loaded object.** A field missing at run time is a `TypeError`,
+never a denial. `null` in the field holds nobody.
+
+`list()` cannot read a field of objects it has not found, so it asks `lookup`
+for the ids of the objects whose field names the subject. A `list()` that would
+reach a `fromField` without one is a compile error:
+
+```ts
+fromField('doctorId', 'staff', { lookup: (staffId) => db.records.ids({ doctorId: staffId }) });
+```
+
+A lookup is your code, and it is not guarded: one that throws rejects `list()`
+with its own error. **Never answer `[]` for a database that could not answer**
+— that is a denial made of an outage.
+
+## `when`
+
+```ts
+function when<const Rule extends string, Ctx>(rule: Rule, test: (ctx: Ctx) => boolean): When<Rule, Ctx>;
+```
+
+Puts a condition written in TypeScript on a rule — any rule of the same type:
+a relation, a permission, an arrow. The test is synchronous and pure: it
+decides on what the caller passes, and reads nothing. Its `ctx` is what `can()`
+and `list()` then **require**, and only for the permissions whose rules reach
+it:
+
+```ts
+const model = defineModel({
+	subjects: ['staff'],
+	types: {
+		record: {
+			relations: { doctor: fromField('doctorId', 'staff') },
+			permissions: {
+				edit: [when('doctor', (ctx: { onShift: boolean }) => ctx.onShift)],
+			},
+		},
+	},
+});
+const access = permissions({ model, store: createMemoryRelations() });
+
+await access.can(grace, 'edit', { type: 'record', ...record }, { ctx: { onShift: true } });
+// @ts-expect-error — ctx is required: edit reaches a condition
+await access.can(grace, 'edit', { type: 'record', ...record });
+```
+
+## `permissions()`
+
+```ts
+function permissions<C extends ModelConfig>(options: PermissionsOptions<C>): Permissions<C>;
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `model` | `PermissionModel` | — | What `defineModel` answered |
+| `store` | `RelationStore` | — | Where tuples live: `createMemoryRelations()` in tests, `createMongoRelations(db)` from `@nxgt/janus-mongo` |
+| `maxDepth` | positive integer | `25` | How many relations a check may cross. Past it: `PERMISSION_DEPTH` |
+
+It connects to nothing, and refuses a store missing a method with a
+`TypeError`.
+
+### `can`
+
+```ts
+can(subject, permission, object, options?): Promise<boolean>;
+```
+
+- `subject` is a user from `janus()` as it is — any object with `type` and
+  `id` — an object of the model, or `null` for anonymous, which answers `false`
+  before any store call.
+- `permission` must be a relation or a permission of the object's type.
+- `object` is `{ type, id }` plus every field its `fromField`s read.
+- `options.ctx` is required exactly when a `when` is reachable.
+
+```ts
+await access.can(grace, 'view', { type: 'record', ...record });                               // true
+await access.can(grace, 'edit', { type: 'record', ...record }, { ctx: { onShift: false } });   // false
+await access.can(null, 'view', { type: 'record', ...record });                                // false, no store call
+```
+
+**A denial is `false`; a failure throws.** A store that cannot answer is
+`STORE_FAILED`; a walk past `maxDepth` is `PERMISSION_DEPTH`. Neither is ever
+`false`, which would deny everybody everything during an outage and say
+nothing. A cycle in the data — a team member of itself — is cut, and is not an
+error.
+
+### `list`
+
+```ts
+list(subject, permission, objectType, options?): Promise<CursorPage<string>>;
+```
+
+The ids of the objects of `objectType` on which `subject` holds `permission`,
+ascending, by pages — what `can()` answers `true` for, found without naming
+them.
+
+```ts
+const page = await access.list(grace, 'view', 'record', { limit: 50 });
+page.items;      // readonly string[]
+page.nextCursor; // string | null
+await access.list(grace, 'view', 'record', { after: page.nextCursor, limit: 50 });
+```
+
+`limit` is 20 by default and at most 100; `ctx` is required as for `can`.
+`null` answers an empty page before any store call.
+
+`list()` walks backwards from the subject, reading every page of the reverse
+index for every id each step reaches. That is fine for what one user can see,
+and not for a subject set holding most of the database — write a query of your
+own for that.
+
+### `grant` and `revoke`
+
+```ts
+grant(object, relation, holder): Promise<void>;
+revoke(object, relation, holder): Promise<void>;
+```
+
+Both are typed from the model: only a stored relation (never a `fromField`),
+and only a holder the relation admits.
+
+The same rule holds when reading: `can()` and `list()` follow only the holders
+a relation admits. A tuple stored past `grant()` — by an older model, or by
+hand — that the model does not admit grants nothing. `revoke()` refuses it as
+it refuses to `grant()` it, so remove it with the store:
+
+```ts
+await relations.write({
+	remove: [
+		{
+			object: { type: 'record', id: 'r1' },
+			relation: 'viewer',
+			subject: { type: 'team', id: 't1' },
+		},
+	],
+});
+```
+
+Narrowing a model therefore hides the tuples it no longer admits; it does not
+delete them, and widening it again brings them back.
+
+```ts
+await access.grant({ type: 'team', id: 't1' }, 'member', grace);
+await access.grant({ type: 'team', id: 't1' }, 'member', { type: 'team', id: 't2', relation: 'member' }); // a subject set
+await access.grant({ type: 'record', id: 'r1' }, 'team', { type: 'team', id: 't1' });                  // what 'team->view' follows
+await access.revoke({ type: 'team', id: 't1' }, 'member', grace);
+```
+
+Both are idempotent: granting what is held, or revoking what is not, is not an
+error. Each writes one tuple.
+
+### Deleting
+
+Wire the relation store into `janus({ relations })`, and deleting a user
+deletes every tuple naming them. Deleting an object's tuples is yours, from
+your own code, when you delete the object:
+
+```ts
+await relations.deleteEntity({ type: 'record', id: 'r1' }); // answers how many tuples it removed
+```
+
+## A route guard
+
+```ts
+import { PermissionDepthError, StoreFailure } from '@nxgt/janus';
+
+export async function getRecord(request: Request, id: string): Promise<Response> {
+	try {
+		const current = await auth.authenticate(request, { type: 'staff' });
+		const record = await loadRecord(id);
+		if (record === null) return new Response(null, { status: 404 });
+
+		const allowed = await access.can(current?.user ?? null, 'view', { type: 'record', ...record });
+		if (!allowed) return new Response(null, { status: current ? 403 : 401 });
+		return Response.json(record);
+	} catch (error) {
+		if (error instanceof StoreFailure) return new Response(null, { status: 503 });
+		if (error instanceof PermissionDepthError) return new Response(null, { status: 500 });
+		throw error;
+	}
+}
+```
+
+## Subjects and the notation
+
+A user **is** a subject: `subjectOf(user)` from `@nxgt/janus` answers its
+`{ type, id }`, and `can` takes the user as it is. Tuples print in Zanzibar's
+notation, typed — see [the shared vocabulary](vocabulary.md#subjects-and-the-tuple-notation).
+
+## The relation store
+
+`RelationStore` is six methods answering one-hop questions about stored tuples
+— `write`, `has`, `findSubjectSets`, `findEntities`, `findObjects`,
+`deleteEntity`. The traversal is the core's. `createMemoryRelations()` is the
+reference implementation, and [Writing an adapter](adapters.md) covers the
+rest.
+
+## See also
+
+- [Users](users.md) — `janus({ relations })`, and user types as subject types
+- [Errors](errors.md) — `STORE_FAILED` and `PERMISSION_DEPTH`
+- [Writing an adapter](adapters.md) — `RelationStore` and its conformance suite

package/docs/guide/sessions.md

@@ -0,0 +1,211 @@
+# Sessions
+
+This page is for everything after a user has signed in: finding who a request
+belongs to, the session cookie, renewal, signing out, and testing expiry.
+Signing up and signing in are on the [users](users.md) page.
+
+```ts
+import { z } from 'zod';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+
+const auth = janus({
+	user: z.object({ email: z.email(), name: z.string() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+export async function me(request: Request): Promise<Response> {
+	const current = await auth.authenticate(request);
+	if (current === null) return new Response(null, { status: 401 });
+
+	const headers = new Headers();
+	if (current.renewed) {
+		headers.set('Set-Cookie', auth.cookie.serialize(current.token, current.session));
+	}
+	return Response.json({ id: current.user.id, email: current.user.email }, { headers });
+}
+```
+
+## `authenticate`
+
+```ts
+authenticate<T extends User['type'] = User['type']>(
+	request: RequestLike,
+	options?: { readonly type?: T },
+): Promise<Authenticated<Extract<User, { type: T }>> | null>;
+
+interface Authenticated<U> {
+	readonly user: U;
+	readonly session: Session;  // the stored session, without its token hash
+	readonly token: string;     // the token the request presented
+	readonly renewed: boolean;  // true when this call moved session.expiresAt
+}
+```
+
+`request` is a `Request`, a `Headers`, anything with `headers` (a Node
+`IncomingMessage`), or a plain header record:
+
+```ts
+await auth.authenticate(new Headers({ authorization: `Bearer ${token}` }));
+await auth.authenticate({ 'x-session-token': token });
+await auth.authenticate({ headers: { cookie: `janus-session=${token}` } });
+```
+
+It reads `Authorization: Bearer`, then `X-Session-Token`, then the cookie.
+**The first credential present wins, not the first valid one**: a client that
+sends a lapsed bearer beside a live cookie is anonymous. An `Authorization`
+header of another scheme (`Basic`) is not a session credential.
+
+It answers `null` — anonymous — for no credential, an unknown token, a lapsed
+or revoked session, a user deleted or inactive, or a user of another type than
+`options.type`:
+
+```ts
+const staff = await clinic.authenticate(request, { type: 'staff' }); // a patient's session → null
+staff?.user.username; // typed as staff
+```
+
+**An outage is not anonymous.** When a store cannot answer, `authenticate`
+rejects with `STORE_FAILED` — answer 503. A 401 would sign everybody out during
+the outage and send them to a sign-in page that cannot work either:
+
+```ts
+import { StoreFailure } from '@nxgt/janus';
+
+export async function guarded(request: Request): Promise<Response> {
+	try {
+		const current = await auth.authenticate(request);
+		return current === null ? new Response(null, { status: 401 }) : Response.json(current.user);
+	} catch (error) {
+		if (error instanceof StoreFailure) return new Response(null, { status: 503 });
+		throw error;
+	}
+}
+```
+
+## Lifespan and renewal
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `session.lifespan` | `Duration` | `'7d'` | How long a session lives from when it was opened or last renewed |
+| `session.renewAfter` | `Duration \| false` | `'1d'` | Once this much has passed, `authenticate` moves `expiresAt` to a whole `lifespan` from now and answers `renewed: true`. `false`: a fixed lifespan |
+
+A sliding session is written **at most once per `renewAfter`**, not on every
+request. When `renewed` is `true`, send the cookie again — its `Expires` moved.
+With several user types, each type has its own `session`.
+
+Expiry is decided by the core on every read, not by the store: a store may
+still hold a lapsed session, and `authenticate` answers it as anonymous.
+
+## The cookie
+
+```ts
+const auth = janus({
+	user: z.object({ email: z.email() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+	cookie: { name: 'sid', sameSite: 'strict', domain: 'example.com' },
+});
+
+const { session, token } = await auth.signUp({ email: 'ada@example.com', password: 'correct horse' });
+
+auth.cookie.name;                       // 'sid'
+auth.cookie.serialize(token, session);  // 'sid=…; Expires=…; Path=/; Domain=example.com; HttpOnly; SameSite=Strict; Secure'
+auth.cookie.clear();                    // the same cookie, expired
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `name` | string | `'janus-session'` | A cookie-name token: no space, `;` or `=` |
+| `domain` | string | none | `Domain=` |
+| `path` | string | `'/'` | `Path=` |
+| `sameSite` | `'lax' \| 'strict' \| 'none'` | `'lax'` | `SameSite=` |
+| `secure` | boolean | `true` | `Secure`. `sameSite: 'none'` requires it |
+
+`HttpOnly` is always set. The cookie methods are synchronous and write
+nothing: they build a `Set-Cookie` value for you to send.
+
+## Signing in and out
+
+```ts
+export async function signIn(request: Request): Promise<Response> {
+	const { email, password } = (await request.json()) as { email: string; password: string };
+	const { user, session, token } = await auth.signIn({ email, password });
+	return Response.json(
+		{ id: user.id, token }, // a native client keeps the token and sends it as a bearer
+		{ headers: { 'Set-Cookie': auth.cookie.serialize(token, session) } },
+	);
+}
+
+export async function signOut(request: Request): Promise<Response> {
+	await auth.signOut(request); // false when the request presents no session, or an unknown one
+	return new Response(null, { status: 204, headers: { 'Set-Cookie': auth.cookie.clear() } });
+}
+```
+
+`signOutEverywhere(user, { except })` revokes every standing session of a
+user, but the one named, and answers how many it revoked — "sign out
+everywhere else":
+
+```ts
+const current = await auth.authenticate(request);
+if (current !== null) {
+	await auth.signOutEverywhere(current.user, { except: current.session.id });
+}
+```
+
+`changePassword` leaves other sessions open; call this after it when that is
+your policy. `resetPassword.confirm` signs out everywhere on its own.
+
+## `collectExpired`
+
+```ts
+const removed: number = await auth.collectExpired();
+```
+
+Deletes lapsed sessions, for a store that keeps them. It rejects with
+`UNSUPPORTED` when the sessions store does not implement the optional
+`deleteExpiredSessions` — a store with its own TTL, such as
+`@nxgt/janus-mongo`'s, does not. The reference store implements it.
+
+## Testing expiry
+
+`fixedClock` is shipped for this:
+
+```ts
+import { expect, it } from 'bun:test';
+import { z } from 'zod';
+import { createMemoryStores, fixedClock, janus, scryptHasher } from '@nxgt/janus';
+
+it('lapses after seven days', async () => {
+	const clock = fixedClock(Date.UTC(2026, 0, 1));
+	const auth = janus({
+		user: z.object({ email: z.email() }),
+		password: { login: 'email' },
+		store: createMemoryStores(),
+		hasher: scryptHasher({ cost: 10 }), // fast in tests; keep the default in production
+		clock,
+	});
+	const { token } = await auth.signUp({ email: 'ada@example.com', password: 'correct horse' });
+	const bearer = { authorization: `Bearer ${token}` };
+
+	clock.advance(8 * 24 * 60 * 60 * 1000);
+
+	expect(await auth.authenticate(bearer)).toBeNull();
+});
+```
+
+## What is stored
+
+The token is 32 random bytes, handed back once in `SignedIn` and
+`Authenticated`. The store holds only its `sha256`, so a dump of the store
+cannot be replayed. `Session` is the stored record without that hash: `id`,
+`userId`, `authenticatedAt`, `expiresAt`, `revokedAt`, `createdAt`.
+
+## See also
+
+- [Users](users.md) — `signUp`, `signIn`, the configuration
+- [E-mail flows](email-flows.md) — verification and password reset
+- [Errors](errors.md) — `STORE_FAILED`, `UNSUPPORTED` and the rest