Dravyn Auth, end to end

What Dravyn Auth is

A self-hosted authentication service, built once and reused by every Dravyn product — and sold to other developers the same way Clerk or Auth0 is, complete with a self-serve signup portal.

Instead of every new app (ClassSync, Cashlet, whatever comes next) reimplementing registration, password hashing, email OTP verification, JWTs, and session handling, they all point at one running instance of Dravyn Auth. Each app registers as a project and gets its own key — its users are fully isolated from every other project's, even though they share the same database and server.

It's no longer just an internal tool, either: the developer portal means an outside developer can sign up, create a project, brand it with their own name and color, generate API keys, register webhooks, define roles, and manage it all themselves — the same product-as-a-service loop as the tools it's modeled on.

It is not a wrapper around Supabase Auth or Firebase. It's a plain NestJS HTTP API backed by your own Postgres database, with no third-party auth dependency in the request path — the only external free services it touches are Postgres, Resend (email), and Google/GitHub's OAuth endpoints, all swappable via environment variables.

Core concepts

These nouns explain almost everything else in this document.

Project

One tenant — one app integrating Dravyn Auth. Has a publicKey (pk_…, safe to ship in client code), a secretKey (sk_…, shown once), and now optional displayName/primaryColor branding used in every email it sends. A default project is seeded for zero-config local use; a reserved platform project is seeded for the portal itself.

Owner

