crossly.client.auth.service 0.0.1

package/src/createApp.ts

@@ -0,0 +1,45 @@
+import express, { type Express, type Request, type Response } from 'express';
+import cors from 'cors';
+import cookieParser from 'cookie-parser';
+import { AuthController } from './controllers/authController.js';
+import { AuthManager } from './managers/authManager.js';
+import type { IJwtSigner } from './signer/types.js';
+import type { IClientRepository } from './repository/types.js';
+import type { IOidcProvider } from './oidc/types.js';
+import type { AuthConfig } from './config.js';
+
+/** Collaborators the app is built from. Injected so tests can swap in fakes. */
+export interface AppDependencies {
+    signer: IJwtSigner;
+    clients: IClientRepository;
+    oidc: IOidcProvider;
+    config: AuthConfig;
+}
+
+/**
+ * Builds the configured Express application (CORS w/ credentials, JSON + cookie
+ * parsing, /health, and the auth routes) from its dependencies, WITHOUT binding
+ * a port.
+ *
+ * The entry point (app.ts) and the integration tests share this factory so they
+ * exercise the same wiring; only the injected collaborators differ (real
+ * Postgres + Google at runtime; in-memory repo + fake provider in tests).
+ */
+export function createApp({ signer, clients, oidc, config }: AppDependencies): Express {
+    const app = express();
+
+    // Credentialed CORS so the browser sends/receives the httpOnly session cookie.
+    app.use(cors({ origin: config.corsOrigin, credentials: true }));
+    app.use(express.json());
+    app.use(cookieParser(config.cookieSecret));
+
+    app.get('/health', (_req: Request, res: Response) => {
+        res.json({ status: 'ok' });
+    });
+
+    const manager = new AuthManager(signer, clients);
+    const controller = new AuthController(manager, oidc, config);
+    app.use('/api/v1/auth', controller.router);
+
+    return app;
+}

package/src/db/migrate.ts

@@ -0,0 +1,106 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import pg from 'pg';
+
+/**
+ * Forward-only migration runner, safe to run from several instances at once.
+ *
+ * Applies every `.sql` file in ./migrations (sorted by filename) that has not yet
+ * been recorded in `schema_migrations`, each in its own transaction. A cluster-wide
+ * Postgres advisory lock serializes migrators: the first caller applies the pending
+ * files; any others block on the lock, then acquire it, see everything already
+ * applied, and do nothing. The lock is session-scoped and held on a single dedicated
+ * connection for the whole run, so it also auto-releases if the process crashes.
+ *
+ * Connection comes from DATABASE_URL; the default targets the local dev Postgres in
+ * docker-compose.yml. Run standalone with `npm run migrate`, or it runs on service
+ * startup (see app.ts).
+ */
+// Host port 5433 (see docker-compose.yml) so the dev container can coexist with a
+// native Postgres that already owns 5432.
+const DEFAULT_DATABASE_URL = 'postgres://crossly:crossly@127.0.0.1:5433/crossly_auth';
+const MIGRATIONS_DIR = join(process.cwd(), 'migrations');
+
+/** The Postgres connection string for the service (env override, else dev default). */
+export function databaseUrl(): string {
+    return process.env.DATABASE_URL ?? DEFAULT_DATABASE_URL;
+}
+
+// Constant key for the advisory lock that serializes migrations cluster-wide.
+// Any fixed value works as long as it is unique to this concern.
+const MIGRATION_LOCK_KEY = 4242420001;
+
+export async function runMigrations(connectionString: string = databaseUrl()): Promise<void> {
+    const pool = new pg.Pool({ connectionString });
+    try {
+        await migrateWithPool(pool);
+    } finally {
+        await pool.end();
+    }
+}
+
+async function migrateWithPool(pool: pg.Pool): Promise<void> {
+    // Hold the advisory lock and run every migration on ONE connection so the
+    // session-scoped lock spans the entire run.
+    const client = await pool.connect();
+    try {
+        await client.query('SELECT pg_advisory_lock($1::bigint)', [MIGRATION_LOCK_KEY]);
+
+        await client.query(
+            `CREATE TABLE IF NOT EXISTS schema_migrations (
+                name       TEXT PRIMARY KEY,
+                applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+            )`,
+        );
+
+        const files = readdirSync(MIGRATIONS_DIR)
+            .filter((file) => file.endsWith('.sql'))
+            .sort();
+
+        for (const file of files) {
+            const applied = await client.query('SELECT 1 FROM schema_migrations WHERE name = $1', [
+                file,
+            ]);
+            if ((applied.rowCount ?? 0) > 0) {
+                console.log(`skip   ${file}`);
+                continue;
+            }
+
+            const sql = readFileSync(join(MIGRATIONS_DIR, file), 'utf8');
+            try {
+                await client.query('BEGIN');
+                await client.query(sql);
+                await client.query('INSERT INTO schema_migrations (name) VALUES ($1)', [file]);
+                await client.query('COMMIT');
+                console.log(`apply  ${file}`);
+            } catch (error) {
+                await client.query('ROLLBACK');
+                throw error;
+            }
+        }
+
+        console.log('migrations complete');
+    } finally {
+        // Best-effort explicit unlock; releasing the connection also drops the
+        // session lock, so a failure here is harmless.
+        try {
+            await client.query('SELECT pg_advisory_unlock($1::bigint)', [MIGRATION_LOCK_KEY]);
+        } catch {
+            // ignore
+        }
+        client.release();
+    }
+}
+
+// CLI entrypoint: only runs when invoked directly (`node dist/db/migrate.js`),
+// not when imported by the app for startup migration.
+const invokedDirectly =
+    process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+    runMigrations().catch((error) => {
+        console.error('migration failed:', error);
+        process.exit(1);
+    });
+}

