chapterhouse 0.1.1

package/dist/api/auth.js

@@ -0,0 +1,159 @@
+import jwt from "jsonwebtoken";
+import jwksClient from "jwks-rsa";
+function getIssuer(tenantId) {
+    return `https://login.microsoftonline.com/${tenantId}/v2.0`;
+}
+function getJwksUri(tenantId) {
+    return `https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`;
+}
+function getBearerToken(req) {
+    const headerAuth = req.headers.authorization;
+    if (typeof headerAuth === "string" && headerAuth.startsWith("Bearer ")) {
+        const token = headerAuth.slice("Bearer ".length).trim();
+        return token.length > 0 ? token : null;
+    }
+    return null;
+}
+function hasRequiredRole(claims, requiredRole) {
+    if (!requiredRole) {
+        return true;
+    }
+    return Array.isArray(claims.roles) && claims.roles.includes(requiredRole);
+}
+function buildAuthenticatedUser(claims, teamLeadId) {
+    const id = claims.oid || claims.sub;
+    const name = claims.name;
+    const email = claims.preferred_username || claims.email || claims.upn;
+    if (!id || !name || !email) {
+        return null;
+    }
+    return {
+        id,
+        name,
+        email,
+        role: teamLeadId && id === teamLeadId ? "team-lead" : "engineer",
+    };
+}
+function unauthorized(res, message) {
+    res.status(401).json({ error: message });
+}
+// Module-level cache of JWKS clients keyed by tenant ID.
+// Creating a new client per request discards the in-process key cache; keeping
+// one client per tenant lets jwks-rsa honour its cacheMaxAge and avoids an
+// outbound HTTPS call on every token verification.
+const jwksClientByTenant = new Map();
+function getJwksClientForTenant(tenantId) {
+    const existing = jwksClientByTenant.get(tenantId);
+    if (existing)
+        return existing;
+    const client = jwksClient({
+        jwksUri: getJwksUri(tenantId),
+        cache: true,
+        cacheMaxEntries: 5,
+        cacheMaxAge: 10 * 60 * 1000,
+    });
+    jwksClientByTenant.set(tenantId, client);
+    return client;
+}
+/** Exposed for test isolation — clears the module-level JWKS client cache. */
+export function _resetJwksClientCache() {
+    jwksClientByTenant.clear();
+}
+export async function verifyEntraBearerToken(token, config) {
+    if (!config.entraTenantId || !config.entraClientId) {
+        throw new Error("Entra auth is enabled but ENTRA_TENANT_ID or ENTRA_CLIENT_ID is missing");
+    }
+    const client = getJwksClientForTenant(config.entraTenantId);
+    const getKey = (header, callback) => {
+        if (!header.kid) {
+            callback(new Error("JWT is missing a key id"));
+            return;
+        }
+        client.getSigningKey(header.kid)
+            .then((key) => {
+            callback(null, key.getPublicKey());
+        })
+            .catch((err) => {
+            callback(err instanceof Error ? err : new Error(String(err)));
+        });
+    };
+    return await new Promise((resolve, reject) => {
+        jwt.verify(token, getKey, {
+            algorithms: ["RS256"],
+            audience: config.entraClientId,
+            issuer: getIssuer(config.entraTenantId),
+        }, (err, decoded) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            if (!decoded || typeof decoded === "string") {
+                reject(new Error("JWT payload is missing"));
+                return;
+            }
+            resolve(decoded);
+        });
+    });
+}
+export function getBootstrapAuthResponse(apiToken, config) {
+    if (config.standaloneMode) {
+        return { authMode: "standalone" };
+    }
+    if (config.entraAuthEnabled) {
+        return { authMode: "entra" };
+    }
+    return { authMode: "legacy", token: apiToken };
+}
+export function createAuthMiddleware(options) {
+    const verifyBearerToken = options.verifyBearerToken ?? verifyEntraBearerToken;
+    return async function authMiddleware(req, res, next) {
+        if (options.config.standaloneMode) {
+            next();
+            return;
+        }
+        const protectedPath = req.path === "/stream" || req.path.startsWith("/api/");
+        if (!protectedPath) {
+            next();
+            return;
+        }
+        if (req.path === "/api/bootstrap" || req.path === "/api/config/public" || req.path === "/status") {
+            next();
+            return;
+        }
+        if (!options.config.entraAuthEnabled) {
+            const token = getBearerToken(req);
+            if (!options.apiToken || token !== options.apiToken) {
+                unauthorized(res, "Unauthorized");
+                return;
+            }
+            next();
+            return;
+        }
+        const token = getBearerToken(req);
+        if (!token) {
+            unauthorized(res, "Unauthorized: missing Bearer token");
+            return;
+        }
+        try {
+            const claims = await verifyBearerToken(token, options.config);
+            if (options.config.entraRequiredRole && !hasRequiredRole(claims, options.config.entraRequiredRole)) {
+                console.warn(`[auth] Token for ${claims.preferred_username || claims.oid} rejected: ` +
+                    `required role "${options.config.entraRequiredRole}" not found in roles=${JSON.stringify(claims.roles ?? [])}`);
+                unauthorized(res, "Unauthorized: user does not have the required app role");
+                return;
+            }
+            const user = buildAuthenticatedUser(claims, options.config.entraTeamLeadId);
+            if (!user) {
+                unauthorized(res, "Unauthorized: token is missing required user claims");
+                return;
+            }
+            req.user = user;
+            next();
+        }
+        catch (err) {
+            console.error("[auth] JWT verification failed:", err);
+            unauthorized(res, "Unauthorized: invalid or expired token");
+        }
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/api/auth.test.js

@@ -0,0 +1,463 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+function createMockResponse() {
+    return {
+        statusCode: 200,
+        body: undefined,
+        status(code) {
+            this.statusCode = code;
+            return this;
+        },
+        json(payload) {
+            this.body = payload;
+            return this;
+        },
+    };
+}
+async function loadAuthModule() {
+    try {
+        return await import("./auth.js");
+    }
+    catch {
+        return null;
+    }
+}
+test("falls back to the legacy API token when Entra auth is disabled", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth.createAuthMiddleware, "function", "createAuthMiddleware should be exported");
+    const middleware = auth.createAuthMiddleware({
+        apiToken: "legacy-token",
+        config: {
+            entraAuthEnabled: false,
+            standaloneMode: false,
+            entraClientId: "",
+            entraTenantId: "",
+            entraRequiredRole: "",
+            entraTeamLeadId: "",
+        },
+    });
+    const req = {
+        path: "/api/model",
+        headers: { authorization: "Bearer legacy-token" },
+        query: {},
+        socket: { remoteAddress: "127.0.0.1" },
+    };
+    const res = createMockResponse();
+    let nextCalled = false;
+    await middleware(req, res, () => {
+        nextCalled = true;
+    });
+    assert.equal(nextCalled, true);
+    assert.equal(res.statusCode, 200);
+    assert.equal(req.user, undefined);
+});
+test("allows requests when standalone mode is enabled", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth.createAuthMiddleware, "function", "createAuthMiddleware should be exported");
+    const middleware = auth.createAuthMiddleware({
+        apiToken: null,
+        config: {
+            entraAuthEnabled: false,
+            standaloneMode: true,
+            entraClientId: "",
+            entraTenantId: "",
+            entraRequiredRole: "",
+            entraTeamLeadId: "",
+        },
+    });
+    const req = {
+        path: "/api/model",
+        headers: {},
+        query: {},
+        socket: { remoteAddress: "127.0.0.1" },
+    };
+    const res = createMockResponse();
+    let nextCalled = false;
+    await middleware(req, res, () => {
+        nextCalled = true;
+    });
+    assert.equal(nextCalled, true);
+    assert.equal(res.statusCode, 200);
+});
+test("authenticates /stream with the Authorization header in legacy mode", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth.createAuthMiddleware, "function", "createAuthMiddleware should be exported");
+    const middleware = auth.createAuthMiddleware({
+        apiToken: "legacy-token",
+        config: {
+            entraAuthEnabled: false,
+            standaloneMode: false,
+            entraClientId: "",
+            entraTenantId: "",
+            entraRequiredRole: "",
+            entraTeamLeadId: "",
+        },
+    });
+    const req = {
+        path: "/stream",
+        headers: { authorization: "Bearer legacy-token" },
+        query: {},
+        socket: { remoteAddress: "127.0.0.1" },
+    };
+    const res = createMockResponse();
+    let nextCalled = false;
+    await middleware(req, res, () => {
+        nextCalled = true;
+    });
+    assert.equal(nextCalled, true);
+    assert.equal(res.statusCode, 200);
+});
+test("rejects legacy /stream query-string tokens", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth.createAuthMiddleware, "function", "createAuthMiddleware should be exported");
+    const middleware = auth.createAuthMiddleware({
+        apiToken: "legacy-token",
+        config: {
+            entraAuthEnabled: false,
+            standaloneMode: false,
+            entraClientId: "",
+            entraTenantId: "",
+            entraRequiredRole: "",
+            entraTeamLeadId: "",
+        },
+    });
+    const req = {
+        path: "/stream",
+        headers: {},
+        query: { token: "legacy-token" },
+        socket: { remoteAddress: "127.0.0.1" },
+    };
+    const res = createMockResponse();
+    let nextCalled = false;
+    await middleware(req, res, () => {
+        nextCalled = true;
+    });
+    assert.equal(nextCalled, false);
+    assert.equal(res.statusCode, 401);
+    assert.deepEqual(res.body, { error: "Unauthorized" });
+});
+test("allows unauthenticated access to the public config endpoint", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth.createAuthMiddleware, "function", "createAuthMiddleware should be exported");
+    const middleware = auth.createAuthMiddleware({
+        apiToken: "legacy-token",
+        config: {
+            entraAuthEnabled: true,
+            standaloneMode: false,
+            entraClientId: "client-id",
+            entraTenantId: "tenant-id",
+            entraRequiredRole: "team.member",
+            entraTeamLeadId: "lead-user-id",
+        },
+    });
+    const req = {
+        path: "/api/config/public",
+        headers: {},
+        query: {},
+        socket: { remoteAddress: "127.0.0.1" },
+    };
+    const res = createMockResponse();
+    let nextCalled = false;
+    await middleware(req, res, () => {
+        nextCalled = true;
+    });
+    assert.equal(nextCalled, true);
+    assert.equal(res.statusCode, 200);
+});
+test("attaches the Entra user when bearer-token validation succeeds", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth.createAuthMiddleware, "function", "createAuthMiddleware should be exported");
+    const middleware = auth.createAuthMiddleware({
+        apiToken: "legacy-token",
+        config: {
+            entraAuthEnabled: true,
+            standaloneMode: false,
+            entraClientId: "client-id",
+            entraTenantId: "tenant-id",
+            entraRequiredRole: "team.member",
+            entraTeamLeadId: "lead-user-id",
+        },
+        verifyBearerToken: async (token) => {
+            assert.equal(token, "entra-token");
+            return {
+                sub: "lead-user-id",
+                oid: "lead-user-id",
+                name: "Brian Ketelsen",
+                preferred_username: "brian@example.com",
+                aud: "client-id",
+                iss: "https://login.microsoftonline.com/tenant-id/v2.0",
+                roles: ["team.member"],
+            };
+        },
+    });
+    const req = {
+        path: "/api/message",
+        headers: { authorization: "Bearer entra-token" },
+        query: {},
+        socket: { remoteAddress: "127.0.0.1" },
+    };
+    const res = createMockResponse();
+    let nextCalled = false;
+    await middleware(req, res, () => {
+        nextCalled = true;
+    });
+    assert.equal(nextCalled, true);
+    assert.deepEqual(req.user, {
+        id: "lead-user-id",
+        name: "Brian Ketelsen",
+        email: "brian@example.com",
+        role: "team-lead",
+    });
+});
+test("rejects Entra tokens that do not satisfy the configured group restriction", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth.createAuthMiddleware, "function", "createAuthMiddleware should be exported");
+    const middleware = auth.createAuthMiddleware({
+        apiToken: "legacy-token",
+        config: {
+            entraAuthEnabled: true,
+            standaloneMode: false,
+            entraClientId: "client-id",
+            entraTenantId: "tenant-id",
+            entraRequiredRole: "team.member",
+            entraTeamLeadId: "",
+        },
+        verifyBearerToken: async () => ({
+            sub: "engineer-user-id",
+            oid: "engineer-user-id",
+            name: "Ada Lovelace",
+            preferred_username: "ada@example.com",
+            aud: "client-id",
+            iss: "https://login.microsoftonline.com/tenant-id/v2.0",
+            roles: ["other.role"],
+        }),
+    });
+    const req = {
+        path: "/api/wiki/pages",
+        headers: { authorization: "Bearer entra-token" },
+        query: {},
+        socket: { remoteAddress: "127.0.0.1" },
+    };
+    const res = createMockResponse();
+    let nextCalled = false;
+    await middleware(req, res, () => {
+        nextCalled = true;
+    });
+    assert.equal(nextCalled, false);
+    assert.equal(res.statusCode, 401);
+    assert.deepEqual(res.body, { error: "Unauthorized: user does not have the required app role" });
+});
+test("rejects Entra requests that do not include a bearer token", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth.createAuthMiddleware, "function", "createAuthMiddleware should be exported");
+    const middleware = auth.createAuthMiddleware({
+        apiToken: "legacy-token",
+        config: {
+            entraAuthEnabled: true,
+            standaloneMode: false,
+            entraClientId: "client-id",
+            entraTenantId: "tenant-id",
+            entraRequiredRole: "team.member",
+            entraTeamLeadId: "lead-user-id",
+        },
+    });
+    const req = {
+        path: "/stream",
+        headers: {},
+        query: {},
+        socket: { remoteAddress: "127.0.0.1" },
+    };
+    const res = createMockResponse();
+    let nextCalled = false;
+    await middleware(req, res, () => {
+        nextCalled = true;
+    });
+    assert.equal(nextCalled, false);
+    assert.equal(res.statusCode, 401);
+    assert.deepEqual(res.body, { error: "Unauthorized: missing Bearer token" });
+});
+test("rejects Entra tokens that are missing required user claims", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth.createAuthMiddleware, "function", "createAuthMiddleware should be exported");
+    const middleware = auth.createAuthMiddleware({
+        apiToken: "legacy-token",
+        config: {
+            entraAuthEnabled: true,
+            standaloneMode: false,
+            entraClientId: "client-id",
+            entraTenantId: "tenant-id",
+            entraRequiredRole: "",
+            entraTeamLeadId: "lead-user-id",
+        },
+        verifyBearerToken: async () => ({
+            sub: "engineer-user-id",
+            oid: "engineer-user-id",
+            roles: ["team.member"],
+        }),
+    });
+    const req = {
+        path: "/api/message",
+        headers: { authorization: "Bearer entra-token" },
+        query: {},
+        socket: { remoteAddress: "127.0.0.1" },
+    };
+    const res = createMockResponse();
+    let nextCalled = false;
+    await middleware(req, res, () => {
+        nextCalled = true;
+    });
+    assert.equal(nextCalled, false);
+    assert.equal(res.statusCode, 401);
+    assert.deepEqual(res.body, { error: "Unauthorized: token is missing required user claims" });
+});
+test("returns a generic message when JWT verification fails", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth.createAuthMiddleware, "function", "createAuthMiddleware should be exported");
+    const originalConsoleError = console.error;
+    const logged = [];
+    console.error = (...args) => {
+        logged.push(args);
+    };
+    try {
+        const middleware = auth.createAuthMiddleware({
+            apiToken: "legacy-token",
+            config: {
+                entraAuthEnabled: true,
+                standaloneMode: false,
+                entraClientId: "client-id",
+                entraTenantId: "tenant-id",
+                entraRequiredRole: "",
+                entraTeamLeadId: "",
+            },
+            verifyBearerToken: async () => {
+                throw new Error("jwt malformed");
+            },
+        });
+        const req = {
+            path: "/api/message",
+            headers: { authorization: "Bearer bad-token" },
+            query: {},
+            socket: { remoteAddress: "127.0.0.1" },
+        };
+        const res = createMockResponse();
+        let nextCalled = false;
+        await middleware(req, res, () => {
+            nextCalled = true;
+        });
+        assert.equal(nextCalled, false);
+        assert.equal(res.statusCode, 401);
+        assert.deepEqual(res.body, { error: "Unauthorized: invalid or expired token" });
+        assert.equal(logged.length, 1);
+        assert.equal(logged[0]?.[0], "[auth] JWT verification failed:");
+    }
+    finally {
+        console.error = originalConsoleError;
+    }
+});
+// ---------------------------------------------------------------------------
+// Auth edge cases: JWKS cache + Entra error paths
+// ---------------------------------------------------------------------------
+test("missing Entra tenantId throws a clear descriptive error, not a crash", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    await assert.rejects(() => auth.verifyEntraBearerToken("any.jwt.token", {
+        entraAuthEnabled: true,
+        standaloneMode: false,
+        entraTenantId: "",
+        entraClientId: "some-client-id",
+        entraRequiredRole: "",
+        entraTeamLeadId: "",
+    }), (err) => {
+        assert.ok(err instanceof Error, "should throw an Error instance");
+        assert.match(err.message, /ENTRA_TENANT_ID or ENTRA_CLIENT_ID is missing/, "error message must identify the missing config");
+        return true;
+    });
+});
+test("missing Entra clientId throws a clear descriptive error, not a crash", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    await assert.rejects(() => auth.verifyEntraBearerToken("any.jwt.token", {
+        entraAuthEnabled: true,
+        standaloneMode: false,
+        entraTenantId: "some-tenant-id",
+        entraClientId: "",
+        entraRequiredRole: "",
+        entraTeamLeadId: "",
+    }), (err) => {
+        assert.ok(err instanceof Error, "should throw an Error instance");
+        assert.match(err.message, /ENTRA_TENANT_ID or ENTRA_CLIENT_ID is missing/, "error message must identify the missing config");
+        return true;
+    });
+});
+test("JWT missing kid header returns 401, not 500", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    const middleware = auth.createAuthMiddleware({
+        apiToken: null,
+        config: {
+            entraAuthEnabled: true,
+            standaloneMode: false,
+            entraClientId: "client-id",
+            entraTenantId: "tenant-id",
+            entraRequiredRole: "",
+            entraTeamLeadId: "",
+        },
+        verifyBearerToken: async () => {
+            const err = new Error("JWT is missing a key id");
+            err.name = "JsonWebTokenError";
+            throw err;
+        },
+    });
+    const req = {
+        path: "/api/message",
+        headers: { authorization: "Bearer token.without.kid" },
+        query: {},
+        socket: { remoteAddress: "127.0.0.1" },
+    };
+    const res = {
+        statusCode: 200,
+        body: undefined,
+        status(code) { this.statusCode = code; return this; },
+        json(payload) { this.body = payload; return this; },
+    };
+    let nextCalled = false;
+    await middleware(req, res, () => { nextCalled = true; });
+    assert.equal(nextCalled, false, "next() must not be called when kid is missing");
+    assert.equal(res.statusCode, 401, "status must be 401, not 500");
+    assert.deepEqual(res.body, { error: "Unauthorized: invalid or expired token" }, "response must not expose internal error details");
+});
+test("JWKS client is reused across calls for the same tenant (module-level cache)", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth._resetJwksClientCache, "function", "_resetJwksClientCache must be exported for test isolation");
+    auth._resetJwksClientCache();
+    const cfg = {
+        entraAuthEnabled: true,
+        standaloneMode: false,
+        entraTenantId: "test-tenant-for-cache",
+        entraClientId: "test-client",
+        entraRequiredRole: "",
+        entraTeamLeadId: "",
+    };
+    // Both calls will fail on a malformed JWT but neither should hit the
+    // "missing config" guard — which proves the JWKS client was constructed
+    // and reused rather than rebuilt on every invocation.
+    const err1 = await auth.verifyEntraBearerToken("not.a.real.jwt", cfg).catch((e) => e);
+    const err2 = await auth.verifyEntraBearerToken("not.a.real.jwt", cfg).catch((e) => e);
+    assert.ok(err1 instanceof Error, "first call must reject");
+    assert.ok(err2 instanceof Error, "second call must reject");
+    assert.doesNotMatch(String(err1.message), /ENTRA_TENANT_ID or ENTRA_CLIENT_ID is missing/, "first error must come from JWT processing, not config guard");
+    assert.doesNotMatch(String(err2.message), /ENTRA_TENANT_ID or ENTRA_CLIENT_ID is missing/, "second error must come from JWT processing — client reused from module cache");
+    auth._resetJwksClientCache();
+});
+//# sourceMappingURL=auth.test.js.map