@graphoria/server 0.3.0 → 0.5.0

package/src/configuration/rest/handleRESTRequestFactory.ts

@@ -12,6 +12,7 @@ import type { HandleGraphQLRequest } from "../gql/handleGraphQLRequestFactory";
 import { analyzeQuery } from "../../analyzeQuery";
 import { checkUserCredentials } from "../../databases";
 import { proxyRemoteRESTRequest } from "../../remoteREST/proxy";
+import { actorFromSession, audit } from "../../logging/audit";
 import { getTokenService } from "../../singletons/authentication";
 import { getCache } from "../../singletons/cache";
 import { databasesConnections, repositoryMap } from "../../singletons/databases";
@@ -174,9 +175,23 @@ export const handleRESTRequestFactory = (
 
             const result = await checkUserCredentials(auth, username, password);
 
+            const actor = { type: "credentials", sub: username } as const;
             if (!result.valid) {
+              audit().emit({
+                action: "auth.login",
+                outcome: "failure",
+                actor,
+                target: { kind: "auth", via: "rest" },
+                reason: "Invalid username or password",
+              });
               return new S401({ errors: ["Invalid username or password"] });
             }
+            audit().emit({
+              action: "auth.login",
+              outcome: "success",
+              actor,
+              target: { kind: "auth", via: "rest", role: result.role },
+            });
 
             const data = await getTokenService().createTokenPair({
               sub: username,
@@ -229,9 +244,11 @@ export const handleRESTRequestFactory = (
 
           if (route.authOperation === "logout") {
             const tokenService = getTokenService();
+            const revoked: string[] = [];
 
             if (session?.jti) {
               await tokenService.revoke(session.jti);
+              revoked.push(session.jti);
             }
 
             const refreshCookie = req?.cookies?.get("refresh_token");
@@ -241,6 +258,7 @@ export const handleRESTRequestFactory = (
                   audience: "refresh",
                 });
                 await tokenService.revoke(refreshPayload.jti);
+                revoked.push(refreshPayload.jti);
               } catch {
                 // tampered or expired cookie — nothing to revoke
               }
@@ -250,6 +268,14 @@ export const handleRESTRequestFactory = (
               req.cookies.delete("refresh_token");
             }
 
+            if (revoked.length > 0) {
+              audit().emit({
+                action: "auth.logout",
+                actor: actorFromSession(session),
+                target: { kind: "auth", via: "rest", revoked },
+              });
+            }
+
             return new S200({ data: true });
           }
 

package/src/console/api.ts

@@ -1,3 +1,4 @@
+import type { ConsoleScope } from "./session";
 import type { TokenService } from "../authentication/types";
 import type { AnalyzedConfiguration } from "../configuration";
 import type { Configuration } from "../types/configuration";
@@ -8,11 +9,12 @@ import type { ConnectionPool } from "mssql";
 
 import { createConsoleSessions } from "./session";
 import { getTags } from "../configuration/rest/generateOpenAPI";
+import { audit } from "../logging/audit";
 import { getCronJobs } from "../singletons/cron";
-import { databasesConnections } from "../singletons/databases";
+import { databasesConnections, pingConnection } from "../singletons/databases";
 import { queueManager } from "../singletons/queues";
 import { resolveClientAddress } from "../utils/rateLimit";
-import { S200, S400, S401, S404, S429 } from "../utils/responses";
+import { S200, S400, S401, S403, S404, S429 } from "../utils/responses";
 
 type ConsoleRoutesFactoryOptions = {
   env: Env;
@@ -33,11 +35,6 @@ type ConsoleRouteHandler = (
 
 const PING_TIMEOUT_MS = 2000;
 
-const pingConnection = (connection: SQL | ConnectionPool, type: string) =>
-  type === "mssql"
-    ? (connection as ConnectionPool).query("SELECT 1")
-    : (connection as SQL).unsafe("SELECT 1");
-
 const measureLatency = async (connection: SQL | ConnectionPool, type: string) => {
   const start = performance.now();
   let timer: ReturnType<typeof setTimeout> | undefined;
@@ -67,12 +64,25 @@ export const consoleRoutesFactory = ({
 }: ConsoleRoutesFactoryOptions): Record<string, Record<string, ConsoleRouteHandler>> => {
   const sessions = createConsoleSessions({ env, consolePath, tokenService });
 
+  const clientAddress = (req: BunRequest, server?: Bun.Server<unknown>) =>
+    resolveClientAddress(req, server, env.rateLimit.trustProxy);
+
   const guarded =
-    (handler: (req: BunRequest) => object | Promise<object>): ConsoleRouteHandler =>
-    async (req: BunRequest) => {
+    (
+      handler: (
+        req: BunRequest,
+        server: Bun.Server<unknown> | undefined,
+        scope: ConsoleScope,
+      ) => object | Promise<object>,
+      required: ConsoleScope = "read",
+    ): ConsoleRouteHandler =>
+    async (req: BunRequest, server?: Bun.Server<unknown>) => {
       try {
-        if (!(await sessions.authorize(req))) return new S404({ error: "Not Found" });
-        return new S200(await handler(req));
+        const scope = await sessions.authorize(req);
+        if (!scope) return new S404({ error: "Not Found" });
+        if (required === "write" && scope !== "write")
+          return new S403({ errors: [{ message: "Console session is read-only" }] });
+        return new S200(await handler(req, server, scope));
       } catch (error) {
         return new S400({ errors: [{ message: (error as Error)?.message }] });
       }
@@ -99,15 +109,28 @@ export const consoleRoutesFactory = ({
         // Keyed by address against the anonymous ceiling: there is no session
         // yet, and the attempt is charged before the secret is compared, so a
         // guesser cannot spend attempts for free.
-        const limit = await rateLimiter?.check(
-          null,
-          resolveClientAddress(req, server, env.rateLimit.trustProxy),
-        );
+        const ip = clientAddress(req, server);
+        const limit = await rateLimiter?.check(null, ip);
         if (limit && !limit.allowed) return new S429(limit.retryAfterMs);
 
+        const actor = { type: "admin_secret", ip } as const;
         try {
-          return new S200(await sessions.login(req));
-        } catch {
+          const { expiresIn, scope, superset } = await sessions.login(req);
+          audit().emit({
+            action: "console.login",
+            outcome: "success",
+            actor: { ...actor, scope: superset ? "all" : `console:${scope}` },
+            target: { kind: "console" },
+          });
+          return new S200({ expiresIn, scope });
+        } catch (error) {
+          audit().emit({
+            action: "console.login",
+            outcome: "failure",
+            actor,
+            target: { kind: "console" },
+            reason: (error as Error)?.message,
+          });
           // One message for a bad secret and for a malformed body alike: the
           // caller learns nothing about which it was.
           return new S401({ errors: [{ message: "Invalid admin secret" }] });
@@ -117,8 +140,14 @@ export const consoleRoutesFactory = ({
 
     [`${base}/logout`]: {
       ...cors,
-      POST: async (req) => {
-        await sessions.logout(req);
+      POST: async (req, server) => {
+        if (await sessions.logout(req)) {
+          audit().emit({
+            action: "console.logout",
+            actor: { type: "console", ip: clientAddress(req, server) },
+            target: { kind: "console" },
+          });
+        }
         return new S200({ ok: true });
       },
     },
@@ -264,7 +293,7 @@ export const consoleRoutesFactory = ({
 
     [`${base}/config`]: {
       ...cors,
-      GET: guarded(() => ({
+      GET: guarded((_req, _server, scope) => ({
         name: projectConfiguration.name,
         version: projectConfiguration.version,
         prefixes,
@@ -274,12 +303,13 @@ export const consoleRoutesFactory = ({
           mcp: projectConfiguration.ai?.mcp?.enabled ?? false,
           cors: env.enableCors,
         },
+        session: { scope },
       })),
     },
 
     [`${base}/queues/publish`]: {
       ...cors,
-      POST: guarded(async (req) => {
+      POST: guarded(async (req, server) => {
         const { publisher, message, key } = (await req.json()) as {
           publisher?: string;
           message?: string | object;
@@ -288,13 +318,18 @@ export const consoleRoutesFactory = ({
         if (!publisher || message == null) throw new Error("publisher and message are required");
         if (!Object.hasOwn(queueManager?.publisherMap() ?? {}, publisher))
           throw new Error(`Unknown publisher "${publisher}"`);
+        audit().emit({
+          action: "console.queue.publish",
+          actor: { type: "console", ip: clientAddress(req, server) },
+          target: { kind: "publisher", name: publisher, key },
+        });
         return { ok: await queueManager!.sendMessage(publisher, message, key) };
-      }),
+      }, "write"),
     },
 
     [`${base}/cron`]: {
       ...cors,
-      POST: guarded(async (req) => {
+      POST: guarded(async (req, server) => {
         const { name, action } = (await req.json()) as { name?: string; action?: string };
         const cron = getCronJobs();
         if (!cron) throw new Error("Cron is not enabled");
@@ -302,10 +337,15 @@ export const consoleRoutesFactory = ({
         if (action !== "trigger" && action !== "pause" && action !== "resume")
           throw new Error(`Unknown action "${action}"`);
         if (!cron.getJob(name)) throw new Error(`Unknown job "${name}"`);
+        audit().emit({
+          action: `console.cron.${action}`,
+          actor: { type: "console", ip: clientAddress(req, server) },
+          target: { kind: "cron", name },
+        });
         if (action === "trigger") await cron.trigger(name);
         else cron[action](name);
         return { ok: true };
-      }),
+      }, "write"),
     },
   };
 };

package/src/console/session.ts

@@ -1,9 +1,8 @@
-import { timingSafeEqual } from "crypto";
-
 import type { BunRequest } from "bun";
 import type { TokenService } from "../authentication/types";
 import type { Env } from "../types/env";
 
+import { createCapabilityAuthorizer } from "../authentication/capabilities";
 import { parseDurationToMs, parseDurationToSeconds } from "../authentication/duration";
 import { logger } from "../logging";
 
@@ -14,23 +13,21 @@ export const CONSOLE_SESSION_COOKIE = "graphoria_console_session";
 const CONSOLE_AUDIENCE = "console";
 const CONSOLE_SUBJECT = "console";
 
-const safeCompare = (a: string, b: string): boolean => {
-  try {
-    const bufA = Buffer.from(a);
-    const bufB = Buffer.from(b);
-    if (bufA.length !== bufB.length) return false;
-    return timingSafeEqual(bufA, bufB);
-  } catch {
-    return false;
-  }
-};
+/** `read` sees state; `write` may also publish to queues and control cron. */
+export type ConsoleScope = "read" | "write";
+
+const isScope = (value: unknown): value is ConsoleScope => value === "read" || value === "write";
 
 export type ConsoleSessions = {
-  /** Exchange the admin secret for a session cookie. Throws if it does not match. */
-  login(req: BunRequest): Promise<{ expiresIn: number }>;
-  /** True when the request carries a live, unrevoked console session cookie. */
-  authorize(req: BunRequest): Promise<boolean>;
-  logout(req: BunRequest): Promise<void>;
+  /**
+   * Exchange a secret for a session cookie. Throws if none matches. `superset`
+   * is true when it was the admin secret rather than a console credential.
+   */
+  login(req: BunRequest): Promise<{ expiresIn: number; scope: ConsoleScope; superset: boolean }>;
+  /** The scope of a live, unrevoked console session cookie; null when there is none. */
+  authorize(req: BunRequest): Promise<ConsoleScope | null>;
+  /** Resolves true when a live session was revoked; the cookie is cleared either way. */
+  logout(req: BunRequest): Promise<boolean>;
 };
 
 type ConsoleSessionsOptions = {
@@ -45,6 +42,7 @@ export const createConsoleSessions = ({
   tokenService,
 }: ConsoleSessionsOptions): ConsoleSessions => {
   const log = logger("console");
+  const authorizeCapability = createCapabilityAuthorizer(env);
   const expiresIn = env.console.sessionExpiresIn;
   const sessionMs = parseDurationToMs(expiresIn);
 
@@ -73,7 +71,9 @@ export const createConsoleSessions = ({
     try {
       const payload = await tokenService.verifyToken(cookie, { audience: CONSOLE_AUDIENCE });
       if (payload.role !== env.superadmin.role) return null;
-      return payload;
+      const scope = payload.claims?.scope;
+      if (!isScope(scope)) return null;
+      return { ...payload, scope };
     } catch {
       return null;
     }
@@ -83,12 +83,14 @@ export const createConsoleSessions = ({
     login: async (req) => {
       const { secret: submitted } = (await req.json()) as { secret?: string };
 
-      if (!env.admin.secret || !submitted || !safeCompare(submitted, env.admin.secret)) {
-        throw new Error("Invalid admin secret");
-      }
+      const candidate = submitted ?? null;
+      const write = authorizeCapability(candidate, "console:write");
+      const grant = write ?? authorizeCapability(candidate, "console:read");
+      if (!grant) throw new Error("Invalid admin secret");
+      const scope: ConsoleScope = write ? "write" : "read";
 
       const token = await tokenService.createToken(
-        { sub: CONSOLE_SUBJECT, role: env.superadmin.role },
+        { sub: CONSOLE_SUBJECT, role: env.superadmin.role, claims: { scope } },
         { audience: CONSOLE_AUDIENCE, expiresIn },
       );
 
@@ -97,17 +99,17 @@ export const createConsoleSessions = ({
         maxAge: parseDurationToSeconds(expiresIn),
       });
 
-      log.info("console session issued");
+      log.info({ scope }, "console session issued");
 
-      return { expiresIn: parseDurationToSeconds(expiresIn) };
+      return { expiresIn: parseDurationToSeconds(expiresIn), scope, superset: grant.superset };
     },
 
     authorize: async (req) => {
       const payload = await readSession(req);
-      if (!payload) return false;
+      if (!payload) return null;
 
       prune();
-      return !revoked.has(payload.jti);
+      return revoked.has(payload.jti) ? null : payload.scope;
     },
 
     logout: async (req) => {
@@ -120,6 +122,8 @@ export const createConsoleSessions = ({
       }
 
       req.cookies.delete({ name: CONSOLE_SESSION_COOKIE, path: consolePath });
+
+      return payload !== null;
     },
   };
 };

package/src/cron/index.ts

@@ -7,6 +7,8 @@ import type { TickContext } from "../types/zod/cron";
 import { databasesConnections, repositoryMap } from "../singletons/databases";
 import { queueManager } from "../singletons/queues";
 import { logger } from "../logging";
+import { incMetric, observeMetric } from "../observability/metrics";
+import { startSpan, withActiveSpan } from "../observability/tracing";
 
 /**
  * Interface for a scheduled cron job instance
@@ -58,42 +60,63 @@ const createScheduledJob = (config: CronJob, gqlQuery: GqlQueryFn<true>): Schedu
       context: config.context,
     },
     async (self) => {
-      try {
-        log.info("executing");
-
-        executionCount++;
-
-        // Execute query if provided
-        const response = config.query
-          ? await gqlQuery(config.query, config.variables ?? {})
-          : undefined;
-
-        const tickContext: TickContext = {
-          name: config.name,
-          pattern: config.pattern,
-          variables: config.variables || {},
-          executionCount,
-          nextRun: self.nextRun(),
-          previousRun: self.previousRun(),
-        };
-
-        // Call the onTick callback if provided, passing options object
-        await config.onTick?.(
-          {
-            gqlQuery,
-            databases: databasesConnections,
-            queues: queueManager,
-            repository: repositoryMap,
-          },
-          tickContext,
-          response,
-        );
-
-        log.info({ executionCount, nextRun: self.nextRun() }, "completed");
-      } catch (error) {
-        log.error({ err: error }, "failed");
-        throw error;
-      }
+      const startTime = Bun.nanoseconds();
+      let outcome: "success" | "error" = "success";
+      // A tick is not inside a request, so it roots its own trace. The span is
+      // entered so anything `onTick` runs through `gqlQuery` lands under it.
+      const span = startSpan("cron.tick", {
+        parent: null,
+        attributes: { "graphoria.cron.job": config.name },
+      });
+
+      return withActiveSpan(span, async () => {
+        try {
+          log.info("executing");
+
+          executionCount++;
+
+          // Execute query if provided
+          const response = config.query
+            ? await gqlQuery(config.query, config.variables ?? {})
+            : undefined;
+
+          const tickContext: TickContext = {
+            name: config.name,
+            pattern: config.pattern,
+            variables: config.variables || {},
+            executionCount,
+            nextRun: self.nextRun(),
+            previousRun: self.previousRun(),
+          };
+
+          // Call the onTick callback if provided, passing options object
+          await config.onTick?.(
+            {
+              gqlQuery,
+              databases: databasesConnections,
+              queues: queueManager,
+              repository: repositoryMap,
+            },
+            tickContext,
+            response,
+          );
+
+          log.info({ executionCount, nextRun: self.nextRun() }, "completed");
+        } catch (error) {
+          outcome = "error";
+          log.error({ err: error }, "failed");
+          span?.recordError(error);
+          throw error;
+        } finally {
+          incMetric("graphoria_cron_runs_total", { job: config.name, outcome });
+          observeMetric(
+            "graphoria_cron_run_duration_seconds",
+            { job: config.name },
+            (Bun.nanoseconds() - startTime) / 1e9,
+          );
+          span?.end();
+        }
+      });
     },
   );