package/src/managers/authManager.ts

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto';
+import type {
+    AccessTokenClaims,
+    GuestSessionResponse,
+    MeResponse,
+} from '@textyly/crossly-client-auth-contracts';
+import type { IAuthManager, ResolvedLogin } from './types.js';
+import type { IJwtSigner } from '../signer/types.js';
+import type { IClientRepository } from '../repository/types.js';
+import type { OidcIdentity } from '../oidc/types.js';
+
+/**
+ * Sessions are valid for 1 year. Combined with refresh-on-use
+ * ({@link AuthManager.refreshSession}), an active anonymous user effectively
+ * never loses their session — it only lapses after a full year of inactivity.
+ */
+const SESSION_TTL_SECONDS: number = 60 * 60 * 24 * 365;
+
+/**
+ * Default {@link IAuthManager} implementation.
+ *
+ * - {@link createGuestSession} mints a brand-new anonymous session (new clientId).
+ * - {@link refreshSession} re-issues a token for an existing session, preserving
+ *   its identity but resetting the expiry (a sliding/rolling session).
+ * - {@link validate} verifies a token and returns its claims (used by the gateway).
+ * - {@link resolveLogin} maps a verified provider identity to a stable clientId,
+ *   promoting the current guest in place on first login.
+ *
+ * Token signing/verification is delegated to the injected {@link IJwtSigner};
+ * account persistence to the injected {@link IClientRepository}.
+ */
+export class AuthManager implements IAuthManager {
+    public constructor(
+        private readonly signer: IJwtSigner,
+        private readonly clients: IClientRepository,
+    ) {}
+
+    public async createGuestSession(): Promise<GuestSessionResponse> {
+        const clientId = randomUUID();
+        const { token, expiresAt } = await this.signer.sign(clientId, true, SESSION_TTL_SECONDS);
+
+        return { token, clientId, expiresAt };
+    }
+
+    public async createAuthenticatedSession(clientId: string): Promise<GuestSessionResponse> {
+        const { token, expiresAt } = await this.signer.sign(clientId, false, SESSION_TTL_SECONDS);
+        return { token, clientId, expiresAt };
+    }
+
+    public async describeSession(token: string): Promise<MeResponse> {
+        const claims = await this.signer.verify(token);
+        if (claims.guest) {
+            return { clientId: claims.sub, guest: true };
+        }
+
+        // Authenticated: surface the stored email (display only) if we have one.
+        const client = await this.clients.findById(claims.sub);
+        return { clientId: claims.sub, guest: false, email: client?.email };
+    }
+
+    public async refreshSession(token: string): Promise<GuestSessionResponse> {
+        // Verify the current token; throws if it is invalid or expired.
+        const claims = await this.signer.verify(token);
+
+        // Re-issue for the SAME identity with a fresh expiry, so an active user's
+        // session keeps rolling forward.
+        const reissued = await this.signer.sign(claims.sub, claims.guest, SESSION_TTL_SECONDS);
+
+        return { token: reissued.token, clientId: claims.sub, expiresAt: reissued.expiresAt };
+    }
+
+    public validate(token: string): Promise<AccessTokenClaims> {
+        // Verify signature + expiry; resolves with the claims or rejects.
+        return this.signer.verify(token);
+    }
+
+    public async resolveLogin(
+        identity: OidcIdentity,
+        guestClientId?: string,
+    ): Promise<ResolvedLogin> {
+        const existing = await this.clients.findByProvider(identity.provider, identity.subject);
+        if (existing) {
+            // Returning user on this provider — recognized on any device. The
+            // current guest id (if any) is discarded by the caller; this account's
+            // id wins.
+            await this.clients.touchLastLogin(existing.clientId);
+            return { clientId: existing.clientId, created: false, promoted: false };
+        }
+
+        // New external identity. Promote the current guest in place if one is
+        // present (the account adopts the guest's id, so the guest's data on this
+        // device carries over with no migration); otherwise mint a fresh id.
+        const promoted = guestClientId !== undefined;
+        const clientId = guestClientId ?? randomUUID();
+
+        await this.clients.create({
+            clientId,
+            provider: identity.provider,
+            providerSubject: identity.subject,
+            email: identity.email,
+        });
+
+        return { clientId, created: true, promoted };
+    }
+}

