@nxgt/janus-mongo

The MongoDB adapter for @nxgt/janus: its identity stores — users, sessions and one-time tokens — the relation store of @nxgt/janus/permissions, and the opt-in API key store, over one database, on @nxgt/mongo.

It passes both @nxgt/janus/conformance suites against a real mongod, outages included. createMongoAdapter(db) gives both sides under the names janus() takes them, so one spread wires them; each is also usable alone, as in @nxgt/janus: createMongoStores for identities, createMongoRelations for permissions.

import { janus, scryptHasher } from '@nxgt/janus';
import { permissions } from '@nxgt/janus/permissions';
import { createMongoAdapter, syncMongoAdapter } from '@nxgt/janus-mongo';

await syncMongoAdapter(db); // a deployment step: creates the collections and indexes (API keys: syncMongoApiKeys, apart)

const mongo = createMongoAdapter(db); // { store, relations }

export const auth = janus({
  user: User,
  password: { login: 'email' },
  hasher: scryptHasher(),
  ...mongo, // deleting a user deletes their tuples too
});

export const access = permissions({ model, store: mongo.relations });

Install

bun add @nxgt/janus-mongo @nxgt/janus @nxgt/mongo mongodb zod
bun add -d typescript

Every peer is required: @nxgt/janus, @nxgt/mongo (>=0.17.0 <1), mongodb (7), zod (4.6.5 or later, which @nxgt/mongo defines collections with) and typescript (6 or 7). @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.

The @nxgt/mongo floor is tested, not claimed: the package's specs and its typecheck run on @nxgt/mongo 0.17.0 as well, in the Floors job, on every CI run.

API

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.

No secret is stored: sessions and tokens hold sha256 of the secret, passwords a self-describing hash, and a user's secondFactor.secret a TOTP secret @nxgt/janus has already sealed with your application's key — v1.<key id>.… — which the store keeps byte for byte. Its secondFactor.recoveryCodes are keyed hashes of the recovery codes, never a code, kept in order; a factor without the field reads as having none.

countAttempt counts an attempt at a code in one findOneAndUpdate with $inc, so twenty concurrent attempts answer twenty distinct counts. spendUserTokens is one updateMany on { userId, kind, spentAt: null } — and _id: { $ne: except } when except is given — through the index deleteUserTokens already reads: each token it spends is matched and written in one step, so a racing redemption and it never both spend the same one.

Traps

• Read from the primary. @nxgt/janus counts on a read seeing every write that completed before it: a sign-in re-reads the user to catch a password written while it ran. A db whose client reads from secondaries (readPreference: 'secondaryPreferred') misses that write, and the sign-in goes through. Hand the adapter a db that reads from the primary — the driver's default:

  import { MongoClient } from 'mongodb';
  
  const client = new MongoClient(url); // readPreference 'primary' by default
  const adapter = createMongoAdapter(client.db('app'));
  

• Upgrading to 0.3: run the sync before deploying. No document is rewritten — a user without secondFactor reads as having none, a token without codeHash and attempts as null and 0 — but the validators the previous sync wrote refuse the new fields. Until syncMongoAdapter(db) has run, every sign-up and every one-time token fails with STORE_FAILED, caused by Document failed validation. Upgrading has the steps.

• Upgrading to 0.5: run the sync before deploying, again. No document is rewritten — a second factor without recoveryCodes reads as having none — but the validator the previous sync wrote refuses the new field. Until syncMongoAdapter(db) has run, every write of a second factor — enroll, activate, a confirmed code — fails with STORE_FAILED, caused by Document failed validation. And finish the rollout before users hold recovery codes: an instance still on 0.4 writes a factor back without them when it accepts a code.

• Upgrading to 0.6: run the sync before deploying, once more. The token kind stepUp is new, and the kind enum the previous sync wrote refuses it: until syncMongoAdapter(db) has run, every step-up request fails with STORE_FAILED, caused by Document failed validation. No document is rewritten.

• Upgrading to 0.7: the sync again, for the same reason. The token kind magicLink — @nxgt/janus 0.15's sign-in link — is new: until the sync has run, every magicLink.request fails with STORE_FAILED, caused by Document failed validation. No document is rewritten.

• Upgrading to 0.9: the sync again, for the same reason. The token kind changeEmail — @nxgt/janus 0.23's link to a new address — is new: until the sync has run, the first write of such a token fails with STORE_FAILED, caused by Document failed validation. No document is rewritten.

• Upgrading to 0.10: run the sync before deploying. The avatar slot — @nxgt/janus 0.29's — is new, and the strict validator the previous sync wrote refuses it: until syncMongoAdapter(db) has run, only a write that sets an avatar fails, with STORE_FAILED, caused by Document failed validation. Sign-up and every other write pass, and no document is rewritten. The sync guide has the detail.

• 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 indexes already drop lapsed sessions and tokens, so deleteExpiredSessions and deleteExpiredTokens are deliberately not implemented.

• No sync function is called for you — syncMongoAdapter, or syncMongoStores for identities alone. 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 — wiring the stores, syncing the collections
• Troubleshooting — by the error message you see
• Roadmap — what is next, and what is not planned

Type safety, counted

Eleven plausible mistakes are refused by the compiler, each with a @ts-expect-error case in test/types/adapter.ts:

• a connection string instead of a database;
• @nxgt/mongo's connection instead of its db, to createMongoAdapter;
• the driver's MongoClient instead of one of its databases;
• @nxgt/mongo's connection instead of its db, to syncMongoAdapter;
• the same, to syncMongoRelations;
• the promise connectMongo answers, not awaited;
• a sync option in the wrong case: dryrun for dryRun;
• the whole adapter as janus()'s store, instead of spreading it;
• the relation store as janus()'s store;
• the whole adapter as permissions()'s store, instead of mongo.relations;
• the identity stores as permissions()'s store.

Licence

MIT