@nxgt/janus 0.1.0

package/docs/guide/adapters.md

@@ -0,0 +1,296 @@
+# Writing an adapter — the store port and `@nxgt/janus/conformance`
+
+This page is for putting `janus()` or `permissions()` on a database of your
+choice: the two ports you implement, the rules they carry, and the conformance
+suites that check an implementation keeps them. If you only use an existing
+adapter, such as `@nxgt/janus-mongo`, you do not need it.
+
+```ts
+import { describe, it } from 'bun:test';
+import { describeJanusStores } from '@nxgt/janus/conformance';
+
+// Yours: myStores(db) builds your adapter's stores, freshDatabase() an empty
+// database with a way to make one command fail.
+describeJanusStores({
+	name: 'my adapter',
+	runner: { describe, it },
+	harness: {
+		async open() {
+			const db = await freshDatabase(); // one per case, never shared
+			return {
+				stores: myStores(db),
+				faults: { fail: (slot, method) => db.failNext(method) },
+				close: () => db.drop(),
+			};
+		},
+	},
+});
+```
+
+## The two ports
+
+| Port | Taken by | Methods |
+| --- | --- | --- |
+| `JanusStores` — `{ users: UserStore, sessions: SessionStore, tokens: TokenStore }` | `janus({ store })` | 6 + 6 (+ 1 optional) + 3 |
+| `RelationStore` | `permissions({ store })`, `janus({ relations })` | 6 |
+
+They are separate on purpose: an application that only authenticates
+implements nothing for permissions, and each of the three user slots may come
+from a different adapter — users in one database, sessions and tokens in
+another:
+
+```ts
+janus({
+	user: User,
+	password: { login: 'email' },
+	store: { users: mongo.users, sessions: other.sessions, tokens: other.tokens },
+	hasher: scryptHasher(),
+});
+```
+
+The seam is where atomicity is not required: a user and their password are one
+record, a session is derived state, a token is ephemeral.
+
+### `UserStore`
+
+```ts
+interface UserStore {
+	insertUser(record: UserRecord): Promise<UserRecord>;
+	findUser(id: Id): Promise<UserRecord | null>;
+	findUserByLogin(type: string, login: string): Promise<UserRecord | null>;
+	listUsers(page: UserPageRequest): Promise<CursorPage<UserRecord>>;
+	updateUser(id: Id, patch: UserPatch, ifVersion: number): Promise<UserRecord>;
+	deleteUser(id: Id): Promise<boolean>;
+}
+```
+
+- `insertUser` is **idempotent under retry**: a user with this `id` already
+  stored is answered as stored. A login held by another user of the same type
+  rejects with `StoreConflict('login', …)`, from the database's own unique
+  constraint.
+- `updateUser` writes **only if the stored version is exactly `ifVersion`**,
+  and never replaces a record whole: a field the patch does not name is left
+  as it is. It rejects with `NotFoundError` for an unknown id — the one
+  absence on the port that throws, because an update always follows a read —
+  and `StoreConflict('version', …)` when the version moved.
+- `listUsers` pages in ascending id order; `after` is the last id of the
+  previous page, already checked by the core.
+
+### `SessionStore` and `TokenStore`
+
+```ts
+interface SessionStore {
+	insertSession(record: SessionRecord): Promise<void>;
+	findSessionByTokenHash(tokenHash: string): Promise<SessionRecord | null>;
+	extendSession(id: SessionId, expiresAt: Date): Promise<SessionRecord | null>; // null once revoked
+	revokeSession(id: SessionId, at: Date): Promise<boolean>;
+	revokeUserSessions(userId: Id, at: Date, except?: SessionId): Promise<number>;
+	deleteUserSessions(userId: Id): Promise<number>;
+	deleteExpiredSessions?(before: Date): Promise<number>; // optional: omit it if the database expires on its own
+}
+
+interface TokenStore {
+	insertToken(record: TokenRecord): Promise<void>;
+	consumeToken(tokenHash: string, kind: TokenKind, at: Date): Promise<TokenRecord | null>;
+	deleteUserTokens(userId: Id): Promise<number>;
+}
+```
+
+`consumeToken` is the most important method on the port: it spends the token
+and answers it **as it was before the call**, in **one conditional write**.
+Twenty concurrent calls must produce exactly one answer with `spentAt: null`;
+in MongoDB that is one `findOneAndUpdate` returning the document before the
+update. A read followed by a write lets two requests redeem one reset code.
+
+Expiry is the core's decision: a read answers a stored session verbatim,
+lapsed or revoked, and never a record it has changed.
+
+### `RelationStore`
+
+```ts
+interface RelationStore {
+	write(changes: { add?: readonly RelationTuple[]; remove?: readonly RelationTuple[] }): Promise<void>;
+	has(tuple: RelationTuple): Promise<boolean>;
+	findSubjectSets(object: Entity, relation: string): Promise<readonly SubjectSet[]>;
+	findEntities(object: Entity, relation: string): Promise<readonly Entity[]>;
+	findObjects(page: ObjectPageRequest): Promise<CursorPage<string>>;
+	deleteEntity(entity: Entity): Promise<number>;
+}
+```
+
+One-hop questions about stored tuples, never a permission: the traversal is
+the core's. `write` is **all or nothing**, removals first, and idempotent.
+`findObjects` is the reverse index `list()` walks, in ascending id order.
+`deleteEntity` removes every tuple naming the entity as object, as subject,
+and as the entity of a subject set.
+
+## The six rules
+
+Written on the port's types, and checked by the suites:
+
+1. **An absence is `null`. A failure throws.** A method that can find nothing
+   answers `null`, `false`, `0` or an empty page; everything else throws,
+   preferably `StoreFailure` with the driver's error as `cause`. Never write
+   `try { … } catch { return null }` in an implementation.
+2. **`null`, not `undefined`.** A function that forgot to `return` produces
+   `undefined`; `null` has to be written on purpose.
+3. **Uniqueness is a constraint** — a unique index, never a read followed by a
+   write.
+4. **Bytes round-trip.** No normalising, trimming or retyping. The core
+   normalises logins before a store sees them.
+5. **Every method is atomic on its own.** The core opens no transaction; an
+   adapter may open one inside a method.
+6. **Schema management is not on the port.** Expose your own `sync`; the core
+   never calls it.
+
+```ts
+import { type Id, StoreFailure, type UserRecord, type UserStore } from '@nxgt/janus';
+
+export const findUser: UserStore['findUser'] = async (id: Id) => {
+	let found: UserRecord | undefined;
+	try {
+		found = await db.users.findOne({ _id: id });
+	} catch (cause) {
+		throw new StoreFailure('users.findUser: the store could not answer', {
+			slot: 'users',
+			operation: 'findUser',
+			cause,
+		});
+	}
+	return found ?? null; // an absence, written on purpose
+};
+```
+
+An adapter **defines no error class**. It throws `@nxgt/janus`'s own
+`StoreFailure`, `StoreConflict` and `NotFoundError`, and declares
+`@nxgt/janus` as a **peer dependency**, never a dependency, so there is one
+copy of each class and `instanceof` holds in the application. A cursor it
+cannot read is `invalidCursor(where, cursor)`. Records, patches and page
+requests are exported as types: `UserRecord`, `UserPatch`, `UserPageRequest`,
+`PasswordRecord`, `SessionRecord`, `TokenRecord`, `TokenKind`, `Json`,
+`JsonObject`, and `ObjectPageRequest`, `RelationChanges` from
+`@nxgt/janus/permissions`.
+
+`createMemoryStores()` and `createMemoryRelations()` are the reference
+implementations: read them when a rule is unclear. `janus()` runs
+`assertStores` on what it is given, and a partially implemented store is a
+compile error naming the missing method.
+
+## The conformance suites
+
+| Suite | Cases | Harness opens |
+| --- | --- | --- |
+| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 37: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" | `{ stores, faults?, close? }` |
+| `describeRelationStores({ name, harness, runner?, faults?, skip? })` | 15: the relation store, and one outage per method | `{ store, faults?, close? }` |
+
+`harness.open()` is called **once per case** and must answer fresh, empty
+stores: a case that leaks into the next is the hardest failure to debug.
+`close()` runs after the case, pass or fail.
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `name` | string | — | The suite's title |
+| `harness` | `ConformanceHarness` / `RelationHarness` | — | Opens fresh stores per case |
+| `runner` | `{ describe, it }` | `globalThis` | **Required under `bun test`**: Bun does not put `describe` and `it` on `globalThis`. jest, and vitest with `globals: true`, are found without it |
+| `faults` | boolean | — | Declare `false` up front and the report says so in the suite's title |
+| `skip` | `{ [caseId]: reason }` | `{}` | Skips a case, reported with the reason — never silent |
+
+The suites import no test framework and no assertion library.
+
+### `faults`: prove the outage invariant
+
+`faults` is optional, and **its absence is reported, never passed over**:
+without it the outage cases are skipped with the reason *"faults not provided:
+the outage invariant is not proven for this adapter"*.
+
+```ts
+import type { StoreFaults } from '@nxgt/janus/conformance';
+
+const faults: StoreFaults = {
+	async fail(slot, method) {
+		await database.failNext(method); // make the DATABASE fail this call
+	},
+};
+```
+
+Make the database fail the way it really fails — for MongoDB, the
+`failCommand` fail point with code 91 (`ShutdownInProgress`). A wrapper that
+throws in front of your adapter proves the wrapper, not the adapter's
+translation of a driver error. Fail **only the method named**: the write
+outage cases read the store back afterwards, to prove a rejected write changed
+nothing.
+
+The relation suite's `faults` is `{ fail(method) }`, with no slot:
+
+```ts
+import { describeRelationStores } from '@nxgt/janus/conformance';
+
+describeRelationStores({
+	name: 'my adapter',
+	runner: { describe, it },
+	harness: {
+		async open() {
+			const database = await freshDatabase();
+			return {
+				store: myRelations(database),
+				faults: { fail: (method) => database.failNext(method) },
+				close: () => database.drop(),
+			};
+		},
+	},
+});
+```
+
+### Skipping a case, and declaring no faults
+
+```ts
+describeJanusStores({
+	name: 'my adapter',
+	runner: { describe, it },
+	faults: false,
+	skip: { 'users.omission': 'not yet: tracked in the issue tracker' },
+	harness: {
+		async open() {
+			const database = await freshDatabase();
+			return { stores: myStores(database), close: () => database.drop() };
+		},
+	},
+});
+```
+
+A skipped case still appears in the run, with its reason in its name. A case
+that cannot run on the stores it was given — an outage case with no `faults`,
+`collectExpired` on a store without `deleteExpiredSessions` — passes, and
+emits a `JANUS_CONFORMANCE_SKIPPED` warning with the reason.
+
+### Without a test runner
+
+The cases are data, and `runCase` runs one against a harness:
+
+```ts
+import { allCases, referenceHarness, runCase } from '@nxgt/janus/conformance';
+
+for (const conformanceCase of allCases) {
+	const outcome = await runCase(conformanceCase, referenceHarness());
+	console.log(conformanceCase.id, 'skipped' in outcome ? `skipped: ${outcome.skipped}` : 'passed');
+}
+```
+
+| Export | What it is |
+| --- | --- |
+| `allCases`, `userStoreCases`, `sessionStoreCases`, `tokenStoreCases`, `outageCases` | The user-port cases, as `ConformanceCase` objects with a stable `id` |
+| `runCase(case, harness)` | Runs one; throws on failure, answers `{ passed: true }` or `{ skipped }` |
+| `SKIP_REASONS` | The reasons the suite gives itself |
+| `allRelationCases`, `relationStoreCases`, `relationOutageCases`, `runRelationCase` | The same for the relation port |
+| `referenceHarness()`, `referenceRelationHarness()` | The suites against the reference stores: the examples to copy |
+
+Types: `ConformanceHarness`, `OpenedStores`, `StoreFaults`, `ConformanceCase`,
+`CaseContext`, `ConformanceRunner`, `PortMethod`, and `RelationHarness`,
+`OpenedRelations`, `RelationFaults`, `RelationCase`, `RelationContext`,
+`RelationMethod`.
+
+## See also
+
+- [Errors](errors.md) — `StoreFailure`, `StoreConflict` and the rule behind them
+- [Vocabulary](vocabulary.md) — ids, cursors and `invalidCursor`
+- `@nxgt/janus-mongo` — an adapter that passes both suites against a real mongod, outages included