package/src/managers/types.ts

@@ -0,0 +1,59 @@
+import type {
+    AccessTokenClaims,
+    GuestSessionResponse,
+    MeResponse,
+} from '@textyly/crossly-client-auth-contracts';
+import type { OidcIdentity } from '../oidc/types.js';
+
+/**
+ * Outcome of resolving a verified provider identity to a stable client.
+ */
+export interface ResolvedLogin {
+    /** The stable client id (== token `sub`) this login resolves to. */
+    clientId: string;
+    /** True if a new `clients` row was written (a brand-new account or a promotion). */
+    created: boolean;
+    /** True if an existing guest was promoted in place (its id became the account). */
+    promoted: boolean;
+}
+
+/**
+ * Business operations for client authentication. Sits between the controllers
+ * (HTTP) and the signer (token issuance/verification) + client repository.
+ */
+export interface IAuthManager {
+    /** Create a fresh anonymous guest session (new clientId + signed token). */
+    createGuestSession(): Promise<GuestSessionResponse>;
+
+    /** Mint an authenticated (guest:false) session token for an existing clientId. */
+    createAuthenticatedSession(clientId: string): Promise<GuestSessionResponse>;
+
+    /**
+     * Verify a token and describe the session for the UI: `{ clientId, guest, email? }`.
+     * Email is looked up for authenticated users; guests have none. Throws if the
+     * token is invalid or expired.
+     */
+    describeSession(token: string): Promise<MeResponse>;
+
+    /**
+     * Re-issue a token for the session identified by `token`, preserving its
+     * identity (clientId) but resetting the expiry. Throws if the token is
+     * invalid or expired.
+     */
+    refreshSession(token: string): Promise<GuestSessionResponse>;
+
+    /**
+     * Verify a token and return its claims. Throws if the token is invalid or
+     * expired. Used by the gateway (ForwardAuth) to turn a token into a trusted
+     * clientId.
+     */
+    validate(token: string): Promise<AccessTokenClaims>;
+
+    /**
+     * Resolve a verified provider identity to a stable clientId:
+     * - existing `(provider, subject)` → that client (returning user, any device);
+     * - else, a guest is present → **promote in place** (reuse `guestClientId`);
+     * - else → create a brand-new client.
+     */
+    resolveLogin(identity: OidcIdentity, guestClientId?: string): Promise<ResolvedLogin>;
+}

package/src/oidc/googleProvider.ts

