@wopr-network/platform-core 0.1.0

package/dist/auth/auth.test.js

@@ -0,0 +1,140 @@
+import { Hono } from "hono";
+import { beforeEach, describe, expect, it } from "vitest";
+import { extractBearerToken, requireRole, timingSafeMapLookup } from "./index.js";
+// ---------------------------------------------------------------------------
+// extractBearerToken
+// ---------------------------------------------------------------------------
+describe("extractBearerToken", () => {
+    it("extracts token from valid Bearer header", () => {
+        expect(extractBearerToken("Bearer abc123")).toBe("abc123");
+    });
+    it("handles case-insensitive Bearer prefix", () => {
+        expect(extractBearerToken("bearer abc123")).toBe("abc123");
+        expect(extractBearerToken("BEARER abc123")).toBe("abc123");
+        expect(extractBearerToken("BeArEr abc123")).toBe("abc123");
+    });
+    it("returns null for undefined header", () => {
+        expect(extractBearerToken(undefined)).toBeNull();
+    });
+    it("returns null for empty string", () => {
+        expect(extractBearerToken("")).toBeNull();
+    });
+    it("returns null for non-Bearer scheme", () => {
+        expect(extractBearerToken("Basic abc123")).toBeNull();
+        expect(extractBearerToken("Digest abc123")).toBeNull();
+    });
+    it("returns null for Bearer with no token", () => {
+        expect(extractBearerToken("Bearer ")).toBeNull();
+        expect(extractBearerToken("Bearer")).toBeNull();
+    });
+    it("trims whitespace from header and token", () => {
+        expect(extractBearerToken("  Bearer   abc123  ")).toBe("abc123");
+    });
+    it("preserves token characters", () => {
+        const token = "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiMSJ9.sig";
+        expect(extractBearerToken(`Bearer ${token}`)).toBe(token);
+    });
+});
+// ---------------------------------------------------------------------------
+// requireRole middleware
+// ---------------------------------------------------------------------------
+describe("requireRole middleware", () => {
+    let app;
+    beforeEach(() => {
+        app = new Hono();
+        // Inject user directly for testing requireRole in isolation
+        app.use("/*", async (c, next) => {
+            const authHeader = c.req.header("X-Test-Roles");
+            if (authHeader !== undefined) {
+                const roles = authHeader ? authHeader.split(",").map((r) => r.trim()) : [];
+                const userId = c.req.header("X-Test-User-Id") ?? "test-user";
+                c.set("user", { id: userId, roles });
+                c.set("authMethod", "api_key");
+            }
+            return next();
+        });
+        app.get("/admin", requireRole("admin"), (c) => {
+            return c.json({ ok: true, user: c.get("user").id });
+        });
+        app.get("/editor", requireRole("editor"), (c) => {
+            return c.json({ ok: true });
+        });
+    });
+    it("allows user with required role", async () => {
+        const res = await app.request("/admin", {
+            headers: { "X-Test-User-Id": "admin-user", "X-Test-Roles": "admin,user" },
+        });
+        expect(res.status).toBe(200);
+        const body = await res.json();
+        expect(body.ok).toBe(true);
+        expect(body.user).toBe("admin-user");
+    });
+    it("rejects user without required role", async () => {
+        const res = await app.request("/admin", {
+            headers: { "X-Test-User-Id": "basic-user", "X-Test-Roles": "user" },
+        });
+        expect(res.status).toBe(403);
+        const body = await res.json();
+        expect(body.error).toBe("Insufficient permissions");
+        expect(body.required).toBe("admin");
+    });
+    it("rejects user with empty roles array", async () => {
+        const res = await app.request("/admin", {
+            headers: { "X-Test-User-Id": "no-roles", "X-Test-Roles": "" },
+        });
+        expect(res.status).toBe(403);
+    });
+    it("returns 401 when no auth (requireRole without user set)", async () => {
+        const noAuthApp = new Hono();
+        noAuthApp.get("/admin", requireRole("admin"), (c) => c.json({ ok: true }));
+        const res = await noAuthApp.request("/admin");
+        expect(res.status).toBe(401);
+        const body = await res.json();
+        expect(body.error).toBe("Authentication required");
+    });
+    it("works with multiple roles (only one required)", async () => {
+        const res = await app.request("/editor", {
+            headers: { "X-Test-Roles": "user,editor,admin" },
+        });
+        expect(res.status).toBe(200);
+    });
+    it("role check is case-sensitive", async () => {
+        const res = await app.request("/admin", {
+            headers: { "X-Test-Roles": "Admin" },
+        });
+        expect(res.status).toBe(403);
+    });
+});
+// ---------------------------------------------------------------------------
+// timingSafeMapLookup
+// ---------------------------------------------------------------------------
+describe("timingSafeMapLookup", () => {
+    it("returns the value for an exact match", () => {
+        const map = new Map([["secret-token", "admin"]]);
+        expect(timingSafeMapLookup(map, "secret-token")).toBe("admin");
+    });
+    it("returns undefined for a non-matching key", () => {
+        const map = new Map([["secret-token", "admin"]]);
+        expect(timingSafeMapLookup(map, "wrong-token")).toBeUndefined();
+    });
+    it("returns undefined for a key with different length", () => {
+        const map = new Map([["short", "val"]]);
+        expect(timingSafeMapLookup(map, "a-much-longer-key")).toBeUndefined();
+    });
+    it("returns undefined when map is empty", () => {
+        const map = new Map();
+        expect(timingSafeMapLookup(map, "any-token")).toBeUndefined();
+    });
+    it("matches the correct entry among multiple keys", () => {
+        const map = new Map([
+            ["token-aaa", "read"],
+            ["token-bbb", "write"],
+            ["token-ccc", "admin"],
+        ]);
+        expect(timingSafeMapLookup(map, "token-bbb")).toBe("write");
+    });
+    it("returns undefined for empty input string", () => {
+        const map = new Map([["secret", "val"]]);
+        expect(timingSafeMapLookup(map, "")).toBeUndefined();
+    });
+});

