@graphoria/server 0.3.0 → 0.4.0

package/src/configuration/rest/generateOpenAPI.ts

@@ -1,38 +1,77 @@
+import { GraphQLObjectType } from "graphql";
+
+import type { GraphQLType } from "graphql";
 import type { OpenAPIV3_1 } from "openapi-types";
 import type { SelectionAnalysis } from "../../analyzeQuery/types";
 import type { GetSchemaReturn } from "../../configuration/getSchemas";
 import type { RemoteRESTResolved } from "../../remoteREST/types";
 import type { Env } from "../../types/env";
 
+import { getFieldType, unwrapType } from "../../analyzeQuery/typeUtils";
 import { convertFromZod, errors } from "./openApiErrors";
 
+// Deliberately coarse: Int and Float both map to "number", so a column keeps
+// the OpenAPI type it had when types were read off the SQL data type.
+const openApiTypeOf = (namedType: GraphQLType | undefined) => {
+  const name = namedType && "name" in namedType ? namedType.name : undefined;
+
+  switch (name) {
+    case "Int":
+    case "Float":
+      return "number";
+    case "Boolean":
+      return "boolean";
+    default:
+      return "string";
+  }
+};
+
+const resolveFieldType = (parentType: GraphQLObjectType | undefined, fieldName: string) => {
+  const fieldType = parentType && getFieldType(parentType, fieldName);
+  const namedType = fieldType ? unwrapType(fieldType).type : undefined;
+
+  return {
+    namedType,
+    objectType: namedType instanceof GraphQLObjectType ? namedType : undefined,
+  };
+};
+
+/**
+ * Resolves selections against the GraphQL schema rather than against a table
+ * name. `<table>_aggregate` returns a GroupBy wrapper whose fields — `key`,
+ * `count`, `items`, `min`/`max`/`sum`/`avg` — are not tables, so looking a
+ * selection's parent name up in the entity map typed everything under an
+ * aggregate as a string. Walking the schema also makes sanitised column names
+ * resolve, since the schema is what the client actually queries.
+ */
 const processSelections = (
-  schema: GetSchemaReturn,
-  name: string,
-  selections: SelectionAnalysis[] = [],
+  parentType: GraphQLObjectType | undefined,
+  fieldParent: SelectionAnalysis,
 ) =>