A developer using Dravyn Auth as a product. Not a separate system — an Owner is just a regular User who happens to belong to the reserved platform project. They sign up and log in through the exact same /v1/auth/* endpoints as anyone else, then use /v1/owner/* routes to manage the projects they own.

User

Scoped to a project — the same email can exist once per project, not once globally. Has an optional passwordHash (null for OAuth-only accounts), an emailVerifiedAt timestamp gating login, and optional MFA fields.

Session

One row per refresh-token family. Holds a hash of the current refresh secret, device metadata, and timestamps. Rotates in place on every /refresh call rather than accumulating rows.

Access / Refresh token

A short-lived RS256 JWT (default 15 min) proves identity on every request — now carrying roles and permissions claims too. A longer-lived opaque refresh token (default 30 days) exchanges for a new pair.

Role / Permission

A Role is a named set of permission strings ("admin" → ["billing.manage"]), scoped to a project. Assigning a role to a user embeds its permissions directly in their next access token — no extra API call needed to check them.

API Key

A machine-to-machine credential scoped to a project (ak_…). sha256-hashed at rest, authenticates server-to-server calls via x-api-key instead of a user session.

Webhook

A URL a project registers to receive HMAC-signed POST requests when events happen (user created, logged in, etc). Delivery retries on failure with exponential backoff.

Organization

A group of a project's end users who share access to something — like a workspace. Not to be confused with a Project or an Owner. Members join via emailed invite links.

OTP

A 6-digit, bcrypt-hashed, 10-minute-lived code used for email verification and password reset.

Feature matrix

What's actually running today versus what's still a config decision away from being real (billing).

Security model

Why refresh rotation matters

Each successful /refresh call generates a new secret and overwrites the session's stored hash — the old refresh token stops working the instant a new one is issued. If that old token is ever presented again, the session is revoked outright rather than just rejected. Verified during development: reusing a rotated-out token returns 401 and the session disappears from /v1/auth/sessions.

Why the MFA challenge token can't be reused

Login for an MFA-enabled user returns { mfaRequired: true, mfaToken } instead of real tokens. That mfaToken is structurally a JWT signed with the same key as a real access token — so JwtStrategy explicitly checks for the mfaChallenge claim and throws 401 MFA_REQUIRED if it's present, on every route except the one dedicated, manually-verified /mfa/challenge endpoint. Verified: presenting an mfaToken to /v1/auth/me is rejected.

Rate limits

Getting started

1. Node 20+, pnpm (corepack enable), and a Postgres database — local via Homebrew, or free-tier Supabase for a hosted one.
2. cd backend && cp .env.example .env
3. node scripts/generate-keys.js — prints a fresh RS256 keypair, paste into .env.
4. openssl rand -hex 32 — paste into MFA_ENCRYPTION_KEY.
5. pnpm run prisma:migrate --name init && pnpm run seed — creates the schema, the default project, and the reserved platform project (prints its public key — you'll need it for the portal).
6. pnpm run dev:api — API on :4000, docs at /api/docs.
7. Optional: cd apps/portal && cp .env.example .env, paste the platform public key into VITE_PLATFORM_PUBLIC_KEY, then pnpm run dev — portal on :5174.

Using the SDK

Framework-agnostic core

// pnpm add @dravyn/auth-js (workspace:*, until published)
import { DravynAuthClient } from '@dravyn/auth-js';

const auth = new DravynAuthClient({
  baseUrl: 'http://localhost:4000',
  publicKey: 'pk_your_project_key', // omit to use the default project
});

await auth.register('jane@site.com', 'correct-horse-battery');
await auth.verifyOtp('jane@site.com', '123456'); // signs in on success

// login() returns the user OR { mfaRequired: true, mfaToken }
const result = await auth.login('jane@site.com', 'correct-horse-battery');
if ('mfaRequired' in result) {
  await auth.completeMfaChallenge(result.mfaToken, '482913');
}

// roles/permissions are right there on the user object — no extra call
const me = auth.getUser(); // { id, email, roles: ['admin'], permissions: ['billing.manage'], ... }

MFA & Organizations

const { qrCodeDataUrl, secret } = await auth.setupMfa();
// render qrCodeDataUrl as an <img>, user scans it, then:
const { backupCodes } = await auth.confirmMfaSetup('482913'); // show these once

const org = await auth.createOrg('Acme Workspace');
await auth.inviteOrgMember(org.id, 'teammate@acme.com');

React

import { AuthProvider, useAuth } from '@dravyn/auth-js/react';

function Root() {
  return (
    <AuthProvider baseUrl="http://localhost:4000" publicKey="pk_…">
      <App />
    </AuthProvider>
  );
}

function LoginForm() {
  const { login, completeMfaChallenge, user, isAuthenticated, logout } = useAuth();
}

Wrap anything behind auth in <ProtectedRoute fallback={<LoginForm />}>. Tokens persist to localStorage by default; pass a storage adapter backed by @react-native-async-storage/async-storage for React Native / Expo (ClassSync's stack).

Completing an OAuth redirect

Google/GitHub callbacks redirect with tokens in the URL fragment (never sent to servers or logged) — call this once on that page:

const user = await auth.completeOAuthFromUrl(); // reads window.location, signs in

Platform-admin dashboard

A small React/Vite app at apps/dashboard (port 5173) for you, the operator, to see every project regardless of who owns it — create projects, copy key pairs, browse users. Gated by ADMIN_BOOTSTRAP_KEY, remembered in localStorage. This is the "god mode" view; day-to-day project management is what the portal below is for.

Developer portal

This is the page: a real product-as-a-service signup flow where any developer creates their own account, spins up projects, and customizes how Dravyn Auth presents itself to their users.

Lives at apps/portal (port 5174), built entirely on @dravyn/auth-js and @dravyn/ui — it doubles as the SDK's own proving ground. Sign-up/login is genuinely full auth: OTP verification, forgot/reset password, and MFA challenge screens all wired through the SDK exactly as an external consumer would use it.

What an owner can do, per project

• Branding — set a display name and accent color, with a live preview of the actual verification email. This is what makes emails say "Acme Inc" in Acme's orange instead of "Dravyn Auth" in teal.
• Users — read-only list of that project's end users.
• API Keys — generate/revoke machine-to-machine credentials.
• Webhooks — register endpoints, pick events, inspect delivery history (status, response code, retry schedule) in a modal.
• Roles — define roles with comma-separated permissions, assign them to users by email.
• Audit Log — chronological feed of everything that's happened in the project.

Why owners are just users

Rather than build a second parallel identity system, an "owner" is a User row that happens to belong to the reserved platform project (seeded automatically, see Getting started). Signing up as a developer goes through the exact same /v1/auth/register → OTP → /v1/auth/login flow as any end user of any other project — Dravyn Auth authenticates its own customers using itself. The only new code is the OwnerGuard, which checks that a request's JWT belongs to a platform-project user before allowing it near /v1/owner/*, and that any projectId in the URL is actually owned by that caller.

@dravyn/ui

@dravyn/ui@0.2.1 is the component library both frontends are built from — Button, Card, Input, Textarea, Badge, Alert, Avatar, Toggle, Modal, Spinner — dark-first, zero runtime dependencies besides React, published and live on npm today.

import '@dravyn/ui/tokens'; // once, at the root — loads the CSS variables every component reads
import { Button, Card, Badge } from '@dravyn/ui';

Component styles auto-inject on import — no separate CSS file to remember. Requires React 18+ (for useId, used internally to keep field ids collision-free). Card now also accepts a plain style prop for one-off spacing, added while building the portal.

Deploying for free

Same environment variables as local dev; set NODE_ENV=production, a real CORS_ORIGINS allowlist (both frontend origins), a strong MFA_ENCRYPTION_KEY, and rotate ADMIN_BOOTSTRAP_KEY away from the development placeholder.

What's left

Two things, both requiring your input rather than more code:

• Stripe billing — needs a real Stripe account, price IDs, and a webhook secret before it can be built.
• The @dravyn/auth-js npm conflict — the SDK described in §08 is complete and verified, but hasn't been published, because the name is already taken by an incompatible prototype from a different repo. Resolving this — republish over it, or ship under a new name — is a decision, not a build task.

Everything else from the original product plan — RBAC, API keys, webhooks, audit log, MFA, organisations, per-project branding, and a self-serve portal to manage all of it — is implemented and was exercised end-to-end through an actual browser session, not just curl.