@graphoria/server 0.2.3 → 0.4.0

package/src/console/api.ts

@@ -1,14 +1,20 @@
+import type { ConsoleScope } from "./session";
+import type { TokenService } from "../authentication/types";
 import type { AnalyzedConfiguration } from "../configuration";
 import type { Configuration } from "../types/configuration";
 import type { Env } from "../types/env";
-import type { SQL } from "bun";
+import type { RateLimiter } from "../utils/rateLimit";
+import type { BunRequest, SQL } from "bun";
 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 { queueManager } from "../singletons/queues";
-import { S200, S400, S404 } from "../utils/responses";
+import { resolveClientAddress } from "../utils/rateLimit";
+import { S200, S400, S401, S403, S404, S429 } from "../utils/responses";
 
 type ConsoleRoutesFactoryOptions = {
   env: Env;
@@ -16,10 +22,16 @@ type ConsoleRoutesFactoryOptions = {
   prefixes: Record<string, string>;
   projectConfiguration: Configuration;
   analyzedConfiguration: AnalyzedConfiguration;
-  getRoleHandlers: (req: Request) => Promise<{ role: string }>;
+  tokenService: TokenService;
+  rateLimiter?: RateLimiter | undefined;
 };
 
-type ConsoleRouteHandler = (req: Request) => Response | Promise<Response>;
+// Bun hands a route handler the server as its second argument; the parameter is
+// optional only because the type is also used for handlers that ignore it.
+type ConsoleRouteHandler = (
+  req: BunRequest,
+  server?: Bun.Server<unknown>,
+) => Response | Promise<Response>;
 
 const PING_TIMEOUT_MS = 2000;
 
@@ -52,15 +64,30 @@ export const consoleRoutesFactory = ({
   prefixes,
   projectConfiguration,
   analyzedConfiguration,
-  getRoleHandlers,
+  tokenService,
+  rateLimiter,
 }: 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: Request) => object | Promise<object>): ConsoleRouteHandler =>
-    async (req: Request) => {
+    (
+      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 {
-        const { role } = await getRoleHandlers(req);
-        if (role !== env.superadmin.role) 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 }] });
       }
