@x12i/authx-token-store

Storage abstractions for AuthX: apps, secrets, tokens, revocations, and audit events. Includes an in-memory implementation for development and testing.

Part of the AuthX monorepo. See the root README for the full system.

Install

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

For production persistence, use @x12i/authx-token-store-mongo instead.

Purpose

This package defines interfaces (AuthxStores) that the token service and custom integrations implement against. Splitting storage from crypto (token-core) keeps the service testable and allows swapping backends.

token-service  →  AuthxStores  →  memory | mongo | (your adapter)

Store bundle

interface AuthxStores {
  apps: AuthxAppStore;
  tokens: AuthxTokenStore;
  revocations: AuthxRevocationStore;
  audit: AuthxAuditStore;
}

Interfaces

AuthxAppStore

| Method | Description | | --- | --- | | saveApp(app) | Create or replace app descriptor | | getAppById(appId) | Get app (no secret) | | listApps() | List all apps | | updateApp(appId, patch) | Partial update | | saveAppSecret(record) | Store signing secret separately | | getAppSecret(appId) | Load secret for verify/issue |

AuthxAppSecretRecord fields: appId, secretKeyRef, secretKey, keyVersion, previousSecretKey?, previousKeyVersion?, timestamps.

AuthxTokenStore

| Method | Description | | --- | --- | | saveToken(descriptor) | Persist issued token metadata | | getTokenById(tokenId) | Lookup by ID | | listTokens(filter?) | Filter by appId, ownerIdentityId, status, paginate with limit/offset | | updateTokenStatus(tokenId, status) | Mark active or revoked |

AuthxRevocationStore

| Method | Description | | --- | --- | | revokeToken(record) | Revoke single token | | isRevoked(tokenId) | Check revocation (used during verify) | | listRevokedByApp(appId) | List revocations for app | | listRevokedByIdentity(identityId) | List revocations for identity | | revokeAllForApp(appId, reason?) | Bulk revoke — returns count | | revokeAllForIdentity(identityId, reason?) | Bulk revoke — returns count |

AuthxAuditStore

| Method | Description | | --- | --- | | appendEvent(event) | Append audit event | | listEvents(filter?) | Filter by appId, tokenId, limit |

In-memory implementation

For local dev, tests, and ephemeral deployments:

import { createInMemoryStores, createAuditEvent } from "@x12i/authx-token-store";

const stores = createInMemoryStores();

await stores.apps.saveApp({ /* AuthxAppDescriptor */ });
await stores.apps.saveAppSecret({ /* AuthxAppSecretRecord */ });

await stores.audit.appendEvent(
  createAuditEvent({ eventType: "app.created", appId: "my-app" }),
);

Caveat: Data is lost when the process exits. The token service uses this when AUTHX_STORE=memory.

Implementing a custom backend

Implement all four interfaces and return them from a factory:

import type { AuthxStores } from "@x12i/authx-token-store";

export async function createPostgresStores(/* ... */): Promise<AuthxStores> {
  return {
    apps: { /* ... */ },
    tokens: { /* ... */ },
    revocations: { /* ... */ },
    audit: { /* ... */ },
  };
}

Wire into the service:

import { AuthxTokenService } from "@x12i/authx-token-service"; // see service README
const stores = await createPostgresStores();
const service = new AuthxTokenService(stores, "authx");

Reference implementation: @x12i/authx-token-store-mongo.

Audit helper

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

const event = createAuditEvent({
  eventType: "token.issued",
  appId: "my-app",
  tokenId: "tok_abc",
  identityId: "user-1",
});
// Adds eventId (UUID) and createdAt automatically

Common event types used by the service: app.created, app.updated, token.issued, token.revoked, token.revoked.all.app, token.revoked.all.identity.

Development

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

Source: src/interfaces.ts, src/memory.ts.

Related packages

| Package | Role | | --- | --- | | @x12i/authx-token-types | Descriptor and event types | | @x12i/authx-token-store-mongo | MongoDB implementation | | @x12i/authx-token-service | Uses stores via AuthxTokenService |