@@ -0,0 +1,72 @@
+import * as oidc from 'openid-client';
+import type { IOidcProvider, OidcIdentity } from './types.js';
+
+export interface GoogleProviderOptions {
+    clientId: string;
+    clientSecret: string;
+    /** Must exactly match an Authorized redirect URI on the Google OAuth client. */
+    redirectUri: string;
+}
+
+const GOOGLE_ISSUER = new URL('https://accounts.google.com');
+const SCOPE = 'openid email profile';
+
+/**
+ * {@link IOidcProvider} backed by Google via `openid-client` (Authorization Code
+ * + PKCE). Created with {@link GoogleProvider.create}, which performs OIDC
+ * discovery once against Google's well-known configuration.
+ *
+ * State/CSRF is handled by the controller (it owns the cookie), so the code
+ * exchange here skips openid-client's own state check.
+ */
+export class GoogleProvider implements IOidcProvider {
+    private constructor(
+        private readonly config: oidc.Configuration,
+        private readonly redirectUri: string,
+    ) {}
+
+    public static async create(options: GoogleProviderOptions): Promise<GoogleProvider> {
+        const config = await oidc.discovery(GOOGLE_ISSUER, options.clientId, options.clientSecret);
+        return new GoogleProvider(config, options.redirectUri);
+    }
+
+    public async authorizeUrl(state: string, codeVerifier: string): Promise<string> {
+        const codeChallenge = await oidc.calculatePKCECodeChallenge(codeVerifier);
+        const url = oidc.buildAuthorizationUrl(this.config, {
+            redirect_uri: this.redirectUri,
+            scope: SCOPE,
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+            state,
+        });
+        return url.href;
+    }
+
+    public async exchangeCode(
+        callbackParams: URLSearchParams,
+        codeVerifier: string,
+    ): Promise<OidcIdentity> {
+        // Rebuild the exact callback URL openid-client expects: our redirect URI
+        // plus ALL of the provider's returned params (code, state, iss, …) so its
+        // response validation (incl. the RFC 9207 issuer check) passes.
+        const currentUrl = new URL(this.redirectUri);
+        currentUrl.search = callbackParams.toString();
+
+        const tokens = await oidc.authorizationCodeGrant(this.config, currentUrl, {
+            pkceCodeVerifier: codeVerifier,
+            // The controller already validated `state` against its cookie.
+            expectedState: oidc.skipStateCheck,
+        });
+
+        const claims = tokens.claims();
+        if (!claims?.sub) {
+            throw new Error('google login did not return a subject');
+        }
+
+        return {
+            provider: 'google',
+            subject: claims.sub,
+            email: typeof claims.email === 'string' ? claims.email : undefined,
+        };
+    }
+}

package/src/oidc/notConfiguredOidcProvider.ts

@@ -0,0 +1,16 @@
+import type { IOidcProvider, OidcIdentity } from './types.js';
+
+/**
+ * Placeholder {@link IOidcProvider} used when no real provider is configured
+ * (e.g. Google client id/secret absent in local dev). Guest sessions keep
+ * working; any attempt to log in fails loudly so the controller can return 503.
+ */
+export class NotConfiguredOidcProvider implements IOidcProvider {
+    public authorizeUrl(): Promise<string> {
+        throw new Error('OIDC login is not configured');
+    }
+
+    public exchangeCode(): Promise<OidcIdentity> {
+        throw new Error('OIDC login is not configured');
+    }
+}

package/src/oidc/types.ts