@@ -78,10 +105,58 @@ export const consoleRoutesFactory = ({
         new S200({
           name: projectConfiguration.name,
           version: projectConfiguration.version,
-          adminSecretHeader: env.admin.header,
         }),
     },
 
+    [`${base}/login`]: {
+      ...cors,
+      POST: async (req, server) => {
+        // 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 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 {
+          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" }] });
+        }
+      },
+    },
+
+    [`${base}/logout`]: {
+      ...cors,
+      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 });
+      },
+    },
+
     [`${base}/tables`]: {
       ...cors,
       GET: guarded(() => ({
@@ -223,7 +298,7 @@ export const consoleRoutesFactory = ({
 
     [`${base}/config`]: {
       ...cors,
-      GET: guarded(() => ({
+      GET: guarded((_req, _server, scope) => ({
         name: projectConfiguration.name,
         version: projectConfiguration.version,
         prefixes,
@@ -233,12 +308,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;
@@ -247,13 +323,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");
@@ -261,10 +342,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

@@ -0,0 +1,129 @@
+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";
+
+export const CONSOLE_SESSION_COOKIE = "graphoria_console_session";
+
+// Separates a console session from an access or refresh token signed with the
+// same key: neither can be presented where the other is expected.
+const CONSOLE_AUDIENCE = "console";
+const CONSOLE_SUBJECT = "console";
+
+/** `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 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 = {
+  env: Env;
+  consolePath: string;
+  tokenService: TokenService;
+};
+
+export const createConsoleSessions = ({
+  env,
+  consolePath,
+  tokenService,
+}: ConsoleSessionsOptions): ConsoleSessions => {
+  const log = logger("console");
+  const authorizeCapability = createCapabilityAuthorizer(env);
+  const expiresIn = env.console.sessionExpiresIn;
+  const sessionMs = parseDurationToMs(expiresIn);
+
+  // Revoked JTIs, held in this process only: the console mints its own tokens
+  // and never writes to the Redis JTI store, so a logout is honoured by the
+  // worker that served it and by no other. An entry is dropped once the token
+  // it revokes would have expired on its own.
+  const revoked = new Map<string, number>();
+
+  const prune = () => {
+    const now = Date.now();
+    for (const [jti, expiresAt] of revoked) if (expiresAt <= now) revoked.delete(jti);
+  };
+
+  const cookieOptions = {
+    httpOnly: true,
+    secure: true,
+    sameSite: "strict",
+    path: consolePath,
+  } as const;
+
+  const readSession = async (req: BunRequest) => {
+    const cookie = req.cookies?.get(CONSOLE_SESSION_COOKIE);
+    if (!cookie) return null;
+
+    try {
+      const payload = await tokenService.verifyToken(cookie, { audience: CONSOLE_AUDIENCE });
+      if (payload.role !== env.superadmin.role) return null;
+      const scope = payload.claims?.scope;
+      if (!isScope(scope)) return null;
+      return { ...payload, scope };
+    } catch {
+      return null;
+    }
+  };
+
+  return {
+    login: async (req) => {
+      const { secret: submitted } = (await req.json()) as { secret?: string };
+
+      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, claims: { scope } },
+        { audience: CONSOLE_AUDIENCE, expiresIn },
+      );
+
+      req.cookies.set(CONSOLE_SESSION_COOKIE, token, {
+        ...cookieOptions,
+        maxAge: parseDurationToSeconds(expiresIn),
+      });
+
+      log.info({ scope }, "console session issued");
+
+      return { expiresIn: parseDurationToSeconds(expiresIn), scope, superset: grant.superset };
+    },
+
+    authorize: async (req) => {
+      const payload = await readSession(req);
+      if (!payload) return null;
+
+      prune();
+      return revoked.has(payload.jti) ? null : payload.scope;
+    },
+
+    logout: async (req) => {
+      const payload = await readSession(req);
+      if (payload) {
+        // The token stays valid until it expires, so the revocation record has
+        // to outlive it: one full session lifetime is the upper bound.
+        revoked.set(payload.jti, Date.now() + sessionMs);
+        log.info("console session revoked");
+      }
+
+      req.cookies.delete({ name: CONSOLE_SESSION_COOKIE, path: consolePath });
+
+      return payload !== null;
+    },
+  };
+};

package/src/databases/common.ts

@@ -826,37 +826,82 @@ const toPositionalPlaceholder = (
   return null;
 };
 
+/**
+ * Page bounds applied to a list field. `null` at a call site means the query is
+ * operator-authored and exempt; `0` on either field opts that half out.
+ */
+export type PageLimits = {
+  defaultPageSize: number;
+  maxPageSize: number;
+};
+
+// Resolve the requested limit to a number, following a $ref into the runtime
+// values. Returns undefined when there is no limit or it cannot be resolved.
+const resolveLimitValue = (
+  value: unknown,
+  variables: Record<string, unknown>,
+): number | undefined => {
+  const resolved = isString(value) && value.startsWith("$") ? variables[value.substring(1)] : value;
+
+  return typeof resolved === "number" ? resolved : undefined;
+};
+
 // Factory function for pagination clause builders
 export const buildPaginationClauseFp =
   (dbType: DatabaseType = "pg") =>
-  (field: SelectionAnalysis, variablesDefinition: VariableDefinition[] = []): string => {
+  (
+    field: SelectionAnalysis,
+    variablesDefinition: VariableDefinition[] = [],
+    variables: Record<string, unknown> = {},
+    pageLimits: PageLimits | null = null,
+  ): string => {
     const args = field.arguments;
 
-    if (!args || args["limit"] === undefined) {
-      return "";
+    const requested = resolveLimitValue(args?.["limit"], variables);
+
+    if (pageLimits && pageLimits.maxPageSize > 0 && requested !== undefined) {
+      if (requested > pageLimits.maxPageSize) {
+        throw new Error(
+          `Requested page size of ${requested} exceeds the maximum allowed page size of ${pageLimits.maxPageSize} (field: "${field.alias || field.name}"). Raise MAX_PAGE_SIZE to allow larger pages.`,
+        );
+      }
     }
 
     // Convert limit variable reference to positional placeholder
-    const limitPlaceholder = toPositionalPlaceholder(args["limit"], variablesDefinition, dbType);
-    if (!limitPlaceholder) {
-      return ""; // Limit must be a variable reference
+    const limitPlaceholder =
+      args?.["limit"] === undefined
+        ? null
+        : toPositionalPlaceholder(args["limit"], variablesDefinition, dbType);
+
+    // An unbounded list field reads the whole table. Supply the default page
+    // size as a literal: minting a variable here would have to push onto the
+    // same definition list the driver binds positionally from, and that order
+    // is load-bearing. The value is an env-validated integer, never caller text.
+    const limitClause =
+      limitPlaceholder ??
+      (field.isArray && pageLimits && pageLimits.defaultPageSize > 0
+        ? String(pageLimits.defaultPageSize)
+        : null);
+
+    if (!limitClause) {
+      return "";
     }
 
     // Convert offset variable reference to positional placeholder (default to 0 if not provided)
-    const offsetPlaceholder = args["offset"]
+    const offsetPlaceholder = args?.["offset"]
       ? toPositionalPlaceholder(args["offset"], variablesDefinition, dbType)
       : "0";
 
     if (dbType !== "mssql") {
-      return `LIMIT ${limitPlaceholder} OFFSET ${offsetPlaceholder}`;
+      return `LIMIT ${limitClause} OFFSET ${offsetPlaceholder}`;
     }
 
     // T-SQL only accepts OFFSET/FETCH after an ORDER BY. Dropping the limit when
     // the query has none returned the whole table instead, so supply the
     // order-agnostic ORDER BY that T-SQL accepts for exactly this case.
-    const orderByFallback = args["orderBy"] === undefined ? "ORDER BY (SELECT NULL) " : "";
+    const orderByFallback = args?.["orderBy"] === undefined ? "ORDER BY (SELECT NULL) " : "";
 
-    return `${orderByFallback}OFFSET ${offsetPlaceholder} ROWS FETCH NEXT ${limitPlaceholder} ROWS ONLY`;
+    return `${orderByFallback}OFFSET ${offsetPlaceholder} ROWS FETCH NEXT ${limitClause} ROWS ONLY`;
   };
 
 export const buildPaginationClausePG = buildPaginationClauseFp("pg");

package/src/databases/core/executor.ts

@@ -14,6 +14,8 @@ export const executeQuery = async <T>(
   db: Database,
   variablesDefinition: VariableDefinition[],
   variables: Record<string, unknown>,
+  /** Per-operation override. `undefined` leaves the engine on its own default. */
+  timeoutMs?: number,
 ) => {
   const adapter = databaseAdapters[db?.type];
   if (!adapter) {
@@ -24,7 +26,7 @@ export const executeQuery = async <T>(
   const startTime = Bun.nanoseconds();
 
   try {
-    const result = await adapter.execute<T>(query, db, variablesDefinition, variables);
+    const result = await adapter.execute<T>(query, db, variablesDefinition, variables, timeoutMs);
     log.debug(
       { durationMs: (Bun.nanoseconds() - startTime) / 1e6, queryLength: query.length },
       "query executed",
@@ -41,6 +43,8 @@ export const executeQueryJSON = async <T>(
   db: Database,
   variablesDefinition: VariableDefinition[],
   variables: Record<string, unknown>,
+  /** Per-operation override. `undefined` leaves the engine on its own default. */
+  timeoutMs?: number,
 ) => {
   const adapter = databaseAdapters[db.type];
   if (!adapter) {
@@ -51,7 +55,13 @@ export const executeQueryJSON = async <T>(
   const startTime = Bun.nanoseconds();
 
   try {
-    const result = await adapter.executeJson<T>(query, db, variablesDefinition, variables);
+    const result = await adapter.executeJson<T>(
+      query,
+      db,
+      variablesDefinition,
+      variables,
+      timeoutMs,
+    );
     log.debug(
       { durationMs: (Bun.nanoseconds() - startTime) / 1e6, queryLength: query.length },
       "query executed (json)",
@@ -68,7 +78,6 @@ export const executeQueryJSON = async <T>(
 
 export const callStoredProcedure = async (
   sp: ProcedureResolver,
-  variablesDefinition: VariableDefinition[],
   variables: Record<string, unknown> = {},
 ) => {
   const adapter = databaseAdapters[sp.db!.type];
@@ -84,7 +93,7 @@ export const callStoredProcedure = async (
   const startTime = Bun.nanoseconds();
 
   try {
-    const result = await adapter.callStoredProcedure(sp, variablesDefinition, variables);
+    const result = await adapter.callStoredProcedure(sp, variables);
     log.debug({ durationMs: (Bun.nanoseconds() - startTime) / 1e6 }, "stored procedure executed");
     return result;
   } catch (error) {

package/src/databases/core/function-mapping.ts

@@ -3,6 +3,7 @@ import type { MergedEntities } from "../../configuration/getSchemas/mergeEntitie
 import type { Auth, Database, DatabaseType } from "../../types/configuration";
 import type { DatabaseStructure, ProcedureResolver, TableResolver, View } from "../../types/db";
 import type { GenerateCreateTableSQLParameters } from "../schemaBuilder/generateCreateTable";
+import type { PageLimits } from "../common";
 
 import {
   checkUserCredentials as checkUserCredentialsMSSQL,
@@ -85,22 +86,25 @@ type DatabaseFunctions = {
     operation: OperationAnalysis,
     variables: Record<string, unknown>,
     forHashMethod: boolean,
+    pageLimits: PageLimits | null,
+    timeoutMs: number | undefined,
   ) => string;
   execute: <T>(
     query: string,
     db: Database,
     variablesDefinition: VariableDefinition[],
     values: Record<string, unknown>,
+    timeoutMs: number | undefined,
   ) => Promise<T[]>;
   executeJson: <T>(
     query: string,
     db: Database,
     variablesDefinition: VariableDefinition[],
     values: Record<string, unknown>,
+    timeoutMs: number | undefined,
   ) => Promise<T>;
   callStoredProcedure: (
     sp: ProcedureResolver,
-    variablesDefinition: VariableDefinition[],
     parameters: Record<string, unknown>,
     // oxlint-disable-next-line typescript/no-explicit-any
   ) => Promise<any>;

package/src/databases/core/procedure-arguments.ts

@@ -0,0 +1,25 @@
+import type { VariableDefinition } from "../../analyzeQuery/types";
+import type { ProcedureResolver } from "../../types/db";
+
+/**
+ * Orders a procedure call's arguments for the engines that bind positionally.
+ *
+ * `$1, $2, …` are numbered by one list and filled from another, so the two have
+ * to be the same list or the values land on the wrong parameters. Signature
+ * order comes from the introspected metadata; the caller's argument object is
+ * unordered and reflects the GraphQL query text.
+ *
+ * Arguments the metadata doesn't account for keep their supplied order and
+ * follow: an unnamed procedure parameter is introspected under a synthesized
+ * name that no caller can match, and dropping the value there would be worse
+ * than binding it where it was already going.
+ */
+export const orderProcedureArguments = (
+  sp: ProcedureResolver,
+  variables: Record<string, unknown>,
+): VariableDefinition[] => {
+  const declared = sp.parameters.map((p) => p.name).filter((name) => name in variables);
+  const undeclared = Object.keys(variables).filter((name) => !declared.includes(name));
+
+  return [...declared, ...undeclared].map((name) => ({ name, type: "", required: false }));
+};

package/src/databases/core/query-builder.ts

@@ -1,6 +1,7 @@
 import type { AnalysisResult, SelectionAnalysis } from "../../analyzeQuery/types";
 import type { MergedEntities } from "../../configuration/getSchemas/mergeEntities";
 import type { Database } from "../../types/configuration";
+import type { PageLimits } from "../common";
 
 import { databaseAdapters } from "./function-mapping";
 
@@ -9,6 +10,10 @@ export const generateSQL = (
   analysisResult: AnalysisResult,
   variables: Record<string, unknown> = {},
   forHashMethod: boolean = false,
+  /** `null` exempts the query — operator-authored queries are configuration, not caller input. */
+  pageLimits: PageLimits | null = null,
+  /** Per-operation override. `undefined` leaves the engine on its own default. */
+  timeoutMs?: number,
 ) => {
   const operation = analysisResult.operations[0];
 
@@ -40,6 +45,8 @@ export const generateSQL = (
         },
         variables,
         forHashMethod,
+        pageLimits,
+        timeoutMs,
       );
 
       return [db, query] as const;