package/dist/auth/better-auth.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Better Auth — Platform auth source of truth.
+ *
+ * Provides email+password auth, session management, and cookie-based auth
+ * for the platform UI. Uses PostgreSQL via pg.Pool for persistence.
+ *
+ * The auth instance is lazily initialized to avoid opening the database
+ * at module import time (which breaks tests).
+ */
+import { betterAuth } from "better-auth";
+import type { Pool } from "pg";
+import type { PlatformDb } from "../db/index.js";
+import { PgEmailVerifier } from "../email/verification.js";
+/** Configuration for initializing Better Auth in platform-core. */
+export interface BetterAuthConfig {
+    pool: Pool;
+    db: PlatformDb;
+    /** Called after a new user signs up (e.g., create personal tenant). */
+    onUserCreated?: (userId: string, userName: string, email: string) => Promise<void>;
+}
+/** The type of a better-auth instance. */
+export type Auth = ReturnType<typeof betterAuth>;
+/** Initialize Better Auth with the given config. Must be called before getAuth(). */
+export declare function initBetterAuth(config: BetterAuthConfig): void;
+/**
+ * Run better-auth migrations against the auth database.
+ * Must be called after initBetterAuth().
+ */
+export declare function runAuthMigrations(): Promise<void>;
+/**
+ * Get or create the singleton better-auth instance.
+ * Lazily initialized on first call. initBetterAuth() must be called first.
+ */
+export declare function getAuth(): Auth;
+/** Get an IEmailVerifier backed by the auth database. */
+export declare function getEmailVerifier(): PgEmailVerifier;
+/** Replace the singleton auth instance (for testing). */
+export declare function setAuth(auth: Auth): void;
+/** Reset the singleton (for testing cleanup). */
+export declare function resetAuth(): void;
+/** Reset the user creator singleton (for testing). */
+export declare function resetUserCreator(): void;

package/dist/auth/better-auth.js

