@nxgt/janus 0.1.0

package/docs/guide/users.md

@@ -0,0 +1,277 @@
+# Users — `janus()`
+
+This page is for wiring `janus()` and managing users with it: the
+configuration, one or several kinds of user, and every method a user type
+answers. Sessions have [their own page](sessions.md), and so do the
+[e-mail flows](email-flows.md) and [password hashing](passwords.md).
+
+```ts
+import { z } from 'zod';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+
+const User = z.object({ email: z.email(), name: z.string() });
+
+export const auth = janus({
+	user: User,
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+const { user, session, token } = await auth.signUp({
+	email: 'ada@example.com',
+	name: 'Ada Lovelace',
+	password: 'correct horse',
+});
+user.email;        // the schema's own field, at the top level
+user.type;         // 'user'
+session.expiresAt; // Date
+token;             // handed back once: the store holds only its sha256
+```
+
+`createMemoryStores()` is the reference store, for tests and for trying the
+package. In production, pass an adapter's stores, such as
+`createMongoStores(db)` from `@nxgt/janus-mongo`.
+
+```ts
+function janus<const C extends JanusConfig>(config: C & Checked<C>): Janus<C>;
+```
+
+`janus()` is **synchronous and does no I/O**. It checks that every store
+answers every method of the port, and connects to nothing. A configuration it
+cannot use is refused with a bare `TypeError` at that call, before any request
+arrives.
+
+## What a user is
+
+A user is **your schema's fields at the top level**, plus what `janus` sets:
+
+```ts
+interface UserBase<Type extends string = string> {
+	readonly id: Id;               // a UUIDv7 the core minted
+	readonly type: Type;           // 'user', or the name you gave the type
+	readonly emailVerified: boolean;
+	readonly active: boolean;
+	readonly hasPassword: boolean; // the hash itself never reaches a user
+	readonly version: number;      // one more on every write
+	readonly createdAt: Date;
+	readonly updatedAt: Date;
+}
+type User<Type extends string = string, Fields = object> = Readonly<Fields> & UserBase<Type>;
+```
+
+A schema that declares one of those keys, or `password`, is refused at compile
+time. A schema is any [Standard Schema](https://standardschema.dev) (Zod 4,
+Valibot, ArkType), and its output must be JSON: a schema that produces a
+`Date` is refused at compile time, because a `Date` round-trips through one
+database and not the next. An optional field left `undefined` is dropped
+before the store sees it.
+
+## Options
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `user` | Standard Schema | — | One kind of user, named `'user'`. Exactly one of `user` and `users` |
+| `users` | `{ [type]: UserTypeConfig }` | — | Several kinds of user. See [Several kinds of user](#several-kinds-of-user) |
+| `password.login` | a field name | — | The field users sign in with: a **top-level, required string** field. A typo is a compile error |
+| `password.normalize` | `'none' \| 'lowercase' \| 'lowercaseTrim' \| 'nfkcLowercaseTrim' \| (value) => string` | `'lowercaseTrim'` | Applied to the login before any store sees it, at sign-up and at sign-in alike |
+| `password.minLength` | integer ≥ 1 | `8` | Below it: `PASSWORD_TOO_SHORT` |
+| `email` | a field name | `'email'` | The field `verifyEmail` and `resetPassword` send to. Without one, those flows are absent from the type |
+| `session.lifespan` | `Duration` | `'7d'` | How long a session lives |
+| `session.renewAfter` | `Duration \| false` | `'1d'` | When `authenticate` slides the session. `false` for a fixed lifespan |
+| `schemaVersion` | string | `'1'` | Recorded on every user written. Bump it when the schema tightens |
+| `store` | `JanusStores` | — | Required. `createMemoryStores()` or an adapter's |
+| `relations` | `RelationStore` | — | The permission store. Wired here, deleting a user deletes every tuple naming them |
+| `hasher` | `PasswordHasher` | — | Required as soon as a type has a password. No silent fallback |
+| `verifiers` | `PasswordHasher[]` | `[]` | Hashers that only verify: those older hashes were written with |
+| `clock` | `Clock` | `systemClock` | `fixedClock()` in tests |
+| `cookie` | `CookieConfig` | strict | See [sessions](sessions.md#the-cookie) |
+| `tokens.verifyEmail` | `Duration` | `'24h'` | How long a verification token lives |
+| `tokens.resetPassword` | `Duration` | `'1h'` | How long a reset token lives |
+
+A `Duration` is `'500ms'`, `'30s'`, `'15m'`, `'8h'`, `'7d'`, or a number of
+milliseconds.
+
+### `password.login` is checked at compile time
+
+```ts
+janus({
+	user: z.object({ email: z.email(), nickname: z.string().optional() }),
+	// @ts-expect-error — on login: '"emial" is not a required string field; name one of' 'email'
+	password: { login: 'emial' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+```
+
+`nickname` is not offered either: a login read from an optional field is a user
+who may have no way to sign in.
+
+### `password.normalize`
+
+```ts
+janus({
+	user: z.object({ username: z.string() }),
+	password: { login: 'username', normalize: 'none' }, // 'Grace' and 'grace' are two users
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+```
+
+A function is accepted, and must be deterministic: the same rule normalises
+at sign-up and at sign-in. An e-mail used by the e-mail flows is always
+compared lower-cased and trimmed, whatever the login's rule.
+
+## Several kinds of user
+
+```ts
+const Patient = z.object({ email: z.email(), birthDate: z.string() });
+const Staff = z.object({ username: z.string(), service: z.string() });
+
+export const clinic = janus({
+	users: {
+		patient: { schema: Patient, password: { login: 'email' } },
+		staff: {
+			schema: Staff,
+			password: { login: 'username', normalize: 'none', minLength: 12 },
+			session: { lifespan: '8h', renewAfter: false },
+		},
+	},
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+await clinic.patient.signUp({ email: 'p@example.com', birthDate: '1990-01-01', password: 'correct horse' });
+await clinic.staff.signIn({ username: 'grace', password: 'a long passphrase' });
+clinic.types; // readonly ('patient' | 'staff')[]
+
+const current = await clinic.authenticate(request);
+if (current?.user.type === 'staff') current.user.service; // narrowed by type
+```
+
+Each type carries `schema` and, optionally, `password`, `email`, `session`
+and `schemaVersion`, with the defaults above. A login is unique **per type**:
+the same e-mail may hold a patient account and a staff account. A type name is
+camelCase, and may not be one of `janus()`'s own methods (`authenticate`,
+`signOut`, `signOutEverywhere`, `findUser`, `getUser`, `cookie`,
+`collectExpired`, `types`) — a compile error, and a `TypeError` for a
+JavaScript caller.
+
+## What each user type answers
+
+In the one-type form these are on `auth` itself; with several types, on
+`clinic.patient`, `clinic.staff`.
+
+| Method | Answers | Rejects with |
+| --- | --- | --- |
+| `create(fields & { password?, active? })` | the user; no session | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `LOGIN_TAKEN` |
+| `find(id)` | the user, or `null` — for a malformed id, an unknown one, or one of another type | |
+| `get(id)` | the user | `NOT_FOUND` |
+| `list({ after?, limit? })` | `CursorPage<User>`, in creation order | `INVALID_CURSOR` |
+| `update(user, patch, { ifVersion? })` | the user as written | `USER_INVALID`, `LOGIN_TAKEN`, `VERSION_CONFLICT`, `NOT_FOUND` |
+| `setActive(user, active, { ifVersion? })` | the user as written | `VERSION_CONFLICT`, `NOT_FOUND` |
+| `delete(user)` | `true`, or `false` for an unknown id or one of another type | |
+
+With a `password`, besides:
+
+| Method | Answers | Rejects with |
+| --- | --- | --- |
+| `signUp(fields & { password })` | `{ user, session, token }` | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `LOGIN_TAKEN` |
+| `signIn({ [login]: string, password })` | `{ user, session, token }` | `CREDENTIALS_INVALID`, `USER_INACTIVE`, `HASH_UNSUPPORTED` |
+| `findByLogin(login)` | the user, or `null`; the login is normalised first | |
+| `setPassword(user, password, { ifVersion? })` | the user — an admin's call | `PASSWORD_TOO_SHORT` |
+| `changePassword(user, { current, next }, { ifVersion? })` | the user — the user's own call | `CREDENTIALS_INVALID`, `PASSWORD_TOO_SHORT` |
+
+Every method may also reject with `STORE_FAILED`. A `user` argument is a user
+or its id (`UserRef = string | { id: string }`).
+
+```ts
+const grace = await auth.create({ email: 'grace@example.com', name: 'Grace', active: false });
+await auth.find(grace.id);                         // User | null
+await auth.get(grace.id);                          // User, or NOT_FOUND
+const renamed = await auth.update(grace, { name: 'Grace Hopper' }, { ifVersion: grace.version });
+await auth.setActive(renamed, true);
+await auth.findByLogin('  GRACE@example.com ');    // found: normalised as sign-up normalised it
+await auth.setPassword(renamed, 'a new password');
+await auth.changePassword(renamed, { current: 'a new password', next: 'another password' });
+await auth.delete(renamed);                        // true
+```
+
+### `update` merges, then validates the whole
+
+The patch is spread over the stored fields and the result is checked against
+the schema, so a patch can never leave a user the schema would refuse.
+Changing the e-mail sets `emailVerified` back to `false`, and moves the login
+with it when the e-mail is the login.
+
+### `ifVersion`
+
+Every write but `delete` takes `{ ifVersion }`. A user who changed since you
+read them is `VERSION_CONFLICT`, and nothing is written: read again and retry.
+A sign-in that rewrites a stale password hash moves `version` too, so an object
+read before that sign-in conflicts — see [passwords](passwords.md#rehash-on-sign-in).
+
+### `delete`
+
+Deletes the user **with every session and one-time token they had**, and
+every tuple naming them when `relations` is wired. The user goes first, so an
+outage half-way leaves only sessions and tokens that authenticate nobody. It is
+idempotent: calling it again finishes the job.
+
+### Paging every user
+
+```ts
+let cursor: string | null = null;
+do {
+	const page = await auth.list({ after: cursor, limit: 100 });
+	for (const user of page.items) console.log(user.email);
+	cursor = page.nextCursor;
+} while (cursor);
+```
+
+`limit` defaults to 20 and is capped at 100. There is no `total`.
+
+### Across types
+
+`findUser(id)` and `getUser(id)` are on the instance itself and find a user
+whatever their type; the answer is a union narrowed by `user.type`.
+
+## A sign-up route
+
+A fetch-style handler — the shape Bun, Hono and most frameworks hand you:
+
+```ts
+import { JanusError } from '@nxgt/janus';
+
+export async function signUpRoute(request: Request): Promise<Response> {
+	const body = (await request.json()) as { email: string; name: string; password: string };
+	try {
+		const { user, session, token } = await auth.signUp(body);
+		return Response.json(
+			{ id: user.id },
+			{ status: 201, headers: { 'Set-Cookie': auth.cookie.serialize(token, session) } },
+		);
+	} catch (error) {
+		if (!(error instanceof JanusError)) throw error;
+		switch (error.code) {
+			case 'USER_INVALID':
+				return Response.json({ issues: error.issues }, { status: 400 });
+			case 'PASSWORD_TOO_SHORT':
+				return Response.json({ minLength: error.minLength }, { status: 400 });
+			case 'LOGIN_TAKEN':
+				return Response.json({ error: 'taken' }, { status: 409 });
+			default:
+				throw error; // STORE_FAILED: your 503
+		}
+	}
+}
+```
+
+Validate the body's shape yourself in a real route; `janus` validates the
+fields against your schema, not that `password` is a string.
+
+## See also
+
+- [Sessions](sessions.md) — `authenticate`, the cookie, signing out
+- [Errors](errors.md) — every code, and the status it deserves
+- [Writing an adapter](adapters.md) — the store port behind `store`

package/docs/guide/vocabulary.md

@@ -0,0 +1,163 @@
+# The shared vocabulary
+
+This page is for the small pieces `@nxgt/janus` exports beside `janus()` and
+the permissions, because both use them: subjects and the tuple notation, ids,
+pagination, durations and clocks. All of it is imported from `@nxgt/janus`.
+
+```ts
+import { formatTuple, mintId, parseDuration, subjectOf } from '@nxgt/janus';
+
+const user = { type: 'staff', id: mintId(), username: 'grace' };
+
+subjectOf(user); // { type: 'staff', id: '…' }: the user IS the subject
+formatTuple({
+	object: { type: 'record', id: 'r1' },
+	relation: 'viewer',
+	subject: { type: 'team', id: 't1', relation: 'member' },
+}); // 'record:r1#viewer@team:t1#member'
+parseDuration('8h', 'session.lifespan'); // 28800000
+```
+
+## Subjects and the tuple notation
+
+```ts
+interface Entity { readonly type: string; readonly id: string }
+interface SubjectSet extends Entity { readonly relation: string } // every `relation` of an entity
+type Subject = Entity | SubjectSet;
+interface RelationTuple { readonly object: Entity; readonly relation: string; readonly subject: Subject }
+```
+
+**Subjects are typed**: `{ type, id }` for one entity, `{ type, id, relation }`
+for a subject set — every `member` of `team:t1`. `type` is the same word as a
+user's own, so a user id and a subject id are the same thing, and
+`subjectOf(user)` is the one-line join between the two halves of the package.
+It copies `type` and `id` only, so none of the user's own fields ever reaches
+a tuple.
+
+| Function | Answers |
+| --- | --- |
+| `subjectOf(user)` | `{ type, id }` of any object carrying both |
+| `isSubjectSet(subject)` | whether `relation` is a string |
+| `formatEntity(entity)` | `'record:r1'` |
+| `formatSubject(subject)` | `'staff:u1'`, or `'team:t1#member'` |
+| `formatTuple(tuple)` | `'record:r1#viewer@team:t1#member'` |
+| `parseSubject(text)` | the `Subject` back |
+| `parseTuple(text)` | the `RelationTuple` back |
+
+```ts
+import { isSubjectSet, parseSubject, parseTuple } from '@nxgt/janus';
+
+parseTuple('record:r1#viewer@staff:u1');
+// { object: { type: 'record', id: 'r1' }, relation: 'viewer', subject: { type: 'staff', id: 'u1' } }
+
+const subject = parseSubject('team:t1#member');
+if (isSubjectSet(subject)) subject.relation; // 'member'
+```
+
+The notation is for messages, logs and tests, not a wire format. No part may
+hold `@`, `#` or a parenthesis, and a type may not hold a `:`, so every string
+reads one way. `parseTuple` and `parseSubject` refuse anything else with a
+**bare `TypeError`** — including Keto's untyped subject, `record:r1#viewer@alice`,
+and the message says what a subject is. Nothing in this package reads a tuple
+off the network, so a malformed string came from your own code.
+
+## Ids
+
+```ts
+import { type Id, isId, mintedAt, mintId } from '@nxgt/janus';
+
+const id: Id = mintId(); // a UUIDv7
+isId(id);                // true
+isId('42');              // false: not an id this package could have minted
+mintedAt(id);            // the Date it was minted, to the millisecond
+```
+
+Ids are **minted by the core, not by the store**. They sort in creation order
+as strings, so a pagination cursor is simply the last id of a page. Ids are
+strictly increasing within a process: inside one millisecond a sequence orders
+them, and past 4096 in a millisecond the next millisecond is borrowed.
+
+- **`mintedAt` is not `createdAt`.** A borrowed millisecond, or a clock that
+  stepped backwards and was held rather than followed, makes it accurate to
+  the millisecond and no further.
+- **`mintId(now)` steers ids forward, never back.** Passing a `now` earlier
+  than an id already minted in this process holds the last one and keeps
+  counting, because a decreasing id would break the cursor. A test that needs
+  a fixed instant wants `fixedClock`, not this argument.
+
+The price for an adapter: it cannot reuse an existing numeric primary key. It
+stores a `uuid` column, or a 36-character string.
+
+## Pagination
+
+```ts
+import { type CursorPage, DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, invalidCursor, pageLimit } from '@nxgt/janus';
+
+interface CursorPage<T> {
+	readonly items: readonly T[];
+	readonly nextCursor: string | null; // null on the last page, never undefined
+}
+
+pageLimit(undefined, 'listThings'); // 20 — DEFAULT_PAGE_SIZE
+pageLimit(500, 'listThings');       // 100 — MAX_PAGE_SIZE, the cap
+pageLimit(0, 'listThings');         // TypeError: listThings: limit must be an integer of at least 1, or absent
+```
+
+There is **no `total`**: a count over a cursor-paged collection is a second
+query whose answer is stale by the time you read it. `while (cursor)` is the
+loop:
+
+```ts
+let cursor: string | null = null;
+do {
+	const page = await auth.list({ after: cursor, limit: 100 });
+	cursor = page.nextCursor;
+} while (cursor);
+```
+
+`invalidCursor(where, cursor)` builds the `INVALID_CURSOR` error an adapter
+throws for a cursor it did not mint — never a silent first page, which would
+make a caller paging a list loop for ever. The message holds the cursor's
+length, not its bytes.
+
+## Durations
+
+```ts
+type Duration = number | `${number}${'ms' | 's' | 'm' | 'h' | 'd'}`;
+```
+
+```ts
+import { parseDuration } from '@nxgt/janus';
+
+parseDuration('15m', 'tokens.resetPassword'); // 900000
+parseDuration(1500, 'session.renewAfter');    // 1500 — a number is milliseconds
+```
+
+Every duration option of `janus()` takes this. `'2w'` is a compile error; a
+value the type cannot see through — from an environment variable, say — is a
+`TypeError` at run time, and the second argument names the option in its
+message. One gap is known and written down: `'30 m'`
+satisfies the type — TypeScript's `${number}` tolerates the space — and
+`parseDuration` refuses it at run time.
+
+## Clocks
+
+```ts
+import { type Clock, fixedClock, systemClock } from '@nxgt/janus';
+
+interface Clock { now(): Date }
+
+systemClock.now();                                   // the default
+const clock = fixedClock(Date.UTC(2026, 0, 1));      // a Date or milliseconds; 0 when absent
+clock.advance(60_000);
+clock.set(new Date('2026-02-01T00:00:00Z'));
+```
+
+`fixedClock` is **shipped, not test-only**: testing session expiry needs it,
+and so do your own tests. Pass it as `janus({ clock })` — see
+[sessions](sessions.md#testing-expiry).
+
+## See also
+
+- [Permissions](permissions.md) — where subjects and tuples are used
+- [Errors](errors.md) — the error classes, also exported from `@nxgt/janus`

package/docs/roadmap.md

@@ -0,0 +1,93 @@
+# Roadmap
+
+Where `@nxgt/janus` is heading. A direction, not a commitment: there are no
+dates here, and the version something shipped in is the only number.
+
+## Now
+
+Nothing in progress.
+
+## Next
+
+Nothing yet.
+
+## Later
+
+- **More official adapters** — the store port is cut where atomicity is not
+  required, so users, sessions and permission tuples can each live in the
+  database that suits them. MongoDB is the first adapter
+  ([`@nxgt/janus-mongo`](https://www.npmjs.com/package/@nxgt/janus-mongo)).
+- **A Redis adapter for sessions and tokens** — both are ephemeral and read on
+  every request, which is why the port gives them slots of their own: they can
+  live in Redis, with a native expiry, while users stay in another store.
+
+## Not planned
+
+- **`moduleResolution: "nodenext"`** — the package, its sources and its
+  emitted declarations import without extensions, and resolve as Bun and every
+  bundler do. Rewriting the declarations for `nodenext` was tried and reverted:
+  it breaks the same contract one step later. Use `"moduleResolution":
+  "bundler"`.
+- **A Kratos-shaped surface** — no `identity.traits`, no identifier derived
+  from a schema annotation. A user is your schema's fields at the top level,
+  and the flows are calls (`signUp`, `signIn`, `authenticate`).
+- **`snake_case` keys** — every key, option and record field is `camelCase`,
+  and a lint rule holds it. Error codes are `SCREAMING_SNAKE` because they are
+  values, not keys.
+- **Emitting a Kratos identity schema** — it would bring Ory's `snake_case`
+  vocabulary into this package. If it ever exists, it is a separate package
+  whose job is to speak that format.
+- **A `total` on `CursorPage`** — a count over a cursor-paged collection is a
+  second query, stale by the time you read it. `nextCursor` is the loop.
+- **Store-assigned or numeric ids** — ids are UUIDv7 minted by the core, so
+  they sort in creation order, the cursor is the last id, and an insert is
+  idempotent under retry. An adapter cannot reuse an existing numeric key.
+- **A required validation library** — schemas are any Standard Schema (Zod 4,
+  Valibot, ArkType); none is imposed as a peer.
+- **A silent hasher fallback** — a user type with a password and no `hasher`
+  is refused at wiring, rather than hashed with something you did not choose.
+- **Answering `null` or `false` on an outage** — a store that cannot answer
+  throws `STORE_FAILED`, and a permission walk past `maxDepth` throws
+  `PERMISSION_DEPTH`. Neither will become a denial: that turns an outage into
+  a silent lockout.
+- **Zanzibar's infrastructure** — no consistency tokens, no distributed
+  cache. The tuples live in your own database, so a read already follows a
+  write.
+- **Deciding between 404 and 403** — `can()` answers one question; what a
+  route reveals about an object it refuses is the application's decision.
+
+## Shipped
+
+The first public release, v0.1.
+
+- **The model decides what a stored tuple grants** — `can()` and `list()` follow
+  only the holders a relation admits, as `grant()` writes only those: a tuple
+  stored past `grant()`, by an older model or by hand, grants nothing. — v0.1
+- **Guides and troubleshooting pages** — a `docs/` folder shipped in the
+  package: detailed guides with examples, and the errors you can meet, each
+  with its cause and fix. — v0.1
+- **Permissions at `@nxgt/janus/permissions`** — and `janus({ relations })`,
+  so deleting a user also deletes every tuple naming them. — v0.1
+- **`list()`** — the ids of every object a subject holds a permission on, as a
+  cursor page, `fromField` relations included through their `lookup`. — v0.1
+- **`can()`, `grant()` and `revoke()`** — a permission check that answers
+  `true` or `false` and throws on an outage, and tuple writes refused at
+  compile time when the model does not admit them. — v0.1
+- **Typed subjects and the `RelationStore` port** — `{ type, id }` subjects,
+  the tuple notation, `createMemoryRelations()`, and
+  `describeRelationStores` for adapter authors. — v0.1
+- **A permission model typed from itself** — `defineModel` with subject sets,
+  arrows, `fromField` relations read from your data, and `when` conditions
+  written in TypeScript. — v0.1
+- **Delete a user, and everything of theirs** — `delete(user)` removes the
+  user with every session and one-time token they had, idempotently. — v0.1
+- **Rehash a stale password on sign-in** — moving hashers, or raising a cost,
+  reaches every active user with no migration to run. — v0.1
+- **`janus()`** — sign-up, sign-in, sessions, e-mail verification and password
+  reset, with several user types in one instance, typed from your schemas.
+  — v0.1
+- **The conformance suite** — `@nxgt/janus/conformance`, the suite an adapter
+  runs, outages included. — v0.1
+- **The store port and its in-memory reference** — `JanusStores` and
+  `createMemoryStores()`, for your tests and as the model for an adapter.
+  — v0.1