@@ -0,0 +1,41 @@
+/**
+ * The identity an OIDC provider asserts after a successful login.
+ *
+ * `(provider, subject)` is the client identity key — `subject` is the provider's
+ * stable user id (their `sub`), which is the same across all of that user's
+ * devices. `email` is provider-reported and kept for display/contact only; it is
+ * NEVER used to match or link clients.
+ */
+export interface OidcIdentity {
+    /** Stable provider name, e.g. 'google'. Part of the client identity key. */
+    provider: string;
+    /** The provider's stable subject id for this user (their `sub`). */
+    subject: string;
+    /** Provider-reported email — display/contact only, never a matching key. */
+    email?: string;
+}
+
+/**
+ * Boundary to an OIDC identity provider (Google now; GitHub / Facebook / a broker
+ * like Auth0 later). Implementations own the provider-specific OAuth/OIDC
+ * mechanics; the rest of the service depends only on this interface, so adding a
+ * provider is a single new class with no changes elsewhere.
+ */
+export interface IOidcProvider {
+    /**
+     * Build the provider's authorization URL to redirect the user to
+     * (Authorization Code flow + PKCE). `state` and `codeVerifier` are generated
+     * by the caller and stashed for the callback.
+     */
+    authorizeUrl(state: string, codeVerifier: string): Promise<string>;
+
+    /**
+     * Exchange the authorization callback for the verified {@link OidcIdentity}.
+     *
+     * `callbackParams` are ALL query parameters the provider returned on the
+     * redirect (code, state, iss, …) — passed whole so the OIDC library can
+     * validate them (e.g. the RFC 9207 `iss`). `codeVerifier` is the stashed PKCE
+     * verifier.
+     */
+    exchangeCode(callbackParams: URLSearchParams, codeVerifier: string): Promise<OidcIdentity>;
+}

package/src/repository/inMemoryClientRepository.ts

@@ -0,0 +1,72 @@
+import type { ClientRecord, IClientRepository, NewClient } from './types.js';
+
+/**
+ * In-memory implementation of {@link IClientRepository}.
+ *
+ * State lives in two Maps (by clientId, and a (provider, subject) -> clientId
+ * index) and is lost on restart. Used by the unit tests and for running locally
+ * without a database; {@link PgClientRepository} is the durable implementation
+ * wired into the service at runtime. Records are cloned on the way in and out so
+ * callers cannot mutate stored state by reference.
+ */
+export class InMemoryClientRepository implements IClientRepository {
+    private readonly byClientId: Map<string, ClientRecord> = new Map();
+    private readonly byIdentity: Map<string, string> = new Map();
+
+    public async findByProvider(
+        provider: string,
+        providerSubject: string,
+    ): Promise<ClientRecord | undefined> {
+        const clientId = this.byIdentity.get(this.identityKey(provider, providerSubject));
+        if (!clientId) {
+            return undefined;
+        }
+
+        const found = this.byClientId.get(clientId);
+        return found ? { ...found } : undefined;
+    }
+
+    public async findById(clientId: string): Promise<ClientRecord | undefined> {
+        const found = this.byClientId.get(clientId);
+        return found ? { ...found } : undefined;
+    }
+
+    public async create(client: NewClient): Promise<ClientRecord> {
+        const idKey = this.identityKey(client.provider, client.providerSubject);
+
+        if (this.byClientId.has(client.clientId)) {
+            throw new Error(`client already exists: ${client.clientId}`);
+        }
+        if (this.byIdentity.has(idKey)) {
+            throw new Error(`identity already mapped: ${client.provider}/${client.providerSubject}`);
+        }
+
+        const record: ClientRecord = {
+            clientId: client.clientId,
+            provider: client.provider,
+            providerSubject: client.providerSubject,
+            email: client.email,
+            createdAt: new Date(),
+            lastLoginAt: undefined,
+        };
+
+        this.byClientId.set(record.clientId, record);
+        this.byIdentity.set(idKey, record.clientId);
+        return { ...record };
+    }
+
+    public async touchLastLogin(clientId: string): Promise<void> {
+        const existing = this.byClientId.get(clientId);
+        if (!existing) {
+            return;
+        }
+
+        existing.lastLoginAt = new Date();
+    }
+
+    // A unique key for a (provider, subject) pair. The pair is JSON-encoded so no
+    // combination of provider/subject characters can produce a colliding key.
+    private identityKey(provider: string, providerSubject: string): string {
+        return JSON.stringify([provider, providerSubject]);
+    }
+}

package/src/repository/pgClientRepository.ts