@@ -0,0 +1,196 @@
+/**
+ * Better Auth — Platform auth source of truth.
+ *
+ * Provides email+password auth, session management, and cookie-based auth
+ * for the platform UI. Uses PostgreSQL via pg.Pool for persistence.
+ *
+ * The auth instance is lazily initialized to avoid opening the database
+ * at module import time (which breaks tests).
+ */
+import { betterAuth } from "better-auth";
+import { twoFactor } from "better-auth/plugins";
+import { RoleStore } from "../admin/role-store.js";
+import { logger } from "../config/logger.js";
+import { initTwoFactorSchema } from "../db/auth-user-repository.js";
+import { getEmailClient } from "../email/client.js";
+import { passwordResetEmailTemplate, verifyEmailTemplate } from "../email/templates.js";
+import { generateVerificationToken, initVerificationSchema, PgEmailVerifier } from "../email/verification.js";
+import { createUserCreator } from "./user-creator.js";
+const BETTER_AUTH_SECRET = process.env.BETTER_AUTH_SECRET || "";
+const BETTER_AUTH_URL = process.env.BETTER_AUTH_URL || "http://localhost:3100";
+let _config = null;
+let _userCreator = null;
+let _userCreatorPromise = null;
+async function getUserCreator() {
+    if (_userCreator)
+        return _userCreator;
+    if (!_userCreatorPromise) {
+        if (!_config)
+            throw new Error("BetterAuth not initialized — call initBetterAuth() first");
+        _userCreatorPromise = createUserCreator(new RoleStore(_config.db)).then((creator) => {
+            _userCreator = creator;
+            return creator;
+        });
+    }
+    return _userCreatorPromise;
+}
+function authOptions(pool) {
+    return {
+        database: pool,
+        secret: BETTER_AUTH_SECRET,
+        baseURL: BETTER_AUTH_URL,
+        basePath: "/api/auth",
+        socialProviders: {
+            ...(process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET
+                ? { github: { clientId: process.env.GITHUB_CLIENT_ID, clientSecret: process.env.GITHUB_CLIENT_SECRET } }
+                : {}),
+            ...(process.env.DISCORD_CLIENT_ID && process.env.DISCORD_CLIENT_SECRET
+                ? { discord: { clientId: process.env.DISCORD_CLIENT_ID, clientSecret: process.env.DISCORD_CLIENT_SECRET } }
+                : {}),
+            ...(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET
+                ? { google: { clientId: process.env.GOOGLE_CLIENT_ID, clientSecret: process.env.GOOGLE_CLIENT_SECRET } }
+                : {}),
+        },
+        account: {
+            accountLinking: {
+                enabled: true,
+                trustedProviders: ["github", "google"],
+            },
+        },
+        emailAndPassword: {
+            enabled: true,
+            minPasswordLength: 12,
+            sendResetPassword: async ({ user, url }) => {
+                try {
+                    const emailClient = getEmailClient();
+                    const template = passwordResetEmailTemplate(url, user.email);
+                    await emailClient.send({
+                        to: user.email,
+                        ...template,
+                        userId: user.id,
+                        templateName: "password-reset",
+                    });
+                }
+                catch (error) {
+                    logger.error("Failed to send password reset email:", error);
+                }
+            },
+        },
+        databaseHooks: {
+            user: {
+                create: {
+                    after: async (user) => {
+                        try {
+                            const userCreator = await getUserCreator();
+                            await userCreator.createUser(user.id);
+                        }
+                        catch (error) {
+                            logger.error("Failed to run user creator:", error);
+                        }
+                        if (user.emailVerified)
+                            return;
+                        try {
+                            await initVerificationSchema(pool);
+                            const { token } = await generateVerificationToken(pool, user.id);
+                            const verifyUrl = `${BETTER_AUTH_URL}/auth/verify?token=${token}`;
+                            const emailClient = getEmailClient();
+                            const template = verifyEmailTemplate(verifyUrl, user.email);
+                            await emailClient.send({
+                                to: user.email,
+                                ...template,
+                                userId: user.id,
+                                templateName: "verify-email",
+                            });
+                        }
+                        catch (error) {
+                            logger.error("Failed to send verification email:", error);
+                        }
+                        // Delegate personal tenant creation to the consumer
+                        if (_config?.onUserCreated) {
+                            try {
+                                await _config.onUserCreated(user.id, user.name || user.email, user.email);
+                            }
+                            catch (error) {
+                                logger.error("Failed to run onUserCreated callback:", error);
+                            }
+                        }
+                    },
+                },
+            },
+        },
+        session: {
+            cookieCache: { enabled: true, maxAge: 5 * 60 },
+        },
+        advanced: {
+            cookiePrefix: "better-auth",
+            cookies: {
+                session_token: {
+                    attributes: {
+                        domain: process.env.COOKIE_DOMAIN || ".wopr.bot",
+                    },
+                },
+            },
+        },
+        plugins: [twoFactor()],
+        rateLimit: {
+            enabled: true,
+            window: 60,
+            max: 100,
+            customRules: {
+                "/sign-in/email": { window: 900, max: 5 },
+                "/sign-up/email": { window: 3600, max: 10 },
+                "/request-password-reset": { window: 3600, max: 3 },
+            },
+            storage: "memory",
+        },
+        trustedOrigins: (process.env.UI_ORIGIN || "http://localhost:3001").split(","),
+    };
+}
+/** Initialize Better Auth with the given config. Must be called before getAuth(). */
+export function initBetterAuth(config) {
+    _config = config;
+}
+/**
+ * Run better-auth migrations against the auth database.
+ * Must be called after initBetterAuth().
+ */
+export async function runAuthMigrations() {
+    if (!_config)
+        throw new Error("BetterAuth not initialized — call initBetterAuth() first");
+    const { getMigrations } = (await import("better-auth/db"));
+    const { runMigrations } = await getMigrations(authOptions(_config.pool));
+    await runMigrations();
+    await initTwoFactorSchema(_config.pool);
+}
+let _auth = null;
+/**
+ * Get or create the singleton better-auth instance.
+ * Lazily initialized on first call. initBetterAuth() must be called first.
+ */
+export function getAuth() {
+    if (!_auth) {
+        if (!_config)
+            throw new Error("BetterAuth not initialized — call initBetterAuth() first");
+        _auth = betterAuth(authOptions(_config.pool));
+    }
+    return _auth;
+}
+/** Get an IEmailVerifier backed by the auth database. */
+export function getEmailVerifier() {
+    if (!_config)
+        throw new Error("BetterAuth not initialized — call initBetterAuth() first");
+    return new PgEmailVerifier(_config.pool);
+}
+/** Replace the singleton auth instance (for testing). */
+export function setAuth(auth) {
+    _auth = auth;
+}
+/** Reset the singleton (for testing cleanup). */
+export function resetAuth() {
+    _auth = null;
+}
+/** Reset the user creator singleton (for testing). */
+export function resetUserCreator() {
+    _userCreator = null;
+    _userCreatorPromise = null;
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Auth — Session management, token verification, and middleware.
+ *
+ * Provides:
+ * - `requireRole` middleware for role-based access control
+ * - `scopedBearerAuth` middleware for operation-scoped API tokens
+ */
+import type { Context, Next } from "hono";
+import type { IOrgMemberRepository } from "../tenancy/org-member-repository.js";
+export interface AuthUser {
+    id: string;
+    roles: string[];
+}
+export interface AuthEnv {
+    Variables: {
+        user: AuthUser;
+        authMethod: "session" | "api_key";
+        tokenTenantId?: string;
+        isOperatorToken?: boolean;
+    };
+}
+/**
+ * Extract the bearer token from an Authorization header value.
+ * Returns `null` if the header is missing, empty, or not a Bearer scheme.
+ */
+export declare function extractBearerToken(header: string | undefined): string | null;
+/**
+ * Timing-safe lookup of a string key in a Map.
+ *
+ * Iterates all entries and compares each key using `crypto.timingSafeEqual`
+ * to prevent timing side-channel attacks. Returns the value of the first
+ * matching key, or `undefined` if no key matches.
+ */
+export declare function timingSafeMapLookup<V>(map: Map<string, V>, candidate: string): V | undefined;
+/**
+ * Create a `requireRole` middleware that rejects users without the specified role.
+ * Must be used after `requireAuth`.
+ */
+export declare function requireRole(role: string): (c: Context<AuthEnv>, next: Next) => Promise<void | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 401, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+    required: string;
+}, 403, "json">)>;
+/** Operation scopes ordered by privilege level. */
+export type TokenScope = "read" | "write" | "admin";
+/**
+ * Parse a token's scope from the `wopr_<scope>_<random>` format.
+ *
+ * - `wopr_read_abc123`  -> `"read"`
+ * - `wopr_write_abc123` -> `"write"`
+ * - `wopr_admin_abc123` -> `"admin"`
+ * - Any other format    -> `null` (not a scoped token)
+ */
+export declare function parseTokenScope(token: string): TokenScope | null;
+/**
+ * Check whether a token's scope satisfies the required minimum scope.
+ * admin >= write >= read.
+ */
+export declare function scopeSatisfies(tokenScope: TokenScope, requiredScope: TokenScope): boolean;
+export interface ScopedTokenConfig {
+    /**
+     * Map of token string -> its scope.
+     * Tokens can be in `wopr_<scope>_<random>` format (scope parsed automatically)
+     * or plain strings mapped explicitly.
+     */
+    tokens: Map<string, TokenScope>;
+}
+/** Token metadata including scope and tenant association. */
+export interface TokenMetadata {
+    scope: TokenScope;
+    tenantId?: string;
+}
+/**
+ * Build a token-to-scope map from environment variables.
+ *
+ * Accepts:
+ * - `FLEET_API_TOKEN` (legacy single token, treated as admin)
+ * - `FLEET_API_TOKEN_READ` (read-scoped token)
+ * - `FLEET_API_TOKEN_WRITE` (write-scoped token)
+ * - `FLEET_API_TOKEN_ADMIN` (admin-scoped token)
+ * - Any `wopr_<scope>_<random>` formatted token has its scope inferred.
+ */
+export declare function buildTokenMap(env?: Record<string, string | undefined>): Map<string, TokenScope>;
+/**
+ * Build a token-to-metadata map from environment variables.
+ *
+ * Accepts:
+ * - `FLEET_TOKEN_<TENANT>=<scope>:<token>` (tenant-scoped tokens)
+ * - Fallback to legacy token map for backwards compatibility (no tenant constraint)
+ *
+ * Example: `FLEET_TOKEN_ACME=write:wopr_write_abc123`
+ */
+export declare function buildTokenMetadataMap(env?: Record<string, string | undefined>): Map<string, TokenMetadata>;
+/**
+ * Create a scoped bearer auth middleware.
+ *
+ * Validates the bearer token against the token map and checks that the
+ * token's scope satisfies the required minimum scope for the route.
+ *
+ * @param tokenMap - Map of token -> scope (use `buildTokenMap()` to create)
+ * @param requiredScope - Minimum scope required for this route/group
+ */
+export declare function scopedBearerAuth(tokenMap: Map<string, TokenScope>, requiredScope: TokenScope): (c: Context, next: Next) => Promise<void | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 401, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+    required: TokenScope;
+    provided: TokenScope;
+}, 403, "json">)>;
+/**
+ * Create a tenant-aware scoped bearer auth middleware.
+ *
+ * Validates the bearer token against the metadata map, checks scope,
+ * and stores the token's associated tenantId for downstream ownership checks.
+ *
+ * @param metadataMap - Map of token -> metadata (use `buildTokenMetadataMap()` to create)
+ * @param requiredScope - Minimum scope required for this route/group
+ */
+export declare function scopedBearerAuthWithTenant(metadataMap: Map<string, TokenMetadata>, requiredScope: TokenScope): (c: Context<AuthEnv>, next: Next) => Promise<void | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 401, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+    required: TokenScope;
+    provided: TokenScope;
+}, 403, "json">)>;
+/**
+ * Middleware that resolves the current user from a better-auth session cookie.
+ *
+ * On success, sets:
+ * - `c.set("user", { id, roles })`
+ * - `c.set("authMethod", "session")`
+ *
+ * If no session cookie is present (or session is invalid), the request
+ * continues without a user — downstream middleware like `scopedBearerAuth`
+ * or `requireAuth` will handle enforcement.
+ *
+ * Uses lazy `getAuth()` to avoid initializing the DB at import time.
+ */
+export declare function resolveSessionUser(): (c: Context, next: Next) => Promise<void>;
+/**
+ * Middleware that requires either a valid session or a scoped API token.
+ *
+ * Tries session first, then falls back to scoped bearer auth.
+ * Returns 401 if neither is present.
+ */
+export declare function requireSessionOrToken(tokenMap: Map<string, TokenScope>, requiredScope: TokenScope): (c: Context, next: Next) => Promise<void | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 401, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+    required: TokenScope;
+    provided: TokenScope;
+}, 403, "json">)>;
+/**
+ * Middleware that enforces tenant ownership on tenant-scoped resources.
+ *
+ * Must be used after `scopedBearerAuthWithTenant` middleware.
+ * Compares the resource's tenantId against the token's tenantId.
+ * - If token has no tenantId (legacy/admin tokens), returns 403 Forbidden.
+ * - If resource tenantId matches token tenantId, passes through.
+ * - Otherwise, returns 403 Forbidden.
+ *
+ * @param _getResourceTenantId - Function that extracts tenantId from the resource (reserved for future use)
+ */
+export declare function requireTenantOwnership<T>(_getResourceTenantId: (resource: T) => string | undefined): (c: Context<AuthEnv>, next: Next) => Promise<void | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 403, "json">)>;
+/**
+ * Validate that a resource belongs to the authenticated tenant.
+ * Returns a response if validation fails (404 for not found or tenant mismatch).
+ *
+ * @param c - Hono context
+ * @param resource - The resource to check (null/undefined = not found)
+ * @param resourceTenantId - The resource's tenantId
+ * @returns Response if validation fails, undefined if validation passes
+ */
+export declare function validateTenantOwnership<T>(c: Context, resource: T | null | undefined, resourceTenantId: string | undefined): Response | undefined;
+/**
+ * Validate that a user has access to the requested tenant.
+ *
+ * - If requestedTenantId is falsy or matches userId, access is allowed (personal tenant).
+ * - Otherwise, checks org membership via IOrgMemberRepository.
+ *
+ * @returns true if the user has access, false otherwise.
+ */
+export declare function validateTenantAccess(userId: string, requestedTenantId: string | undefined, orgMemberRepo: IOrgMemberRepository): Promise<boolean>;