@nxgt/janus-mongo 0.1.0

package/dist/stores.d.ts

@@ -0,0 +1,37 @@
+import type { JanusStores } from '@nxgt/janus';
+import { type SyncOptions, type SyncReport } from '@nxgt/mongo';
+import type { Db } from 'mongodb';
+/**
+ * The three stores `janus()` takes, over one MongoDB database.
+ *
+ * ```ts
+ * const db = (await connectMongo(process.env.MONGO_URI)).db;
+ * await syncMongoStores(db); // a deployment step: creates the indexes
+ * const auth = janus({ user, password: { login: 'email' }, store: createMongoStores(db), hasher });
+ * ```
+ *
+ * **Reads go through `@nxgt/mongo`'s `find*`, never its `get*`.** `findById`
+ * answers `undefined` for an absence, so an absence arrives as a *value*,
+ * turned into `null` here, and everything that arrives as a rejection is a
+ * failure. There is no path on which an absence and an outage travel the same
+ * channel, so there is none on which a `catch` could confuse them.
+ *
+ * **Every conditional write is one driver call** on `raw`, the driver's own
+ * collection: `@nxgt/mongo` names no update conditioned on anything but its
+ * own lock, and the port needs `version`, `revokedAt` and `kind`.
+ *
+ * `sessions.deleteExpiredSessions` is not implemented: a TTL index drops lapsed
+ * sessions, so `sessions.collectExpired()` answers `UNSUPPORTED` — which is
+ * what the port asks of a store with its own expiry.
+ */
+export declare function createMongoStores(db: Db): JanusStores;
+/**
+ * Creates the three collections, their validators and their indexes, and says
+ * what it changed. Run it twice and the second run sends nothing.
+ *
+ * A deployment step, never a request-time one: it needs the `dbAdmin` role,
+ * and the core never calls it (rule 6). An application that deploys with
+ * `@nxgt/mongo`'s `syncAll(db)` already syncs these three with its own.
+ */
+export declare function syncMongoStores(db: Db, options?: SyncOptions): Promise<SyncReport[]>;
+//# sourceMappingURL=stores.d.ts.map

package/dist/stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../src/stores.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,WAAW,EAQX,MAAM,aAAa,CAAC;AAErB,OAAO,EAGN,KAAK,WAAW,EAChB,KAAK,UAAU,EAEf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAclC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,EAAE,GAAG,WAAW,CAMrD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC9B,EAAE,EAAE,EAAE,EACN,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,EAAE,CAAC,CAEvB"}

package/dist/translate.d.ts

@@ -0,0 +1,58 @@
+import { StoreConflict, StoreFailure } from '@nxgt/janus';
+/**
+ * **The driver's errors, as the port's.** One file, and one default.
+ *
+ * | What happens | Becomes |
+ * | --- | --- |
+ * | A duplicate key on `(type, logins)` | `StoreConflict('login')`, naming the login and the type |
+ * | A duplicate key on `_id` | nothing — the insert is a retry, and answers what is stored |
+ * | A duplicate key on **any other index** | **`StoreFailure`** |
+ * | A `$jsonSchema` validation failure (121) | **`StoreFailure`** |
+ * | Anything else, absolutely | `StoreFailure`, with the driver error as `cause` |
+ *
+ * The two bold rows go against the obvious reading. A duplicate on an index
+ * the adapter did not mean to collide on is an adapter bug: reporting it as
+ * `LOGIN_TAKEN` would tell somebody their login is taken when it is
+ * not. And the core has validated every record before it reaches a store, so a
+ * validator refusing one means the adapter and the port disagree — never the
+ * caller's fault, never a 400.
+ *
+ * **The default is a failure, not an absence.** That branch is what keeps the
+ * port's first rule: nothing here answers `null` for an error.
+ */
+/** Runs one port method, and makes every rejection one the port allows. */
+export declare function run<T>(slot: 'users' | 'sessions' | 'tokens' | 'relations', operation: string, body: () => Promise<T>): Promise<T>;
+/** The shape of the driver's `E11000`, as far as this file reads it. */
+export interface DuplicateKey {
+    readonly code: 11000;
+    readonly keyPattern?: Readonly<Record<string, unknown>>;
+    readonly keyValue?: Readonly<Record<string, unknown>>;
+}
+export declare function isDuplicateKey(error: unknown): error is DuplicateKey;
+/**
+ * Settles a write: what it answered when it landed, or the duplicate-key error
+ * when an index refused it. **Any other rejection is rethrown**, so a caller
+ * of this is only ever told "written" or "duplicate", and never "nothing".
+ */
+export declare function settle<T>(write: Promise<T>): Promise<{
+    readonly written: T;
+} | {
+    readonly written?: never;
+    duplicate: DuplicateKey;
+}>;
+/** A login one type holds. */
+export interface TypedLogin {
+    readonly type: string;
+    readonly login: string;
+}
+/**
+ * The login a duplicate names, when it is the login index that refused the
+ * write — and `null` for every other index, which the caller then reports as
+ * a failure.
+ */
+export declare function takenLogin(duplicate: DuplicateKey): TypedLogin | null;
+/** The refusal the port promises for a taken login. */
+export declare function loginTaken(operation: string, { type, login }: TypedLogin, cause: unknown): StoreConflict;
+/** A duplicate on an index the adapter never meant to collide on: a bug, reported as one. */
+export declare function unexpectedDuplicate(slot: 'users' | 'sessions' | 'tokens', operation: string, duplicate: DuplicateKey): StoreFailure;
+//# sourceMappingURL=translate.d.ts.map

