@graphoria/server 0.3.0 → 0.4.0

package/src/index.ts

@@ -4,8 +4,10 @@ import { serve } from "bun";
 import { isString } from "es-toolkit";
 
 import type { BunRequest } from "bun";
+import type { Capability } from "./authentication/capabilities";
 import type { Configuration } from "./types/configuration";
 import type { Env } from "./types/env";
+import type { SessionContext } from "./utils/sessionVariables";
 
 import { createTokenService } from "./authentication";
 import { analyzeConfiguration, loadConfiguration } from "./configuration";
@@ -14,6 +16,7 @@ import { websocketHandlerFactory } from "./configuration/gql/handleGraphQLSubscr
 import { consoleRoutesFactory } from "./console/api";
 import { createAuthTables, verifyAuthTablesExist } from "./databases";
 import { createMCPRoutes } from "./ai";
+import { createCapabilityAuthorizer } from "./authentication/capabilities";
 import { getAgent, instantiateAI } from "./singletons/ai";
 import { getTokenService, setTokenService } from "./singletons/authentication";
 import { instantiateCronJobs } from "./singletons/cron";
@@ -32,6 +35,7 @@ import {
 import { S200, S400, S401, S404, S429 } from "./utils/responses";
 import { writeSchema } from "./utils/writeSchema";
 import { logger, configureLogging } from "./logging";
+import { actorFromSession, audit } from "./logging/audit";
 
 // Re-export for consumers
 export { configureLogging };
@@ -244,24 +248,52 @@ const createGraphQLServer = async (env: Env) => {
         : createMemoryRateLimitStore(),
   });
 
