@x12i/authx-token-store-mongo

MongoDB adapter implementing @x12i/authx-token-store interfaces. Used by the token service when AUTHX_STORE=mongo.

Part of the AuthX monorepo. See the root README for deployment guidance.

Install

npm install @x12i/authx-token-store-mongo @x12i/authx-token-store @x12i/authx-token-types mongodb

Peer dependency: MongoDB server (tested with driver mongodb ^6).

Quick start

Connect and get stores

import { connectMongoStores } from "@x12i/authx-token-store-mongo";

const { client, db, stores } = await connectMongoStores(
  "mongodb://localhost:27017",
  "authx", // database name
);

// Use stores.apps, stores.tokens, stores.revocations, stores.audit
// ...

await client.close();

Use an existing Db handle

import { createMongoStores } from "@x12i/authx-token-store-mongo";

const stores = await createMongoStores({ db: existingDb });

Indexes are created by default (ensureIndexes: true). Pass ensureIndexes: false to skip.

Environment (token service)

MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=authx
AUTHX_STORE=mongo

The service calls connectMongoStores(uri, dbName) on startup.

Collections

| Collection | Constant | Contents | | --- | --- | --- | | authx_apps | AUTHX_APPS_COLLECTION | App descriptors (no raw secret in list/get projections) | | authx_app_secrets | — | Signing secrets (secretKey, keyVersion, rotation fields) | | authx_tokens | AUTHX_TOKENS_COLLECTION | Issued token metadata | | authx_token_revocations | AUTHX_REVOCATIONS_COLLECTION | Revocation records | | authx_token_audit_events | AUTHX_AUDIT_COLLECTION | Audit trail |

Export constants from the package:

import {
  AUTHX_APPS_COLLECTION,
  AUTHX_TOKENS_COLLECTION,
  AUTHX_REVOCATIONS_COLLECTION,
  AUTHX_AUDIT_COLLECTION,
} from "@x12i/authx-token-store-mongo";

Indexes

Created automatically by ensureAuthxIndexes(db):

| Collection | Indexes | | --- | --- | | authx_apps | Unique appId; status | | authx_tokens | Unique tokenId; appId, ownerIdentityId, status; TTL on expiresAt (sparse) | | authx_token_revocations | Unique tokenId; appId, ownerIdentityId | | authx_token_audit_events | Unique eventId; appId, tokenId; createdAt descending |

Call manually if needed:

import { ensureAuthxIndexes } from "@x12i/authx-token-store-mongo";

await ensureAuthxIndexes(db);

Secrets storage

App secrets live in authx_app_secrets, separate from public app metadata in authx_apps. This mirrors the in-memory store design and keeps secrets out of list/get projections on apps.

Each record matches AuthxAppSecretRecord:

{
  appId: string;
  secretKeyRef: string;
  secretKey: string;
  keyVersion: number;
  previousSecretKey?: string;
  previousKeyVersion?: number;
  createdAt: string;
  updatedAt: string;
}

See docs/app-secret-management.md.

Docker example

docker run -d --name authx-mongo -p 27017:27017 mongo:7

MONGODB_URI=mongodb://localhost:27017/authx \
MONGODB_DB=authx \
AUTHX_STORE=mongo \
npm run dev:service

Exports

| Export | Description | | --- | --- | | connectMongoStores(uri, dbName?) | Connect client, return { client, db, stores } | | createMongoStores(options) | Build stores from existing Db | | ensureAuthxIndexes(db) | Create all indexes | | newAuditEventId() | UUID helper | | Collection name constants | See above |

Development

npm run build -w @x12i/authx-token-store-mongo
npm test -w @x12i/authx-token-store-mongo

Tests use mongodb-memory-server — no local MongoDB required for CI.

Source: src/mongo-stores.ts, src/indexes.ts, src/collections.ts.

Related packages

| Package | Role | | --- | --- | | @x12i/authx-token-store | Interface definitions | | @x12i/authx-token-service | HTTP service with AUTHX_STORE=mongo | | @x12i/authx-token-types | Stored document types |