Vaultly

RS256 with Locally-Managed RSA Key Pair

The auth server owns an RSA key pair. Private key signs all JWTs; public key is served at /jwks.json. Any service can verify tokens without ever holding a shared secret. Just fetch the public key and verify the signature locally.

// JWT payload structure
{
  "sub": "user-uuid",
  "email": "user@example.com",
  "role": "admin",                 // RBAC role
  "org_id": "org-uuid",           // tenant scope
  "org_role": "member",           // org-level role
  "token_version": 3,             // for invalidation
  "iat": 1718000000,
  "exp": 1718000900               // 15-min access token
}

// JWKS endpoint response
GET /jwks.json
{
  "keys": [{
    "kty": "RSA",
    "use": "sig",
    "alg": "RS256",
    "kid": "2025-06",
    "n": "...",   // public modulus
    "e": "AQAB"
  }]
}

Why RS256 over HS256? With HS256, every verifying service needs the shared secret, which can leak. RS256 lets you publish the public key openly. Compromise of any downstream service cannot be used to forge tokens.

Organisation Data Model

-- Core tables (simplified)
CREATE TABLE users (
  id            UUID PRIMARY KEY,
  email         TEXT UNIQUE NOT NULL,
  password_hash TEXT,                    -- null for OAuth users
  mfa_secret    TEXT,                    -- encrypted
  mfa_enabled   BOOLEAN DEFAULT false,
  token_version INT DEFAULT 0,           -- invalidation counter
  created_at    TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE organisations (
  id         UUID PRIMARY KEY,
  name       TEXT NOT NULL,
  slug       TEXT UNIQUE NOT NULL,
  owner_id   UUID REFERENCES users(id),
  created_at TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE org_members (
  org_id     UUID REFERENCES organisations(id),
  user_id    UUID REFERENCES users(id),
  role       TEXT CHECK (role IN ('admin','member','viewer')),
  joined_at  TIMESTAMPTZ DEFAULT now(),
  PRIMARY KEY (org_id, user_id)
);

CREATE TABLE org_invitations (
  id          UUID PRIMARY KEY,
  org_id      UUID REFERENCES organisations(id),
  email       TEXT NOT NULL,
  role        TEXT NOT NULL,
  token       TEXT UNIQUE NOT NULL,    -- signed invite token
  expires_at  TIMESTAMPTZ NOT NULL,   -- 48hr window
  accepted_at TIMESTAMPTZ,
  created_at  TIMESTAMPTZ DEFAULT now()
);

RBAC Model

Role is included in the JWT payload (org_role) and enforced via Express middleware on every protected route; no additional DB lookup needed for permission checks on hot paths.

Org Switcher: Scoped JWT Reissue

When a user switches organisations, the auth server issues a new JWT scoped to the target org. The BFF updates the session and calls router.refresh() to revalidate all Server Components with the new org context. Stale tokens are detected server-side and silently reissued before the component renders.

Drizzle ORM over Prisma

Drizzle is closer to raw SQL: schema definitions are TypeScript, queries compose like SQL. For a system where understanding exactly what hits the database matters, this beats Prisma's magic. Query performance is fully predictable.

iron-session over NextAuth

NextAuth abstracts away exactly the things I needed to understand: how the session is stored, what's in the cookie, how expiry works. iron-session gives encrypted HTTP-only cookies with zero magic. Every byte in the cookie is mine to control.

pnpm workspaces monorepo

Auth server and Next.js BFF share TypeScript types (request/response shapes, JWT payload). A monorepo with a shared `packages/types` package means a change to the JWT payload is a compile error in both services immediately.

otplib for TOTP

RFC 6238 compliant, actively maintained, and the verify function handles the ±1 window (clock skew) correctly. Building TOTP from scratch would be a security anti-pattern.

Resend for invitation emails

Email deliverability is an operational problem, not an engineering one. Resend provides a clean API, good developer experience, and handles SPF/DKIM. Invitation tokens are signed server-side; Resend only delivers the link.