@@ -0,0 +1,75 @@
+import pg from 'pg';
+import type { ClientRecord, IClientRepository, NewClient } from './types.js';
+
+/** Raw row shape returned from the `clients` table. */
+interface ClientRow {
+    client_id: string;
+    provider: string;
+    provider_subject: string;
+    email: string | null;
+    created_at: Date;
+    last_login_at: Date | null;
+}
+
+/**
+ * PostgreSQL-backed implementation of {@link IClientRepository}.
+ *
+ * A connected {@link pg.Pool} is injected; its lifecycle (and the schema, via the
+ * migration runner) is owned by the composition root. The UNIQUE (provider,
+ * provider_subject) constraint enforces one client per external identity at the
+ * database level, so a concurrent duplicate `create` rejects rather than racing.
+ */
+export class PgClientRepository implements IClientRepository {
+    public constructor(private readonly pool: pg.Pool) {}
+
+    public async findByProvider(
+        provider: string,
+        providerSubject: string,
+    ): Promise<ClientRecord | undefined> {
+        const result = await this.pool.query<ClientRow>(
+            'SELECT * FROM clients WHERE provider = $1 AND provider_subject = $2',
+            [provider, providerSubject],
+        );
+
+        const row = result.rows[0];
+        return row ? this.toDomain(row) : undefined;
+    }
+
+    public async findById(clientId: string): Promise<ClientRecord | undefined> {
+        const result = await this.pool.query<ClientRow>(
+            'SELECT * FROM clients WHERE client_id = $1',
+            [clientId],
+        );
+
+        const row = result.rows[0];
+        return row ? this.toDomain(row) : undefined;
+    }
+
+    public async create(client: NewClient): Promise<ClientRecord> {
+        const result = await this.pool.query<ClientRow>(
+            `INSERT INTO clients (client_id, provider, provider_subject, email)
+             VALUES ($1, $2, $3, $4)
+             RETURNING *`,
+            [client.clientId, client.provider, client.providerSubject, client.email ?? null],
+        );
+
+        return this.toDomain(result.rows[0]);
+    }
+
+    public async touchLastLogin(clientId: string): Promise<void> {
+        await this.pool.query('UPDATE clients SET last_login_at = now() WHERE client_id = $1', [
+            clientId,
+        ]);
+    }
+
+    private toDomain(row: ClientRow): ClientRecord {
+        return {
+            clientId: row.client_id,
+            provider: row.provider,
+            providerSubject: row.provider_subject,
+            email: row.email ?? undefined,
+            createdAt: row.created_at,
+            lastLoginAt: row.last_login_at ?? undefined,
+        };
+    }
+}

package/src/repository/types.ts

@@ -0,0 +1,50 @@
+/**
+ * A persisted client (account).
+ *
+ * `clientId` equals the token `sub` and is immutable for the life of the client
+ * (it is reused from the guest's id on promote-in-place). Identity is the pair
+ * `(provider, providerSubject)` — the provider's stable subject is matched
+ * directly; email is stored for display/contact only and is NEVER a matching key.
+ *
+ * Guests are NOT stored here — only clients that have logged in at least once.
+ */
+export interface ClientRecord {
+    clientId: string;
+    provider: string;
+    providerSubject: string;
+    email?: string;
+    createdAt: Date;
+    lastLoginAt?: Date;
+}
+
+/** Fields required to insert a new client. */
+export interface NewClient {
+    clientId: string;
+    provider: string;
+    providerSubject: string;
+    email?: string;
+}
+
+/**
+ * Persistence boundary for authenticated clients (accounts).
+ *
+ * Implementations may be Postgres ({@link PgClientRepository}) or in-memory
+ * ({@link InMemoryClientRepository}); the rest of the service depends only on
+ * this interface.
+ */
+export interface IClientRepository {
+    /** Find a client by its external identity. Returns undefined if none exists. */
+    findByProvider(provider: string, providerSubject: string): Promise<ClientRecord | undefined>;
+
+    /** Find a client by its immutable clientId. Returns undefined if none exists. */
+    findById(clientId: string): Promise<ClientRecord | undefined>;
+
+    /**
+     * Insert a new client. Rejects if `clientId` already exists or if
+     * `(provider, providerSubject)` is already mapped to another client.
+     */
+    create(client: NewClient): Promise<ClientRecord>;
+
+    /** Set last_login_at to now for the given client. No-op if the client is unknown. */
+    touchLastLogin(clientId: string): Promise<void>;
+}