package/docs/guide/email-flows.md

@@ -0,0 +1,146 @@
+# E-mail verification and password reset
+
+This page is for the two one-time-token flows: proving a user holds their
+e-mail, and resetting a forgotten password. `janus` issues and redeems the
+tokens; **sending the e-mail is yours**.
+
+```ts
+import { z } from 'zod';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+
+async function sendMail(to: string, link: string): Promise<void> {
+	// your mailer
+}
+
+const auth = janus({
+	user: z.object({ email: z.email(), name: z.string() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+const { user } = await auth.signUp({ email: 'ada@example.com', name: 'Ada', password: 'correct horse' });
+
+const sent = await auth.verifyEmail.send(user); // { token, email, expiresAt }
+await sendMail(sent.email, `https://app.example/verify?token=${sent.token}`);
+
+// when the link is followed: the token comes back from the query string
+const verified = await auth.verifyEmail.confirm(sent.token);
+verified.emailVerified; // true
+```
+
+## Which types have these flows
+
+`verifyEmail` exists on a type with an e-mail field: the one `email` names, or
+a required string field called `email`. `resetPassword` needs an e-mail **and**
+a password. On a type without them the flows are **absent from its type**, not
+failing at run time:
+
+```ts
+const clinic = janus({
+	users: {
+		staff: { schema: z.object({ username: z.string() }), password: { login: 'username' } },
+		patient: { schema: z.object({ contact: z.email() }), password: { login: 'contact' }, email: 'contact' },
+	},
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+clinic.patient.verifyEmail.send; // exists: `email` names the field
+// @ts-expect-error — staff has no e-mail, so no verifyEmail
+clinic.staff.verifyEmail;
+```
+
+## Options
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `email` | a field name | `'email'` | The field the tokens are sent to, per type |
+| `tokens.verifyEmail` | `Duration` | `'24h'` | How long a verification token lives |
+| `tokens.resetPassword` | `Duration` | `'1h'` | How long a reset token lives |
+
+## `verifyEmail`
+
+```ts
+readonly verifyEmail: {
+	send(user: UserRef): Promise<IssuedToken>; // { token, email, expiresAt }
+	confirm(token: string): Promise<User>;
+};
+```
+
+`send` issues a token for the user's **current** e-mail. `confirm` redeems it
+and sets `emailVerified`. A token sent to an e-mail the user has since changed
+is `TOKEN_STALE`: confirming it would verify an address nobody holds any more.
+Changing the e-mail with `update` sets `emailVerified` back to `false`.
+
+## `resetPassword`
+
+```ts
+readonly resetPassword: {
+	request(email: string): Promise<(IssuedToken & { user: User }) | null>;
+	confirm(token: string, password: string): Promise<User>;
+};
+```
+
+`request` answers `null` for an e-mail nobody holds. **Never tell the visitor
+which**: answer the same page either way.
+
+```ts
+export async function forgotPassword(request: Request): Promise<Response> {
+	const { email } = (await request.json()) as { email: string };
+	const issued = await auth.resetPassword.request(email);
+	if (issued !== null) {
+		await sendMail(issued.email, `https://app.example/reset?token=${issued.token}`);
+	}
+	return new Response(null, { status: 202 }); // the same answer either way
+}
+```
+
+`confirm` sets the password, marks the e-mail verified — the link proved it —
+and **signs the user out everywhere**. It opens no session: call `signIn` next
+if that is your policy. A password refused for its length does not spend the
+token, so the visitor can try again with the same link.
+
+```ts
+import { JanusError } from '@nxgt/janus';
+
+export async function resetPassword(request: Request): Promise<Response> {
+	const { token, password } = (await request.json()) as { token: string; password: string };
+	try {
+		await auth.resetPassword.confirm(token, password);
+		return new Response(null, { status: 204 });
+	} catch (error) {
+		if (!(error instanceof JanusError)) throw error;
+		switch (error.code) {
+			case 'TOKEN_UNKNOWN':
+			case 'TOKEN_SPENT':
+			case 'TOKEN_EXPIRED':
+			case 'TOKEN_STALE':
+				return Response.json({ error: 'link' }, { status: 400 });
+			case 'PASSWORD_TOO_SHORT':
+				return Response.json({ minLength: error.minLength }, { status: 400 });
+			default:
+				throw error; // STORE_FAILED: your 503
+		}
+	}
+}
+```
+
+## What a token refusal means
+
+| Code | When |
+| --- | --- |
+| `TOKEN_UNKNOWN` | No token holds that secret — or it was issued for the other flow: a verification token is not a reset token |
+| `TOKEN_SPENT` | Already redeemed. Every token is single use |
+| `TOKEN_EXPIRED` | Its lifespan passed. It is spent all the same, so it cannot be retried |
+| `TOKEN_STALE` | Sent to an e-mail the user no longer has |
+
+Of twenty concurrent redemptions of one token, exactly one succeeds: the store
+spends it in one conditional write. The store holds the token's `sha256`,
+never the token, and no refusal's message contains it.
+
+## See also
+
+- [Users](users.md) — `email`, `update`, and the other per-type methods
+- [Sessions](sessions.md) — `signOutEverywhere`, which `resetPassword.confirm` calls for you
+- [Errors](errors.md) — every code, and the status it deserves

package/docs/guide/errors.md

@@ -0,0 +1,146 @@
+# Errors
+
+This page is for turning what `@nxgt/janus` throws into a response: the error
+classes, every code, what each carries, and the one rule behind them. When you
+have an error message in hand and want its cause, see
+[troubleshooting](../troubleshooting.md).
+
+```ts
+import { JanusError, type JanusErrorCode } from '@nxgt/janus';
+
+export function statusOf(code: JanusErrorCode): number {
+	switch (code) {
+		case 'STORE_FAILED':
+			return 503;
+		case 'NOT_FOUND':
+			return 404;
+		case 'LOGIN_TAKEN':
+		case 'VERSION_CONFLICT':
+			return 409;
+		case 'USER_INVALID':
+		case 'PASSWORD_TOO_SHORT':
+		case 'HASH_UNSUPPORTED':
+		case 'INVALID_CURSOR':
+		case 'TOKEN_UNKNOWN':
+		case 'TOKEN_SPENT':
+		case 'TOKEN_EXPIRED':
+		case 'TOKEN_STALE':
+			return 400;
+		case 'CREDENTIALS_INVALID':
+			return 401;
+		case 'USER_INACTIVE':
+			return 403;
+		case 'UNSUPPORTED':
+			return 501;
+		case 'PERMISSION_DEPTH':
+			return 500;
+	}
+}
+
+export function toResponse(error: unknown): Response {
+	if (!(error instanceof JanusError)) throw error;
+	return Response.json({ code: error.code }, { status: statusOf(error.code) });
+}
+```
+
+`JanusErrorCode` is a union of sixteen string literals, so that `switch` is
+exhaustive: when a code is added, a function like `statusOf` stops compiling
+instead of answering `undefined`.
+
+## The one rule
+
+**An absence is `null`. A failure throws.** A call that can find nothing
+answers `null`, `false` or an empty page. A store that cannot answer — a
+refused connection, a timeout, a primary stepping down, a bug in the adapter —
+rejects with `STORE_FAILED`. Answer 503. Mapping it to a 404, to `null` or to
+`false` turns an outage into a silent lockout: everybody who has an account is
+told they do not.
+
+## Two kinds of refusal
+
+| Thrown | When | Class |
+| --- | --- | --- |
+| At **call** time, on a value that could have come from a request | a taken login, a wrong password, a spent token, an outage | a `JanusError` subclass, with a `code` |
+| At **wiring** time, from how you called the library | a lifespan that is not a duration, a store missing a method, a model with a loop, a malformed tuple string | a bare `TypeError` |
+
+No request handler should ever answer a `TypeError` — it is a bug in the code
+that wired the library, so no handler needs to tell it apart.
+
+## The codes
+
+| Code | Class | Status | When | Carries |
+| --- | --- | --- | --- | --- |
+| `STORE_FAILED` | `StoreFailure` | 503 | A store could not answer. **Never a negative answer** | `slot`, `operation`, `cause` |
+| `NOT_FOUND` | `NotFoundError` | 404 | `get`, `getUser`, or a write to a user who is gone. `find*` answers `null` instead | `userId` |
+| `LOGIN_TAKEN` | `StoreConflict` (`on: 'login'`) | 409 | Another user of the same type holds the login | `login`, `userType` |
+| `VERSION_CONFLICT` | `StoreConflict` (`on: 'version'`) | 409 | `ifVersion` no longer matches; nothing was written | `expectedVersion`, `actualVersion` |
+| `USER_INVALID` | `UserInvalidError` | 400 | The fields failed the schema | `issues`, field by field |
+| `PASSWORD_TOO_SHORT` | `CredentialError` | 400 | Below `password.minLength` | `minLength` — never the password |
+| `CREDENTIALS_INVALID` | `CredentialError` | 401 | Unknown login, no password, or the wrong one — **one code for the three** | `reason`, for your logs only |
+| `HASH_UNSUPPORTED` | `CredentialError` | 400 | A stored hash no wired hasher reads | `hashPrefix` — never the hash |
+| `USER_INACTIVE` | `UserInactiveError` | 403 | Deactivated; told only to someone who gave the right password | `userId` |
+| `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_STALE` | `TokenError` | 400 | See [e-mail flows](email-flows.md#what-a-token-refusal-means) | |
+| `INVALID_CURSOR` | `InvalidCursorError` | 400 | A cursor this store did not mint. Never a silent first page | |
+| `UNSUPPORTED` | `UnsupportedError` | 501 | The wired store lacks an optional capability — `collectExpired` without `deleteExpiredSessions` | `slot`, `operation` |
+| `PERMISSION_DEPTH` | `PermissionDepthError` | 500 | A check or list walked past `maxDepth`. **Not a denial** | `permission`, `maxDepth` |
+
+Every class extends `JanusError`, which extends `Error`, so no `catch` block
+needs ordering. Every field listed above is on `JanusError` itself, `undefined`
+when it does not apply.
+
+## Handling the ones that need care
+
+```ts
+import { CredentialError, JanusError, StoreFailure } from '@nxgt/janus';
+
+async function signIn(email: string, password: string): Promise<Response> {
+	try {
+		const { token } = await auth.signIn({ email, password });
+		return Response.json({ token });
+	} catch (error) {
+		if (error instanceof CredentialError && error.code === 'CREDENTIALS_INVALID') {
+			console.warn('sign-in refused', error.reason); // 'unknownLogin' | 'noPassword' | 'wrongPassword'
+			return Response.json({ error: 'invalid' }, { status: 401 });
+		}
+		if (error instanceof StoreFailure) return new Response(null, { status: 503 });
+		throw error;
+	}
+}
+```
+
+- **Never put `reason` in a response body.** `unknownLogin` tells an attacker
+  which accounts exist.
+- **`STORE_FAILED` is never a 401 or a 404.** Test for it before anything that
+  would read as "no".
+- **`VERSION_CONFLICT` is a retry**: read the user again, reapply, write with
+  the new `version`.
+- **`USER_INVALID`'s `issues`** have the schema's own paths
+  (`['address', 'city']`), so a form can show each next to its field.
+
+## No message holds a secret
+
+Not a password, not a hash, not a session token, not a token's hash, and not a
+connection URI — a connection string holds a password. A `login` may appear in
+a `LOGIN_TAKEN` message, because the caller just sent it. A message names the
+call you wrote (`signIn`, `users.findUser`) so you know where to look.
+
+## For adapter authors
+
+`StoreFailure` and `StoreConflict` are exported **because an adapter throws
+them**. An adapter defines no error class of its own, so `instanceof` holds
+across the two packages:
+
+```ts
+import { StoreConflict, StoreFailure } from '@nxgt/janus';
+
+throw new StoreFailure('users.findUser: the store could not answer', { slot: 'users', operation: 'findUser', cause });
+throw new StoreConflict('login', 'users.insertUser: the login is taken', { login, userType: 'user' });
+throw new StoreConflict('version', 'users.updateUser: the version moved', { expectedVersion: 3, actualVersion: 4 });
+```
+
+See [Writing an adapter](adapters.md).
+
+## See also
+
+- [Troubleshooting](../troubleshooting.md) — by the message you see
+- [Users](users.md) and [Sessions](sessions.md) — which method rejects with what