package/dist/translate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.d.ts","sourceRoot":"","sources":["../src/translate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,2EAA2E;AAC3E,wBAAsB,GAAG,CAAC,CAAC,EAC1B,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,EACnD,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAMpE;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACvB,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GACf,OAAO,CACP;IAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;CAAE,GACvB;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,YAAY,CAAA;CAAE,CACvD,CAQA;AAED,8BAA8B;AAC9B,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,YAAY,GAAG,UAAU,GAAG,IAAI,CAKrE;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CACzB,SAAS,EAAE,MAAM,EACjB,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,UAAU,EAC3B,KAAK,EAAE,OAAO,GACZ,aAAa,CAMf;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,EACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,YAAY,GACrB,YAAY,CAKd"}

package/docs/README.md

@@ -0,0 +1,11 @@
+# @nxgt/janus-mongo — documentation
+
+The [README](../README.md) shows the whole wiring in one example; these pages
+give the detail.
+
+| Page | Read it when |
+| --- | --- |
+| [Wiring the stores and the relations](guide/wiring.md) | You are passing MongoDB to `janus()` and `permissions()`, mixing adapters, or handling what a failure throws |
+| [Collections and indexes](guide/sync.md) | You are creating the collections and indexes at deploy time, checking them in CI, or want to know what the database holds |
+| [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |
+| [Roadmap](roadmap.md) | You want to know what is coming, what shipped, and what is deliberately not planned |

package/docs/guide/sync.md

@@ -0,0 +1,122 @@
+# Collections and indexes
+
+This page is for creating what the adapter needs in the database — the
+collections, their validators and their indexes — as a deployment step, and
+for knowing what ends up stored. Wiring the stores into `janus()` and
+`permissions()` is on [the wiring page](wiring.md).
+
+```ts
+import { syncMongoRelations, syncMongoStores } from '@nxgt/janus-mongo';
+import { MongoClient } from 'mongodb';
+
+const client = await MongoClient.connect(process.env.MONGO_URL ?? 'mongodb://localhost:27017');
+const db = client.db('janus');
+
+await syncMongoStores(db);    // users, sessions, tokens
+await syncMongoRelations(db); // relations — only if you use @nxgt/janus/permissions
+
+await client.close();
+```
+
+**The core never manages a schema, and neither function is called for you.**
+Without `syncMongoStores` there is no unique index on logins, and nothing stops
+two concurrent sign-ups with one e-mail.
+
+## `syncMongoStores` and `syncMongoRelations`
+
+```ts
+function syncMongoStores(db: Db, options?: SyncOptions): Promise<SyncReport[]>;
+function syncMongoRelations(db: Db, options?: SyncOptions): Promise<SyncReport[]>;
+```
+
+Each creates its collections when they are missing, writes their `$jsonSchema`
+validators, and creates or rebuilds their indexes, then answers one report per
+collection saying what it changed. **Run it twice and the second run sends
+nothing.**
+
+- It is a **deployment step**, never a request-time one: `collMod` needs the
+  `dbAdmin` role, and neither it nor an index build may run in a transaction.
+- The relation store is a separate step because an application that only
+  authenticates keeps no tuples.
+
+```ts
+for (const report of await syncMongoStores(db)) {
+	console.log(report.name, report.created, report.indexes);
+}
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `dryRun` | boolean | `false` | Compare and report, send nothing — a CI check, or a look before a deploy |
+| `dropUnknownIndexes` | boolean | `false` | Drop indexes the server has and no definition names. Off: an index someone added on purpose is not this package's to remove |
+| `session` | `ClientSession` | none | A session for the reads — not one inside a transaction |
+
+`SyncOptions` and `SyncReport` are `@nxgt/mongo`'s types, which is where the
+sync comes from.
+
+```ts
+const reports = await syncMongoStores(db, { dryRun: true });
+const pending = reports.filter(
+	(report) => report.created || report.indexes.created.length + report.indexes.recreated.length > 0,
+);
+if (pending.length > 0) process.exitCode = 1; // the database is behind the code
+```
+
+## With `@nxgt/mongo`'s `syncAll`
+
+The definitions are exported — `users`, `sessions`, `tokens`, `relations`, and
+`janusCollections` (the first three, in sync order) — and defining them
+registered them with `@nxgt/mongo`. An application that already deploys with
+`syncAll(db)` gets them synced with its own collections:
+
+```ts
+import '@nxgt/janus-mongo'; // importing it registers the four definitions
+import { syncAll, syncCollections } from '@nxgt/mongo';
+import { janusCollections, relations } from '@nxgt/janus-mongo';
+
+await syncAll(db); // every registered collection: yours, and the four of this package
+
+// or name them yourself
+await syncCollections(db, [...janusCollections, relations]);
+```
+
+Importing the package registers `relations` too, so `syncAll` creates it even
+for an application that does not use permissions. It stays empty.
+
+## What the database holds
+
+The port's records, with the id under `_id` and nothing else renamed or
+encoded: a document read in a shell reads like the record in the code.
+
+| Collection | Holds | Indexes |
+| --- | --- | --- |
+| `users` | one user: `type`, `fields`, `logins`, `password`, `emailVerifiedAt`, `version`, … | `loginUnique` on `{ type, logins }`, unique — a login is unique **per user type** · `typeId` on `{ type, _id }`, for listing |
+| `sessions` | one session, by the `sha256` of its token | `tokenHashUnique` · `userId` · `expiry`, a TTL index |
+| `tokens` | one one-time token; `_id` **is** its `sha256` | `userId` · `expiry`, a TTL index |
+| `relations` | one tuple; `_id` **is** the tuple, `{ object: { type, id }, relation, subject: { type, id, relation? } }` | `objectRelation`, one hop forwards · `subjectObjects`, the reverse index `list()` walks |
+
+- **No secret is stored.** Sessions and tokens hold the `sha256` of the
+  secret; passwords a self-describing hash (`$scrypt$…`, `$argon2id$…`).
+- **Ids are strings**, the UUIDv7s the core minted — never an `ObjectId`: the
+  store mints nothing.
+- **A tuple is unique by construction**, since it is its own `_id`, so writing
+  a stored tuple again is a no-op rather than a duplicate. A subject set and
+  its entity (`team:t1#member`, `team:t1`) are two different keys.
+- `findObjects` is served by `subjectObjects` with no in-memory sort —
+  measured, 11 keys examined for a page of 10.
+- The collection names are fixed: `users`, `sessions`, `tokens`, `relations`.
+  Give the adapter a database of its own — `client.db('janus')` — so they
+  never meet a collection of your application's.
+
+## The TTL indexes are not the expiry
+
+MongoDB's TTL monitor runs every sixty seconds, so a lapsed session can stay
+readable for up to a minute. The core compares `expiresAt` on every read, and
+that is what expires it; the TTL index only keeps storage tidy. It is also why
+`deleteExpiredSessions` is not implemented, and `auth.collectExpired()` answers
+`UNSUPPORTED` with this adapter.
+
+## See also
+
+- [Wiring the stores](wiring.md) — `createMongoStores`, `createMongoRelations`, and what a failure looks like
+- [`@nxgt/mongo`](https://www.npmjs.com/package/@nxgt/mongo) — `syncAll`, `syncCollections`, `SyncReport`

package/docs/guide/wiring.md

@@ -0,0 +1,159 @@
+# Wiring the stores and the relations
+
+This page is for connecting `@nxgt/janus` to MongoDB: the three user stores
+for `janus()`, the relation store for `permissions()`, and what each gives
+back when the database cannot answer. Creating the collections and indexes is
+on [the sync page](sync.md).
+
+```ts
+import { janus, scryptHasher } from '@nxgt/janus';
+import { defineModel, permissions } from '@nxgt/janus/permissions';
+import { createMongoRelations, createMongoStores } from '@nxgt/janus-mongo';
+import { MongoClient } from 'mongodb';
+import { z } from 'zod';
+
+const client = new MongoClient(process.env.MONGO_URL ?? 'mongodb://localhost:27017');
+const db = client.db('janus');
+
+const relations = createMongoRelations(db);
+
+export const auth = janus({
+	user: z.object({ email: z.email(), name: z.string() }),
+	password: { login: 'email' },
+	store: createMongoStores(db),
+	relations, // deleting a user deletes every tuple naming them
+	hasher: scryptHasher(),
+});
+
+export const model = defineModel({
+	subjects: auth.types,
+	types: {
+		document: {
+			relations: { owner: ['user'], viewer: ['user'] },
+			permissions: { view: ['owner', 'viewer'] },
+		},
+	},
+});
+
+export const access = permissions({ model, store: relations });
+```
+
+## `createMongoStores(db)`
+
+```ts
+function createMongoStores(db: Db): JanusStores; // { users, sessions, tokens }
+```
+
+What `janus({ store })` takes. **It connects to nothing** and sends nothing:
+the first command goes out on the first call that needs one. `db` is a
+`mongodb` `Db`; the adapter reads the `users`, `sessions` and `tokens`
+collections of it.
+
+Every method of the port is implemented except the optional
+`deleteExpiredSessions`: a TTL index drops lapsed sessions, so
+`auth.collectExpired()` answers `UNSUPPORTED` with this adapter. Do not
+schedule it.
+
+## `createMongoRelations(db)`
+
+```ts
+function createMongoRelations(db: Db): RelationStore;
+```
+
+What `permissions({ store })` takes, and `janus({ relations })`. It connects to
+nothing either, and reads the `relations` collection.
+
+**A write of more than one tuple is a transaction**, and MongoDB runs
+transactions on a replica set only. `grant` and `revoke` write one tuple and
+run anywhere, including a standalone `mongod`; a multi-tuple `write` there
+fails with `STORE_FAILED`. The transaction is not retried: a write is
+idempotent, so retry it yourself if you want to.
+
+`findObjects` orders ids as MongoDB does, by UTF-8 bytes. `list()` sorts what
+it gathers, so its pages do not depend on that; a caller of the store directly
+sees byte order, which differs from JavaScript's `<` only past U+FFFF.
+
+## What a failure looks like
+
+The adapter defines **no error class**. Every rejection is `@nxgt/janus`'s
+own, so `instanceof` holds in your code — `@nxgt/janus` is a peer, and there
+is one copy of it:
+
+| What the driver reports | What you get |
+| --- | --- |
+| A duplicate key on the login index | `StoreConflict` — `LOGIN_TAKEN`, naming the login and the user type |
+| A duplicate key on `_id` | nothing: the insert was a retry, and answers what is stored |
+| A duplicate key on **any other index** | `StoreFailure` — an adapter bug, never reported as a taken login |
+| A validator refusing a document (121) | `StoreFailure` — the core validated it already, so it is never the caller's fault |
+| Anything else: a timeout, a stepped-down primary, a refused connection | `StoreFailure`, with the driver's error as `cause` |
+
+Nothing answers `null` for an error. So a route answers 503, not 401 or 404:
+
+```ts
+import { StoreFailure } from '@nxgt/janus';
+
+export async function me(request: Request): Promise<Response> {
+	try {
+		const current = await auth.authenticate(request);
+		return current === null ? new Response(null, { status: 401 }) : Response.json({ id: current.user.id });
+	} catch (error) {
+		if (error instanceof StoreFailure) return new Response(null, { status: 503 });
+		throw error;
+	}
+}
+```
+
+The error's message names the slot and the method (`users.findUser: the store
+could not answer`) and never the connection string.
+
+## Mixing adapters
+
+Each slot of `JanusStores` may come from a different store. Users in MongoDB,
+sessions and tokens elsewhere:
+
+```ts
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+import { createMongoStores } from '@nxgt/janus-mongo';
+import { z } from 'zod';
+
+const mongo = createMongoStores(db);
+const other = createMemoryStores(); // or another adapter's stores
+
+export const auth = janus({
+	user: z.object({ email: z.email() }),
+	password: { login: 'email' },
+	store: { users: mongo.users, sessions: other.sessions, tokens: other.tokens },
+	hasher: scryptHasher(),
+});
+```
+
+## Testing against a real `mongod`
+
+The reference store `createMemoryStores()` is faster, but it is not MongoDB.
+When a test depends on a transaction or on the unique index, run a
+single-node replica set — the adapter's own specs use
+`mongodb-memory-server-core`, one database per case:
+
+```ts
+import { createMongoRelations, createMongoStores, syncMongoRelations, syncMongoStores } from '@nxgt/janus-mongo';
+import { MongoClient } from 'mongodb';
+import { MongoMemoryReplSet } from 'mongodb-memory-server-core';
+
+const server = await MongoMemoryReplSet.create({ replSet: { count: 1 } });
+const client = await MongoClient.connect(server.getUri());
+
+const db = client.db('janusTest');
+await syncMongoStores(db);
+await syncMongoRelations(db);
+const store = createMongoStores(db);
+const relations = createMongoRelations(db);
+
+// after the suite
+await client.close();
+await server.stop();
+```
+
+## See also
+
+- [Collections and indexes](sync.md) — `syncMongoStores`, `syncMongoRelations`, and what the database holds
+- [`@nxgt/janus`](https://www.npmjs.com/package/@nxgt/janus) — its `docs/guide/` covers users, sessions and permissions

package/docs/roadmap.md

@@ -0,0 +1,54 @@
+# Roadmap
+
+Where `@nxgt/janus-mongo` 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
+
+Nothing yet.
+
+## Not planned
+
+- **`collectExpired()` with this adapter** — it answers `UNSUPPORTED` on
+  purpose. The TTL indexes on `sessions` and `tokens` already drop lapsed
+  records, and the core decides expiry on every read regardless.
+- **Retrying a relation transaction for you** — the driver's
+  `withTransaction` would retry an outage for two minutes before answering. A
+  relation write is idempotent, so retry it yourself, on your own terms.
+- **Multi-tuple relation writes on a standalone mongod** — a write of more
+  than one tuple is a transaction, and MongoDB runs transactions on a replica
+  set only. `grant` and `revoke` write one tuple and run anywhere.
+- **Managing the schema from the store** — the collections and indexes are
+  created by `syncMongoStores` and `syncMongoRelations`, a deployment step you
+  run. The stores never create anything per request.
+- **Error classes of its own** — the adapter throws `@nxgt/janus`'s classes,
+  which is why `@nxgt/janus` is a required peer and never a dependency:
+  `instanceof StoreFailure` has to hold in your code.
+- **`moduleResolution: "nodenext"`** — like `@nxgt/janus`, the package imports
+  without extensions and resolves as Bun and every bundler do. Use
+  `"moduleResolution": "bundler"`.
+
+## Shipped
+
+The first public release, v0.1.
+
+- **Guides and troubleshooting pages** — a `docs/` folder shipped in the
+  package, with the errors and traps you can meet running the adapter, each
+  with its cause and fix. — v0.1
+- **The relation store** — `createMongoRelations(db)` and
+  `syncMongoRelations(db)`: the `RelationStore` of `@nxgt/janus/permissions`,
+  one document per tuple, and `findObjects` served by an index with no
+  in-memory sort. — v0.1
+- **Deleting a user, and everything of theirs** — the stores delete a user's
+  sessions and one-time tokens with them, as `delete(user)` requires. — v0.1
+- **Users, sessions and one-time tokens** — `createMongoStores(db)` and
+  `syncMongoStores(db)`, passing the `@nxgt/janus/conformance` suite against a
+  real mongod, outages included. — v0.1

package/docs/troubleshooting.md

@@ -0,0 +1,193 @@
+# Troubleshooting `@nxgt/janus-mongo`
+
+Each entry is headed by the text you see: a compiler error, a message, or an
+error `code`. Search this page for the words of your message.
+
+This adapter **defines no error class**. Every error it throws is one of
+`@nxgt/janus`'s — `StoreFailure`, `StoreConflict`, `NotFoundError` — so the
+codes, and what each one deserves as an answer, are those of the core. The
+errors the core raises itself (`CREDENTIALS_INVALID`, `TOKEN_EXPIRED`,
+`PERMISSION_DEPTH`, …) are in
+[`@nxgt/janus`'s troubleshooting](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md).
+
+How the driver's errors become the port's:
+
+| What MongoDB answers | What you get |
+| --- | --- |
+| A duplicate key on the login index | `LOGIN_TAKEN`, naming the login and the user type |
+| A duplicate key on `_id` | Nothing: the insert was a retry, and what is stored is answered |
+| A duplicate key on any other index | `STORE_FAILED` |
+| A `$jsonSchema` validation failure (code 121) | `STORE_FAILED` |
+| Anything else | `STORE_FAILED`, with the driver's error as `cause` |
+
+## Index
+
+**Install and types**
+- [`TS2834: Relative import paths need explicit file extensions …`](#ts2834-relative-import-paths-need-explicit-file-extensions-in-ecmascript-imports-when---moduleresolution-is-node16-or-nodenext)
+- [`error instanceof StoreFailure` is `false` for an outage](#error-instanceof-storefailure-is-false-for-an-outage)
+
+**Setup**
+- [Two sign-ups with the same login both succeed](#two-sign-ups-with-the-same-login-both-succeed)
+- [`STORE_FAILED` — `relations.write: the store could not answer` on a standalone mongod](#store_failed--relationswrite-the-store-could-not-answer-on-a-standalone-mongod)
+- [`STORE_FAILED` with `Document failed validation` as its cause](#store_failed-with-document-failed-validation-as-its-cause)
+
+**Runtime**
+- [`STORE_FAILED` — `<slot>.<operation>: the store could not answer`](#store_failed--slotoperation-the-store-could-not-answer)
+- [`LOGIN_TAKEN` — `<operation>: the login "<login>" is taken by another <type>`](#login_taken--operation-the-login-login-is-taken-by-another-type)
+- [`STORE_FAILED` — `<slot>.<operation>: a duplicate key on <fields>, which this adapter never writes on purpose`](#store_failed--slotoperation-a-duplicate-key-on-fields-which-this-adapter-never-writes-on-purpose)
+- [`NOT_FOUND` / `VERSION_CONFLICT` — `updateUser: …`](#not_found--version_conflict--updateuser-)
+- [`UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions …`](#unsupported--collectexpired-storesessions-does-not-implement-deleteexpiredsessions--)
+- [Lapsed sessions and tokens are still in the collection](#lapsed-sessions-and-tokens-are-still-in-the-collection)
+- [`findObjects` answers ids in a different order than JavaScript sorts them](#findobjects-answers-ids-in-a-different-order-than-javascript-sorts-them)
+
+---
+
+## Install and types
+
+### `TS2834: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'.`
+
+With `skipLibCheck: true`, the same cause shows up instead as
+`TS2305: Module '"@nxgt/janus-mongo"' has no exported member '<name>'.`
+
+**When:** `tsc` on your project, reported inside the package's `dist/*.d.ts`.
+**Why:** the declarations of this package and of `@nxgt/janus` import their siblings without an extension, the way a bundler resolves them. `moduleResolution: "nodenext"` (or `"node16"`) is **not supported**.
+**Fix:**
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "module": "preserve",          // or "esnext"
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+Do not patch the declarations to add `.js` extensions: that support is out of
+scope, and a patched copy breaks on the next install.
+
+### `error instanceof StoreFailure` is `false` for an outage
+
+**When:** at run time, testing an error from this adapter against the class you imported from `@nxgt/janus`.
+**Why:** two copies of `@nxgt/janus` are installed. This adapter throws the `StoreFailure` of the copy *it* resolves; if that is not yours, `instanceof` fails, and an outage — or a taken login — is handled as an unknown error.
+**Fix:** `@nxgt/janus` is a **required peer** of this package: install it once, in your application, at a version the peer range accepts.
+
+```sh
+bun add @nxgt/janus-mongo @nxgt/janus @nxgt/mongo mongodb zod
+bun pm ls --all | grep @nxgt/janus   # one @nxgt/janus, not two
+```
+
+---
+
+## Setup
+
+### Two sign-ups with the same login both succeed
+
+**When:** concurrent `signUp` or `create` calls with one login — or any second sign-up — after deploying to a new database.
+**Why:** `syncMongoStores(db)` was never run, so the `loginUnique` index does not exist. The core never reads first to decide uniqueness; only the index refuses a duplicate, and it is what produces `LOGIN_TAKEN`. The core never manages a schema, so nothing creates the index for you.
+**Fix:** run the sync as a deployment step, with a user that has the `dbAdmin` role — never per request:
+
+```ts
+import { syncMongoRelations, syncMongoStores } from '@nxgt/janus-mongo';
+
+await syncMongoStores(db);     // users, sessions, tokens: validators and indexes
+await syncMongoRelations(db);  // only if you use @nxgt/janus/permissions
+```
+
+An application that deploys with `@nxgt/mongo`'s `syncAll(db)` already syncs
+the three stores' collections, since defining them registers them.
+
+### `STORE_FAILED` — `relations.write: the store could not answer` on a standalone mongod
+
+`error.cause` is the driver's
+`This MongoDB deployment does not support retryable writes. Please add retryWrites=false to your connection string.`
+
+**When:** a relation-store `write` of more than one tuple — `store.write({ add: [a, b] })`, or an add and a remove together — against a standalone `mongod`. `grant` and `revoke` write one tuple and are not affected.
+**Why:** a write of several tuples runs in a transaction, and MongoDB runs transactions on a replica set only. Adding `retryWrites=false`, as the driver suggests, does not help: the transaction is still refused.
+**Fix:** run a replica set. For local development and tests, a single-node replica set is enough:
+
+```sh
+mongod --replSet rs0 --dbpath ./data
+mongosh --eval 'rs.initiate()'
+```
+
+```ts
+// In tests, with mongodb-memory-server
+import { MongoMemoryReplSet } from 'mongodb-memory-server-core';
+const replSet = await MongoMemoryReplSet.create({ replSet: { count: 1 } });
+```
+
+The transaction is not retried by the adapter — the driver's `withTransaction`
+would retry an outage for two minutes before answering. A relation write is
+idempotent, so retry it yourself.
+
+### `STORE_FAILED` with `Document failed validation` as its cause
+
+**When:** a write — `insertUser`, `updateUser`, `insertSession`, … — rejected by the collection's `$jsonSchema` validator (MongoDB error code 121).
+**Why:** the core validates every record before it reaches the store, so a validator refusing one means the collection and the adapter disagree: the collection's validator was set by another version of this adapter, or a collection of the same name (`users`, `sessions`, `tokens`, `relations`) already belonged to your application, with its own validator. It is never the caller's fault, and never a 400.
+**Fix:** after upgrading this package, run `syncMongoStores(db)` again. If your application already has a `users` collection, the adapter is sharing its database: give it one of its own, `janus`:
+
+```ts
+const auth = janus({ ..., store: createMongoStores(client.db('janus')) });
+```
+
+---
+
+## Runtime
+
+### `STORE_FAILED` — `<slot>.<operation>: the store could not answer`
+
+`StoreFailure`, for example `users.findUserByLogin: the store could not answer`, with `slot`, `operation` and the driver's error as `cause`.
+
+**When:** any call that reaches MongoDB while it cannot answer: the server is unreachable, server selection timed out, the credentials were refused, a primary stepped down.
+**Why:** a store that cannot answer throws — it never answers `null`. The driver's message stays out of the error's message, because it can hold the connection string, and a connection string holds a password.
+**Fix:** answer **503** and log `cause`; never map it to 401, 404, `null` or `false`.
+
+```ts
+import { JanusError } from '@nxgt/janus';
+
+if (error instanceof JanusError && error.code === 'STORE_FAILED') {
+  logger.error({ slot: error.slot, operation: error.operation, cause: error.cause });
+  return new Response('Try again shortly', { status: 503 });
+}
+```
+
+### `LOGIN_TAKEN` — `<operation>: the login "<login>" is taken by another <type>`
+
+`StoreConflict` with `on: 'login'`, for example `insertUser: the login "ada@example.com" is taken by another patient`. It carries `login` and `userType`.
+
+**When:** `signUp`, `create`, or an `update` that changes the login, when another user **of the same type** already holds it. The message names the port method (`insertUser`, `updateUser`), not your call.
+**Why:** the `loginUnique` index on `{ type, logins }` refused the write. The same e-mail may hold one account per user type.
+**Fix:** answer 409.
+
+### `STORE_FAILED` — `<slot>.<operation>: a duplicate key on <fields>, which this adapter never writes on purpose`
+
+**When:** a write refused by a unique index that is not the login index — typically one you added to `users` or `sessions` yourself.
+**Why:** this adapter only ever collides on the login index and on `_id`. A duplicate anywhere else is reported as a failure, not as `LOGIN_TAKEN`: that would tell somebody their e-mail is in use when it is not.
+**Fix:** drop the extra unique index (`db.users.getIndexes()` lists them), or make it non-unique. Uniqueness of your own fields belongs in your own collection.
+
+### `NOT_FOUND` / `VERSION_CONFLICT` — `updateUser: …`
+
+`updateUser: no user has this id`, and `updateUser: expected version <n>, found <m>`.
+
+**When:** calling `createMongoStores(db).users.updateUser(...)` directly. Through `janus()`, the same refusals carry the name of your call instead (`update: …`).
+**Why:** the write matched nothing, and the adapter reads again to tell an unknown id from a version that moved. On a conflict nothing was written.
+**Fix:** for a conflict, read the user again and retry; see `VERSION_CONFLICT` in the core's troubleshooting.
+
+### `UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions — …`
+
+**When:** `auth.collectExpired()`.
+**Why:** deliberate. The `expiry` TTL index already deletes lapsed sessions, so this adapter does not implement `deleteExpiredSessions`.
+**Fix:** do not schedule `collectExpired` with this adapter. Nothing is lost: expiry never depended on it.
+
+### Lapsed sessions and tokens are still in the collection
+
+**When:** looking at `sessions` or `tokens` in a shell shortly after `expiresAt`.
+**Why:** MongoDB's TTL monitor runs every sixty seconds, so a document can outlive its `expiresAt` by up to a minute, or more on a loaded server. The TTL index is storage hygiene, not the expiry mechanism.
+**Fix:** none needed. The core compares `expiresAt` on every read, so `authenticate` answers a lapsed session as anonymous and refuses a lapsed token (`TOKEN_EXPIRED`, or `TOKEN_UNKNOWN` once the document is gone).
+
+### `findObjects` answers ids in a different order than JavaScript sorts them
+
+**When:** calling the relation store's `findObjects` directly, with ids holding characters past U+FFFF (emoji, some CJK).
+**Why:** MongoDB orders strings by UTF-8 bytes; JavaScript's `<` compares UTF-16 code units. The two agree everywhere else.
+**Fix:** none through `access.list()`: it sorts what it gathers itself, so its pages do not depend on the store's order. A direct caller that needs JavaScript's order sorts the page.