-  // Helper to get role-based handlers
-  const getRoleHandlers = async (req: Request, server?: Bun.Server<unknown>) => {
-    const session = await getTokenService().verifyTokenAndGetSession(
-      req.headers.get(env.authorizationHeader),
-      req.headers.get(env.admin.header),
-    );
+  const authorizeCapability = createCapabilityAuthorizer(env);
+
+  // Helper to get role-based handlers. A route that names a capability also
+  // accepts that capability's scoped credential in the admin-secret header;
+  // it stands in for the superadmin role on that route and nowhere else.
+  const getRoleHandlers = async (
+    req: Request,
+    server?: Bun.Server<unknown>,
+    capability?: Capability,
+  ) => {
+    const adminSecretHeader = req.headers.get(env.admin.header);
+    const grant = capability ? authorizeCapability(adminSecretHeader, capability) : null;
+
+    const session: SessionContext =
+      grant && !grant.superset
+        ? { sub: capability, role: env.superadmin.role, authMethod: "admin_secret" }
+        : await getTokenService().verifyTokenAndGetSession(
+            req.headers.get(env.authorizationHeader),
+            adminSecretHeader,
+          );
+
+    const ip = resolveClientAddress(req, server, env.rateLimit.trustProxy);
 
     // The limit needs the role, and the role costs a token verification plus a
     // revocation lookup — so it is spent here, once, rather than again inside a
     // wrapper.
-    const limit = await rateLimiter?.check(
-      session,
-      resolveClientAddress(req, server, env.rateLimit.trustProxy),
-    );
+    const limit = await rateLimiter?.check(session, ip);
+
+    const scope: Capability | "all" | undefined = grant
+      ? grant.superset
+        ? "all"
+        : capability
+      : undefined;
+
+    if (session.authMethod === "admin_secret") {
+      audit().emit({
+        action: "admin_secret.used",
+        actor: { type: "admin_secret", ...(scope ? { scope } : {}), ip },
+        target: { kind: "endpoint", method: req.method, path: new URL(req.url).pathname },
+      });
+    }
 
     return {
       role: session.role!,
       session,
+      scope,
       limit,
       ...analyzedConfiguration.roles[session.role!].handlers,
     };
@@ -380,7 +412,7 @@ const createGraphQLServer = async (env: Env) => {
         name: projectConfiguration.name,
         version: projectConfiguration.version,
         maxQueryDepth: env.ai?.mcp?.maxQueryDepth ?? env.maxQueryDepth,
-        adminSecret: env.admin.secret,
+        authorize: authorizeCapability,
         adminSecretHeader: env.admin.header,
       });
 
@@ -395,7 +427,7 @@ const createGraphQLServer = async (env: Env) => {
         ...(env.enableCors ? { OPTIONS: () => new S200(null) } : {}),
         POST: async (req: BunRequest, server: Bun.Server<unknown>) => {
           try {
-            const { role, limit } = await getRoleHandlers(req, server);
+            const { role, session, scope, limit } = await getRoleHandlers(req, server, "ai");
             if (limit && !limit.allowed) return new S429(limit.retryAfterMs);
             if (role !== env.superadmin.role) return new S404({ error: "Not Found" });
 
@@ -405,6 +437,13 @@ const createGraphQLServer = async (env: Env) => {
                 errors: [{ message: "`prompt` (string) is required" }],
               });
 
+            audit().emit({
+              action: "ai.ask",
+              actor: { ...actorFromSession(session), ...(scope ? { scope } : {}) },
+              target: { kind: "ai", via: "rest" },
+              prompt,
+            });
+
             return new S200({ answer: await getAgent()(prompt) });
           } catch (error) {
             return new S400({ errors: [{ message: (error as Error)?.message }] });

package/src/logging/audit.ts

@@ -0,0 +1,86 @@
+import type { Logger } from "pino";
+import type { Capability } from "../authentication/capabilities";
+import type { SessionContext } from "../utils/sessionVariables";
+
+import { logger } from "./index";
+
+export type AuditActor = {
+  type: "admin_secret" | "console" | "token" | "credentials" | "anonymous";
+  sub?: string;
+  role?: string;
+  /** Which credential was presented at a scoped surface: `all` is the admin secret. */
+  scope?: Capability | "all";
+  ip?: string | undefined;
+};
+
+export type AuditEvent = {
+  action: string;
+  actor: AuditActor;
+  target: Record<string, unknown>;
+  outcome?: "success" | "failure";
+  [key: string]: unknown;
+};
+
+export type AuditLog = {
+  emit(event: AuditEvent): void;
+};
+
+const REDACTED_KEYS = new Set([
+  "password",
+  "secret",
+  "secrets",
+  "token",
+  "access_token",
+  "refresh_token",
+  "authorization",
+  "cookie",
+]);
+
+const redact = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(redact);
+  if (typeof value !== "object" || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [
+      key,
+      REDACTED_KEYS.has(key) ? "[REDACTED]" : redact(entry),
+    ]),
+  );
+};
+
+export const actorFromSession = (session: SessionContext | undefined): AuditActor => {
+  if (!session) return { type: "anonymous" };
+  const type =
+    session.authMethod === "admin_secret" ? "admin_secret" : session.jti ? "token" : "anonymous";
+  return {
+    type,
+    ...(session.sub !== undefined ? { sub: session.sub } : {}),
+    ...(session.role !== undefined ? { role: session.role } : {}),
+  };
+};
+
+export const createAuditLog = (base: Logger): AuditLog => {
+  // An audit record has to survive LOG_LEVEL=warn: the level is pinned here,
+  // independent of whatever the root logger was configured with.
+  const log = base.child({});
+  log.level = "info";
+
+  return {
+    emit: (event) => {
+      log.info(redact(event) as object, event.action);
+    },
+  };
+};
+
+let override: AuditLog | null = null;
+let instance: AuditLog | null = null;
+
+/** Test seam: pass `null` to restore the default log. */
+export const setAuditLog = (log: AuditLog | null): void => {
+  override = log;
+};
+
+export const audit = (): AuditLog => {
+  if (override) return override;
+  if (!instance) instance = createAuditLog(logger("audit"));
+  return instance;
+};

package/src/types/env.ts

@@ -3,19 +3,29 @@ import { z } from "zod";
 import { version } from "../../package.json";
 import { ConfigurationZod } from "./zod/configuration";
 
+// A secret env var is a comma-separated list: the first entry is the one in
+// use, the rest are still accepted so a rotation can overlap instead of cutting
+// over. Blank entries are dropped, so an unset var is an empty list.
+const splitSecrets = (value: string) =>
+  value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+const secretList = z.string().default("").transform(splitSecrets);
+
 export const EnvZod = z
   .object({
     PORT: z.coerce.number().default(3000),
     NODE_ENV: z.string().default("DEVELOPMENT"),
-    ADMIN_SECRET: z.string(),
+    ADMIN_SECRET: z.string().transform(splitSecrets),
     CONFIGURATION: z.union([z.string(), ConfigurationZod]).optional(),
     ANONYMOUS_ROLE: z.string().default("anonymous"),
-    JWT_SECRET: z.string().optional().default(""),
+    JWT_SECRET: secretList,
     JWT_EXPIRES_IN: z.string().default("5m"),
     JWT_RT_EXPIRES_IN: z.string().default("7d"),
-    PASETO_LOCAL_KEY: z.string().optional().default(""),
+    PASETO_LOCAL_KEY: secretList,
     PASETO_SECRET_KEY: z.string().optional().default(""),
-    PASETO_PUBLIC_KEY: z.string().optional().default(""),
+    PASETO_PUBLIC_KEY: secretList,
     AUTH_STRATEGY: z.enum(["jwt", "paseto_local", "paseto_public"]).optional(),
     REDIS_URL: z.string().default("redis://localhost:6379"),
     CACHE_STORE: z.enum(["memory", "redis"]).default("memory"),
@@ -31,6 +41,8 @@ export const EnvZod = z
     CONSOLE_ENABLED: z.stringbool().default(false),
     CONSOLE_ENDPOINT: z.string().default("/_console"),
     CONSOLE_SESSION_EXPIRES_IN: z.string().default("1h"),
+    CONSOLE_READ_SECRET: secretList,
+    CONSOLE_WRITE_SECRET: secretList,
     PREFIX: z.string().default(""),
     CORS_ENABLED: z.stringbool().default(true),
     PRINT_SCHEMAS: z.stringbool().default(false),
@@ -48,9 +60,11 @@ export const EnvZod = z
     AI_ENABLED: z.stringbool().optional(),
     AI_GRAPHQL_ENABLED: z.stringbool().default(true),
     AI_REST_ENABLED: z.stringbool().default(true),
+    AI_SECRET: secretList,
     AI_MCP_ENABLED: z.stringbool().optional(),
     AI_MCP_ENDPOINT: z.string().default("/mcp"),
     AI_MCP_REQUIRE_ADMIN_SECRET: z.stringbool().default(false),
+    AI_MCP_SECRET: secretList,
     AI_MCP_MAX_QUERY_DEPTH: z.coerce.number().int().min(0).optional(),
     AI_MCP_DISABLED_TOOLS: z.string().default(""),
     AI_MCP_DISABLED_RESOURCES: z.string().default(""),
@@ -80,18 +94,18 @@ export const EnvZod = z
     queryTimeoutMs: env.QUERY_TIMEOUT_MS,
     maxQueryCost: env.MAX_QUERY_COST,
     admin: {
-      secret: env.ADMIN_SECRET,
+      secrets: env.ADMIN_SECRET,
       header: env.ADMIN_SECRET_HEADER,
     },
     jwt: {
-      secret: env.JWT_SECRET,
+      secrets: env.JWT_SECRET,
       expiresIn: env.JWT_EXPIRES_IN,
       rtExpiresIn: env.JWT_RT_EXPIRES_IN,
     },
     paseto: {
-      localKey: env.PASETO_LOCAL_KEY,
+      localKeys: env.PASETO_LOCAL_KEY,
       secretKey: env.PASETO_SECRET_KEY,
-      publicKey: env.PASETO_PUBLIC_KEY,
+      publicKeys: env.PASETO_PUBLIC_KEY,
     },
     rateLimit: {
       max: env.RATE_LIMIT_MAX,
@@ -114,15 +128,19 @@ export const EnvZod = z
       enabled: env.CONSOLE_ENABLED,
       endpoint: env.CONSOLE_ENDPOINT,
       sessionExpiresIn: env.CONSOLE_SESSION_EXPIRES_IN,
+      readSecrets: env.CONSOLE_READ_SECRET,
+      writeSecrets: env.CONSOLE_WRITE_SECRET,
     },
     ai: {
       enabled: env.AI_ENABLED,
       graphqlEnabled: env.AI_GRAPHQL_ENABLED,
       restEnabled: env.AI_REST_ENABLED,
+      secrets: env.AI_SECRET,
       mcp: {
         enabled: env.AI_MCP_ENABLED,
         endpoint: env.AI_MCP_ENDPOINT,
         requireAdminSecret: env.AI_MCP_REQUIRE_ADMIN_SECRET,
+        secrets: env.AI_MCP_SECRET,
         maxQueryDepth: env.AI_MCP_MAX_QUERY_DEPTH,
         disabledTools: env.AI_MCP_DISABLED_TOOLS
           ? env.AI_MCP_DISABLED_TOOLS.split(",")

package/src/utils/responses.ts

@@ -29,6 +29,12 @@ export class S401 extends ClientResponse {
   }
 }
 
+export class S403 extends ClientResponse {
+  constructor(body?: object | null, init?: ResponseInit) {
+    super(body, { ...init, status: 403 });
+  }
+}
+
 export class S404 extends ClientResponse {
   constructor(body?: object | null, init?: ResponseInit) {
     super(body, { ...init, status: 404 });

package/src/utils/sessionVariables.ts

@@ -13,6 +13,8 @@ export type SessionContext = {
   iat?: number;
   exp?: number;
   nbf?: number;
+  /** Set when the admin secret, not a token, produced this session. */
+  authMethod?: "admin_secret";
   [key: string]: unknown;
 };