forgeguard

Drop-in Identity & Access Management for Node + Postgres apps.

ForgeGuard gives a host application a complete IAM backend — authentication (server sessions and bearer tokens), role-based access control, scopes/ABAC, external identity providers, SCIM provisioning, and an OAuth2 authorization server — without shipping any UI. It owns its own Postgres schema (forgeguard) and its own migrations, so it coexists with whatever tables your app already has.

Status: early. Phase 0 (packaging + migrations) is in place; auth, RBAC, scopes, providers, SCIM and the OAuth2 server land in subsequent phases.

Install

pnpm add @fieldstate/forgeguard drizzle-orm pg
# express is an optional peer, only needed for the HTTP adapter
pnpm add express

Quick start

import { createForgeGuard } from "@fieldstate/forgeguard";
import { createForgeGuardRouter } from "@fieldstate/forgeguard/express";

const fg = createForgeGuard({
  databaseUrl: process.env.DATABASE_URL,
  mode: "owns", // or "linked" to sit beside your existing auth
});

// Apply ForgeGuard's migrations into the `forgeguard` schema.
await fg.migrate();

// Mount the HTTP surface on your Express app.
app.use(await createForgeGuardRouter(fg));

Migrations

ForgeGuard ships its SQL migrations and a CLI. In dev or deploy, run:

DATABASE_URL=postgres://… pnpm exec forgeguard migrate

This creates the forgeguard schema (if needed) and applies any pending migrations, tracking applied files in forgeguard._sql_migrations. It is safe to run repeatedly.

Subpath exports

| Import | What | | --- | --- | | @fieldstate/forgeguard | Core SDK — createForgeGuard(), services, types | | @fieldstate/forgeguard/express | Mountable Express router + middleware | | @fieldstate/forgeguard/schema | Drizzle table definitions (all in the forgeguard schema) |

Configuration

createForgeGuard(options) accepts a connection (databaseUrl or a shared Drizzle db), mode (owns | linked), and optional session, tokens, oauth2, email, federation, passwordPolicy, and lockoutPolicy settings. Most have process.env fallbacks (DATABASE_URL, SESSION_SECRET, OAUTH_ISSUER, GITHUB_*, GOOGLE_*, …).