-  selections.reduce<Record<string, unknown>>((acc, field) => {
-    const type = schema.getColumnTypeForOpenApi(name, field.name);
+  fieldParent.selections?.reduce<Record<string, unknown>>((acc, field) => {
+    const { namedType, objectType } = resolveFieldType(parentType, field.name);
 
     if (field.isArray) {
       acc[field.alias || field.name] = {
         type: "array",
         items: {
           type: "object",
-          properties: processSelections(schema, field.name, field.selections),
+          properties: processSelections(objectType, field),
           required: (field.selections ?? [])
             .filter((f) => f.isRequired)
             .map((f) => f.alias || f.name),
+          nullable: !field.isRequired,
         },
       };
     } else {
       acc[field.alias || field.name] = field.selections
         ? {
             type: "object",
-            properties: processSelections(schema, field.name, field.selections),
+            properties: processSelections(objectType, field),
             required: field.selections.filter((f) => f.isRequired).map((f) => f.alias || f.name),
+            nullable: !field.isRequired,
           }
-        : { type };
+        : { type: openApiTypeOf(namedType), nullable: !field.isRequired };
     }
 
     return acc;
@@ -137,7 +176,12 @@ export const generateOpenAPI = ({
         const responseDataSchema = value.output
           ? convertFromZod(value.output)
           : (() => {
-              const fields = value.queryStructure!.operations[0].fields;
+              const operation = value.queryStructure!.operations[0];
+              const fields = operation.fields;
+              const rootType =
+                (operation.operation === "mutation"
+                  ? schema.schema.getMutationType()
+                  : schema.schema.getQueryType()) ?? undefined;
               return {
                 type: "object" as const,
                 properties: fields.reduce<Record<string, unknown>>((acc, field) => {
@@ -146,7 +190,10 @@ export const generateOpenAPI = ({
                       type: "array",
                       items: {
                         type: "object",
-                        properties: processSelections(schema, field.name, field.selections!),
+                        properties: processSelections(
+                          resolveFieldType(rootType, field.name).objectType,
+                          field,
+                        ),
                         required: (field.selections ?? [])
                           .filter((f) => f.isRequired)
                           .map((f) => f.alias || f.name),
@@ -155,7 +202,10 @@ export const generateOpenAPI = ({
                   } else {
                     acc[field.alias || field.name] = {
                       type: "object",
-                      properties: processSelections(schema, field.name, field.selections!),
+                      properties: processSelections(
+                        resolveFieldType(rootType, field.name).objectType,
+                        field,
+                      ),
                       required: (field.selections ?? [])
                         .filter((f) => f.isRequired)
                         .map((f) => f.alias || f.name),

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 { 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;
@@ -67,12 +69,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 +114,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 +145,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 +298,7 @@ export const consoleRoutesFactory = ({
 
     [`${base}/config`]: {
       ...cors,
-      GET: guarded(() => ({
+      GET: guarded((_req, _server, scope) => ({
         name: projectConfiguration.name,
         version: projectConfiguration.version,
         prefixes,
@@ -274,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;
@@ -288,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");
@@ -302,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

@@ -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/databases/core/executor.ts

@@ -78,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];
@@ -94,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

@@ -105,7 +105,6 @@ type DatabaseFunctions = {
   ) => 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/engines/mssql/connection.ts

@@ -161,7 +161,6 @@ export const executeQueryJSONSingle = executeQueryJSONFactory(true);
 
 export const callStoredProcedure = async (
   sp: ProcedureResolver,
-  variablesDefinition: VariableDefinition[],
   variables: Record<string, unknown> = {},
 ) => {
   try {
@@ -170,8 +169,6 @@ export const callStoredProcedure = async (
     const request = pool!.request();
 
     for (const [key, value] of Object.entries(variables)) {
-      if (!value) continue;
-
       const paramFound = sp.parameters.find((p) => p.name === `@${key}`);
 
       if (paramFound?.dataType === "varchar") {

package/src/databases/engines/mysql/connection.ts

@@ -7,6 +7,7 @@ import type { ProcedureResolver } from "../../../types/db";
 
 import { BunSQLConnectionOptionsZod } from "../../../config/types/db";
 import { databasesConnections } from "../../../singletons/databases";
+import { orderProcedureArguments } from "../../core/procedure-arguments";
 import { toMySQLPlaceholders } from "./placeholders";
 
 // Every pool bound comes from the schema, which is the only place they are
@@ -97,22 +98,24 @@ export const executeQueryJSONFactory =
 export const executeQueryJSON = executeQueryJSONFactory();
 export const executeQueryJSONSingle = executeQueryJSONFactory(true);
 
+// The generated schema types every stored procedure mutation as `Boolean!`, so
+// the call reports whether it ran, not what it selected. Returning the rows here
+// would put an array behind a field the schema promises is a boolean.
 export const callStoredProcedure = async (
   sp: ProcedureResolver,
-  variablesDefinition: VariableDefinition[],
   variables: Record<string, unknown>,
 ) => {
   try {
-    const data = await executeQuery(
-      `CALL ${sp.dottedQuotedName}(${Object.keys(variables)
-        .map((_, i) => `$${i + 1}`)
-        .join(", ")});`,
+    const args = orderProcedureArguments(sp, variables);
+
+    await executeQuery(
+      `CALL ${sp.dottedQuotedName}(${args.map((_, i) => `$${i + 1}`).join(", ")});`,
       sp.db!,
-      variablesDefinition,
+      args,
       variables,
     );
 
-    return data;
+    return true;
   } catch {
     return false;
   }

package/src/databases/engines/postgresql/connection.ts

@@ -7,6 +7,7 @@ import type { ProcedureResolver } from "../../../types/db";
 
 import { BunSQLConnectionOptionsZod } from "../../../config/types/db";
 import { databasesConnections } from "../../../singletons/databases";
+import { orderProcedureArguments } from "../../core/procedure-arguments";
 import { getQueryTimeoutMs } from "../../../singletons/queryTimeout";
 
 // Every pool bound comes from the schema, which is the only place they are
@@ -138,22 +139,24 @@ export const executeQueryJSONFactory =
 export const executeQueryJSON = executeQueryJSONFactory();
 export const executeQueryJSONSingle = executeQueryJSONFactory(true);
 
+// The generated schema types every stored procedure mutation as `Boolean!`, so
+// the call reports whether it ran, not what it selected. Returning the rows here
+// would put an array behind a field the schema promises is a boolean.
 export const callStoredProcedure = async (
   sp: ProcedureResolver,
-  variablesDefinition: VariableDefinition[],
   variables: Record<string, unknown>,
 ) => {
   try {
-    const data = await executeQuery(
-      `SELECT * FROM ${sp.dottedQuotedName}(${Object.keys(variables)
-        .map((_, i) => `$${i + 1}`)
-        .join(", ")});`,
+    const args = orderProcedureArguments(sp, variables);
+
+    await executeQuery(
+      `SELECT * FROM ${sp.dottedQuotedName}(${args.map((_, i) => `$${i + 1}`).join(", ")});`,
       sp.db!,
-      variablesDefinition,
+      args,
       variables,
     );
 
-    return data;
+    return true;
   } catch {
     return false;
   }