Database

The IAM service stores all persistent auth state in MySQL. The IAM schema includes four tables: users for account data, api_tokens for machine-to-machine credentials, refresh_tokens for session credentials, and mfa_codes for pending multi-factor authentication challenges. A fifth related table, visitors, is created and managed by the bot-detector service but referenced by a foreign key from users.

Access tokens are not stored in the database. They live exclusively in an in-memory LRU cache with a configurable maximum size and TTL. This keeps token verification fast and makes individual token revocation immediate without database writes.

The service maintains two MySQL connection pools: a promise-based pool for all auth operations and a callback-based pool for rate limiting. A third data store, an LMDB key-value database, holds a read-only list of disposable email domains used during signup validation.

Connection Architecture

Pool Types

The service creates two separate MySQL pools at startup. They serve different purposes and use different MySQL2 APIs.

Both pools are configured from the store section of the service configuration:

Disposable Email Store

The third data connection is an LMDB database opened in read-only, compressed mode. It contains a precomputed list of disposable email domains (services like Mailinator, Guerrilla Mail, etc.). During signup, the service extracts the domain from the user's email address and checks it against this store. If the domain is found, the signup request is rejected.

LMDB is a memory-mapped key-value store that does not require a separate server process. The data file is bundled with the shield-base-cli package and loaded at startup.

Initialization Order

All three stores are initialized inside the configuration() function, which must be called before any route handler runs:

The service exports accessor functions for each store. All three throw if called before configuration() has run:

Schema

users Table

The users table stores account credentials, profile data, OAuth provider references, and a foreign key to the visitors table managed by the bot-detector.

Foreign Key: visitor_id

FOREIGN KEY (visitor_id) REFERENCES visitors(visitor_id)
  ON UPDATE CASCADE
  ON DELETE RESTRICT

The ON DELETE RESTRICT constraint prevents deleting a visitor record while a user row still references it. The ON UPDATE CASCADE constraint propagates visitor ID changes (if any) to the user row automatically. This ensures the link between a user and their device fingerprint is never broken.

Password Hashing

Passwords are hashed with Argon2id before storage. The password configuration section controls the hashing parameters:

api_tokens Table

The api_tokens table stores hashed machine-to-machine credentials together with the public identifier and metadata used by the verification and dashboard management flows. For the full lifecycle and route behavior, see API Tokens.

Foreign key: user_id

CONSTRAINT users_api_keys
  FOREIGN KEY (user_id) REFERENCES users(id)
  ON DELETE CASCADE

The ON DELETE CASCADE constraint ensures that deleting a user automatically deletes all of their API tokens. No orphaned machine-to-machine credentials remain after account deletion.

Indexes

The service creates three explicit indexes for the most common API-token lookup patterns:

refresh_tokens Table

The refresh_tokens table holds hashed refresh tokens, their validity state, and usage metadata. For a full guide on the refresh token lifecycle (generation, verification, consumption, rotation, revocation), see Refresh Tokens.

Foreign Key: user_id

FOREIGN KEY (user_id) REFERENCES users(id)
  ON DELETE CASCADE

The ON DELETE CASCADE constraint ensures that deleting a user automatically deletes all their refresh tokens. No orphaned sessions remain after account deletion.

mfa_codes Table

The mfa_codes table stores pending MFA verification codes. Each row represents a single challenge that a user must complete to finalize authentication. Rows are deleted after successful verification or when they expire.

Indexes

The table has four indexes beyond the primary key to support the common query patterns:

Foreign Keys

CONSTRAINT users_mfa
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE

CONSTRAINT token_mfa
  FOREIGN KEY (token) REFERENCES refresh_tokens(token) ON DELETE CASCADE

Both cascade on delete. Deleting a user wipes their pending MFA codes. Deleting (or revoking) the refresh token that initiated the MFA flow also removes the pending code, because the session no longer exists.

visitors Table (External)

The visitors table is created and managed by the bot-detector service, not by the IAM service. It is documented here because the users table references it through a foreign key.

Access Token Cache

Access tokens are not stored in any database table. Instead, the service maintains an in-memory LRU cache. When an access token is generated, it is added to the cache. When a request arrives with an access token, the service checks the cache first. If the token is present and has not expired, it is valid. If it is not in the cache, the token is verified cryptographically from the JWT signature.

The cache is configured from the JWT configuration section:

The LRU cache provides two benefits:

1. Early rejection and metadata binding. Missing or invalid cache entries fail before JWT verification, and valid cache entries provide the expected userId, jti, visitorId, and roles used during claim validation.
2. Immediate revocation. Deleting an entry from the cache makes the next verification fail immediately, without waiting for JWT expiry.

Hashing Utilities

The service uses two utility functions for all token hashing operations. Both enforce SHA-256 hex format and are used by refresh token, MFA code, and access token flows.

toDigestHex

Accepts any string input and ensures it becomes a SHA-256 hex digest. If the input is already a 64-character hex string matching the SHA-256 pattern, it passes through unchanged. Otherwise, the function computes sha256(input) and returns the hex digest.

import { toDigestHex } from '@riavzon/auth'

const result = await toDigestHex(rawToken)
// result.input the SHA-256 hex string
// result.wasHashed true if the input was already a valid SHA-256 hex,
//                    false if the function had to compute the hash

This function uses Zod validation internally to determine whether the input matches the SHA-256 hex pattern. The idempotent design means you can safely pass either a raw token or an already-hashed value without producing a double hash.

ensureSha256Hex

Strict validation function. Checks that the input is already a valid SHA-256 hex string (exactly 64 lowercase hex characters). If the validation fails, it throws an error. This function does not compute a hash; it only validates format.

import { ensureSha256Hex } from '@riavzon/auth'

ensureSha256Hex(tokenHash) // throws if not a valid SHA-256 hex string

Used as a guard before database operations to ensure that only properly formatted hashes reach the token and code_hash columns.

Entity Relationship

The five related tables form a simple hierarchy. The bot-detector's visitors table sits at the root and the IAM service owns the other four:

visitors (bot-detector)
  └── users (IAM)
  ├── api_tokens (IAM)
        ├── refresh_tokens (IAM)
        │     └── mfa_codes (IAM, via token FK)
        └── mfa_codes (IAM, via user_id FK)

• A visitor can have zero or more users though typically one.
• A user can have zero or more API tokens.
• A user can have zero or more refresh tokens one per active session/device.
• A user can have at most one pending MFA code enforced by UNIQUE on user_id.
• An MFA code is also linked to a specific refresh token the session that triggered the MFA challenge.

Cascade deletes flow downward: deleting a visitor is blocked, deleting a user cascades to their API tokens, refresh tokens, and MFA codes, and deleting a refresh token cascades to any MFA code tied to that session.