@nxgt/janus-mongo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @nxgt/janus-mongo
+
+The MongoDB adapter for [`@nxgt/janus`](https://www.npmjs.com/package/@nxgt/janus): its three stores —
+users, sessions and one-time tokens — and the relation store of
+`@nxgt/janus/permissions`, over one database, on
+[`@nxgt/mongo`](https://www.npmjs.com/package/@nxgt/mongo).
+
+It passes both `@nxgt/janus/conformance` suites against a real mongod, outages
+included.
+
+```ts
+import { janus, scryptHasher } from '@nxgt/janus';
+import { permissions } from '@nxgt/janus/permissions';
+import {
+  createMongoRelations,
+  createMongoStores,
+  syncMongoRelations,
+  syncMongoStores,
+} from '@nxgt/janus-mongo';
+
+await syncMongoStores(db); // a deployment step: creates the collections and indexes
+
+export const auth = janus({
+  user: User,
+  password: { login: 'email' },
+  store: createMongoStores(db),
+  hasher: scryptHasher(),
+  relations: createMongoRelations(db), // deleting a user deletes their tuples
+});
+
+await syncMongoRelations(db);
+export const access = permissions({ model, store: createMongoRelations(db) });
+```
+
+## Install
+
+```sh
+bun add @nxgt/janus-mongo @nxgt/janus @nxgt/mongo mongodb zod
+```
+
+Every peer is required: `@nxgt/janus`, `@nxgt/mongo` (`>=0.17 <1`), `mongodb`
+(7), `zod` (4.6.5 or later, which `@nxgt/mongo` defines collections with) and `typescript`
+(6). `@nxgt/janus` is a **peer**, never a dependency: this package defines no
+error class and throws the peer's own, so `instanceof StoreFailure` holds in
+your code. Like it, this package expects `"moduleResolution": "bundler"`: the
+declarations import without extensions, so `nodenext` is not supported.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `createMongoStores(db)` | The `{ users, sessions, tokens }` that `janus()` takes as `store`. Connects to nothing. |
+| `syncMongoStores(db, options?)` | Creates the three collections, their validators and indexes, and answers what it changed. Needs `dbAdmin`; run it when you deploy, never per request. |
+| `users`, `sessions`, `tokens` | The `@nxgt/mongo` definitions. Defining them registers them, so `syncAll(db)` syncs them with your own collections. |
+| `janusCollections` | The three definitions, in sync order. |
+| `createMongoRelations(db)` | The `RelationStore` that `permissions()` takes as `store`, and `janus()` as `relations`. Connects to nothing. |
+| `syncMongoRelations(db, options?)` | Creates the `relations` collection and its indexes. A separate step: an application that only authenticates keeps no tuples. |
+| `relations` | Its `@nxgt/mongo` definition. |
+
+## 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 | Indexes |
+| --- | --- |
+| `users` | `loginUnique` on `{ type, logins }`, unique — a login is unique **per user type** · `typeId` on `{ type, _id }` for listing |
+| `sessions` | `tokenHashUnique` · `userId` · `expiry`, a TTL index |
+| `tokens` | `_id` is the token's hash · `userId` · `expiry`, a TTL index |
+| `relations` | `_id` **is the tuple**, `{ object: { type, id }, relation, subject: { type, id, relation? } }` — unique by construction · `objectRelation` for one hop forwards · `subjectObjects` for `findObjects`, which it serves with no in-memory sort (measured: 11 keys examined for a page of 10) |
+
+No secret is stored: sessions and tokens hold `sha256` of the secret, and
+passwords a self-describing hash.
+
+## Traps
+
+- **The TTL indexes are storage hygiene, 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.
+- **`auth.collectExpired()` answers `UNSUPPORTED`** with this adapter. The TTL
+  index already drops lapsed sessions, so `deleteExpiredSessions` is
+  deliberately not implemented.
+- **`syncMongoStores` is not called for you.** The core never manages a schema.
+  Without it there is no unique index, and nothing stops two concurrent sign-ups
+  with one login.
+- **A duplicate key on an index other than the login index is a
+  `StoreFailure`, not `LOGIN_TAKEN`.** Such a duplicate is an adapter bug, and
+  reporting it as a taken login would tell somebody their e-mail is in use when
+  it is not.
+- **A relation 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; on a standalone mongod a multi-tuple write fails with
+  `STORE_FAILED`. The transaction is not retried: the driver's `withTransaction`
+  would retry an outage for two minutes before answering, and a write is
+  idempotent, so retry it yourself.
+- **`findObjects` orders ids as MongoDB does, by UTF-8 bytes.** `list()` sorts
+  what it gathers itself, so its pages do not depend on it; a caller of the
+  store directly sees bytes order, which differs from JavaScript's `<` only past
+  U+FFFF.
+
+## Documentation
+
+- [Guides](docs/README.md) — wiring the stores, syncing the collections
+- [Troubleshooting](docs/troubleshooting.md) — by the error message you see
+- [Roadmap](docs/roadmap.md) — what is next, and what is not planned

package/dist/collections.d.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+export declare const users: import("@nxgt/mongo").CollectionDefinition<import("@nxgt/mongo").StampedSchema<{
+    _id: z.ZodString;
+    type: z.ZodString;
+    schemaVersion: z.ZodString;
+    active: z.ZodBoolean;
+    fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    logins: z.ZodArray<z.ZodString>;
+    password: z.ZodNullable<z.ZodObject<{
+        hash: z.ZodString;
+        updatedAt: z.ZodDate;
+    }, z.core.$strip>>;
+    emailVerifiedAt: z.ZodNullable<z.ZodDate>;
+    version: z.ZodInt;
+    createdAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+}, false, false, false, false>, import("@nxgt/mongo").StampNamesOf<false, false, false, false>>;
+export declare const sessions: import("@nxgt/mongo").CollectionDefinition<import("@nxgt/mongo").StampedSchema<{
+    _id: z.ZodString;
+    tokenHash: z.ZodString;
+    userId: z.ZodString;
+    authenticatedAt: z.ZodDate;
+    expiresAt: z.ZodDate;
+    revokedAt: z.ZodNullable<z.ZodDate>;
+    createdAt: z.ZodDate;
+}, false, false, false, false>, import("@nxgt/mongo").StampNamesOf<false, false, false, false>>;
+export declare const tokens: import("@nxgt/mongo").CollectionDefinition<import("@nxgt/mongo").StampedSchema<{
+    _id: z.ZodString;
+    kind: z.ZodEnum<{
+        verifyEmail: "verifyEmail";
+        resetPassword: "resetPassword";
+    }>;
+    userId: z.ZodString;
+    address: z.ZodString;
+    expiresAt: z.ZodDate;
+    spentAt: z.ZodNullable<z.ZodDate>;
+    createdAt: z.ZodDate;
+}, false, false, false, false>, import("@nxgt/mongo").StampNamesOf<false, false, false, false>>;
+/** The three definitions, in the order `syncMongoStores` syncs them. */
+export declare const janusCollections: readonly [import("@nxgt/mongo").CollectionDefinition<import("@nxgt/mongo").StampedSchema<{
+    _id: z.ZodString;
+    type: z.ZodString;
+    schemaVersion: z.ZodString;
+    active: z.ZodBoolean;
+    fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    logins: z.ZodArray<z.ZodString>;
+    password: z.ZodNullable<z.ZodObject<{
+        hash: z.ZodString;
+        updatedAt: z.ZodDate;
+    }, z.core.$strip>>;
+    emailVerifiedAt: z.ZodNullable<z.ZodDate>;
+    version: z.ZodInt;
+    createdAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+}, false, false, false, false>, import("@nxgt/mongo").StampNamesOf<false, false, false, false>>, import("@nxgt/mongo").CollectionDefinition<import("@nxgt/mongo").StampedSchema<{
+    _id: z.ZodString;
+    tokenHash: z.ZodString;
+    userId: z.ZodString;
+    authenticatedAt: z.ZodDate;
+    expiresAt: z.ZodDate;
+    revokedAt: z.ZodNullable<z.ZodDate>;
+    createdAt: z.ZodDate;
+}, false, false, false, false>, import("@nxgt/mongo").StampNamesOf<false, false, false, false>>, import("@nxgt/mongo").CollectionDefinition<import("@nxgt/mongo").StampedSchema<{
+    _id: z.ZodString;
+    kind: z.ZodEnum<{
+        verifyEmail: "verifyEmail";
+        resetPassword: "resetPassword";
+    }>;
+    userId: z.ZodString;
+    address: z.ZodString;
+    expiresAt: z.ZodDate;
+    spentAt: z.ZodNullable<z.ZodDate>;
+    createdAt: z.ZodDate;
+}, false, false, false, false>, import("@nxgt/mongo").StampNamesOf<false, false, false, false>>];
+//# sourceMappingURL=collections.d.ts.map

package/dist/collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collections.d.ts","sourceRoot":"","sources":["../src/collections.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;+FAmChB,CAAC;AAEH,eAAO,MAAM,QAAQ;;;;;;;;+FA6BnB,CAAC;AAEH,eAAO,MAAM,MAAM;;;;;;;;;;;+FAmBjB,CAAC;AAEH,wEAAwE;AACxE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gGAAqC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@nxgt/janus-mongo` — the MongoDB adapter for `@nxgt/janus`.
+ *
+ * Implements all three stores of the `@nxgt/janus` store port, and the relation
+ * store of `@nxgt/janus/permissions`, over one database, on `@nxgt/mongo`. It defines **no error class**: every refusal is `@nxgt/janus`'s
+ * own, from the peer the application installed, so `instanceof` holds across
+ * the two packages.
+ */
+export { janusCollections, sessions, tokens, users } from './collections';
+export { createMongoRelations, relations, syncMongoRelations, } from './relations';
+export { createMongoStores, syncMongoStores } from './stores';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EACN,oBAAoB,EACpB,SAAS,EACT,kBAAkB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC"}