@graphoria/server 0.3.0 → 0.4.0

package/src/ai/mcp/index.ts

@@ -1,23 +1,17 @@
-import { timingSafeEqual } from "crypto";
-
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/server";
 
+import type { CapabilityAuthorizer } from "../../authentication/capabilities";
 import type { AnalyzedConfiguration } from "../../configuration";
 import type { CreateMcpServerOptions } from "./create-server";
 
 import { createMcpServer } from "./create-server";
 import { logger } from "../../logging";
-
-const safeCompare = (a: string, b: string): boolean => {
-  const bufA = Buffer.from(a);
-  const bufB = Buffer.from(b);
-  if (bufA.length !== bufB.length) return false;
-  return timingSafeEqual(bufA, bufB);
-};
+import { audit } from "../../logging/audit";
 
 export type CreateMCPRoutesOptions = CreateMcpServerOptions & {
   requireAdminSecret?: boolean;
-  adminSecret?: string;
+  /** Decides whether the presented header grants `mcp`; without one the gate never opens. */
+  authorize?: CapabilityAuthorizer;
   adminSecretHeader?: string;
 };
 
@@ -34,16 +28,27 @@ const jsonRpcError = (status: number, code: number, message: string) =>
     },
   );
 
+type RequestServer = { requestIP(req: Request): { address: string } | null };
+
 const handleMcpPost =
   (analyzedConfiguration: AnalyzedConfiguration, options: CreateMCPRoutesOptions) =>
-  async (req: Request) => {
+  async (req: Request, bunServer?: RequestServer) => {
     if (options.requireAdminSecret) {
       const headerName = options.adminSecretHeader ?? "x-admin-secret";
-      const provided = req.headers.get(headerName);
-      const expected = options.adminSecret ?? "";
-      if (!provided || !expected || !safeCompare(provided, expected)) {
+      const grant = options.authorize?.(req.headers.get(headerName), "mcp");
+      if (!grant) {
         return jsonRpcError(401, -32001, "Unauthorized: admin secret required");
       }
+      const ip = bunServer?.requestIP(req)?.address;
+      audit().emit({
+        action: "admin_secret.used",
+        actor: {
+          type: "admin_secret",
+          scope: grant.superset ? "all" : "mcp",
+          ...(ip ? { ip } : {}),
+        },
+        target: { kind: "mcp" },
+      });
     }
 
     const server = createMcpServer(analyzedConfiguration, options);

package/src/analyzeQuery/analyzers/selectionAnalyzer.ts

@@ -1,4 +1,4 @@
-import { GraphQLObjectType, GraphQLSchema } from "graphql";
+import { GraphQLNonNull, GraphQLObjectType, GraphQLSchema } from "graphql";
 
 import type { FieldNode, SelectionNode } from "graphql";
 import type { MergedEntities } from "../../configuration/getSchemas/mergeEntities";
@@ -55,6 +55,7 @@ export const analyzeSelections = (
         const directives = analyzeDirectives(field.directives || [], generatedVariables);
 
         const isRequired =
+          fieldType instanceof GraphQLNonNull &&
           directives.filter(
             (dir) => dir.name === "include" || dir.name === "skip" || dir.name === "when",
           ).length === 0;

package/src/authentication/capabilities.ts

@@ -0,0 +1,54 @@
+import type { Env } from "../types/env";
+
+import { logger } from "../logging";
+import { matchesAnySecret } from "./secrets";
+
+export type Capability = "console:read" | "console:write" | "ai" | "mcp";
+
+/** `superset` is true when the admin secret, not a scoped credential, matched. */
+export type CapabilityGrant = { superset: boolean };
+
+export type CapabilityAuthorizer = (
+  candidate: string | null,
+  capability: Capability,
+) => CapabilityGrant | null;
+
+type WarnLog = { warn: (obj: object, msg: string) => void };
+
+// Each list is checked on its own so the rotation debug line inside
+// matchesAnySecret keeps reporting the index within one credential.
+const scopedSecretsFor = (env: Env, capability: Capability): string[][] => {
+  switch (capability) {
+    case "console:read":
+      return [env.console.writeSecrets, env.console.readSecrets];
+    case "console:write":
+      return [env.console.writeSecrets];
+    case "ai":
+      return [env.ai.secrets];
+    case "mcp":
+      return [env.ai.mcp.secrets];
+  }
+};
+
+/**
+ * Decides whether a presented secret grants a capability. The admin secret
+ * grants all of them and is reported as the superset so the caller can tell
+ * the two apart; it is also logged, since a scoped credential would have done.
+ */
+export const createCapabilityAuthorizer = (
+  env: Env,
+  log: WarnLog = logger("auth"),
+): CapabilityAuthorizer => {
+  return (candidate, capability) => {
+    if (matchesAnySecret(candidate, env.admin.secrets)) {
+      log.warn({ capability }, "admin secret used where a scoped credential would do");
+      return { superset: true };
+    }
+
+    for (const secrets of scopedSecretsFor(env, capability)) {
+      if (matchesAnySecret(candidate, secrets)) return { superset: false };
+    }
+
+    return null;
+  };
+};

package/src/authentication/index.ts

@@ -7,7 +7,7 @@ import { createPASETOService } from "./paseto";
 export const createTokenService = (env: Env, strategy: TokenStrategy = "jwt"): TokenService => {
   switch (strategy) {
     case "jwt": {
-      if (!env.jwt.secret) {
+      if (env.jwt.secrets.length === 0) {
         throw new Error(
           "JWT_SECRET environment variable is required when using jwt token strategy",
         );
@@ -15,7 +15,7 @@ export const createTokenService = (env: Env, strategy: TokenStrategy = "jwt"): T
       return createJWTService(env);
     }
     case "paseto_local": {
-      if (!env.paseto.localKey) {
+      if (env.paseto.localKeys.length === 0) {
         throw new Error(
           "PASETO_LOCAL_KEY environment variable is required when using paseto_local token strategy.",
         );
@@ -23,7 +23,7 @@ export const createTokenService = (env: Env, strategy: TokenStrategy = "jwt"): T
       return createPASETOService(env, "local");
     }
     case "paseto_public": {
-      if (!env.paseto.secretKey || !env.paseto.publicKey) {
+      if (!env.paseto.secretKey || env.paseto.publicKeys.length === 0) {
         throw new Error(
           "PASETO_SECRET_KEY and PASETO_PUBLIC_KEY environment variables are required when using paseto_public token strategy.",
         );

package/src/authentication/jwt.ts

@@ -1,6 +1,4 @@
-import { timingSafeEqual } from "crypto";
-
-import { SignJWT, jwtVerify } from "jose";
+import { SignJWT, errors, jwtVerify } from "jose";
 
 import type { JWTPayload } from "jose";
 import type { Env } from "../types/env";
@@ -9,6 +7,7 @@ import type { TokenRepository } from "./tokenRepository";
 import type { TokenGenerationParameters, TokenOptions, TokenResponse, TokenService } from "./types";
 
 import { parseDurationToSeconds } from "./duration";
+import { matchesAnySecret } from "./secrets";
 import { createTokenRepository } from "./tokenRepository";
 import { logger } from "../logging";
 
@@ -16,18 +15,6 @@ import { logger } from "../logging";
 const ACCESS_TOKEN_AUDIENCE = "access";
 const REFRESH_TOKEN_AUDIENCE = "refresh";
 
-// Timing-safe string comparison to prevent timing attacks
-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;
-  }
-};
-
 export type { TokenGenerationParameters, TokenOptions, TokenResponse };
 
 export type JWTTokenPayload = JWTPayload &
@@ -43,7 +30,9 @@ export const createJWTService = (
   tokenRepositoryOverride?: TokenRepository,
 ): TokenService => {
   const tokenRepository = tokenRepositoryOverride ?? createTokenRepository(env.cache.redisUrl);
-  const jwtSecret = new TextEncoder().encode(env.jwt.secret);
+  // First entry signs; every entry verifies, so a rotation can overlap.
+  const jwtSecrets = env.jwt.secrets.map((secret) => new TextEncoder().encode(secret));
+  const signingSecret = jwtSecrets[0];
 
   const createToken = async (
     payload: TokenGenerationParameters,
@@ -67,7 +56,8 @@ export const createJWTService = (
         jwt.setNotBefore(options.notBefore);
       }
 
-      return await jwt.sign(jwtSecret);
+      if (!signingSecret) throw new Error("No JWT secret configured");
+      return await jwt.sign(signingSecret);
     } catch (error) {
       logger("auth").child({ strategy: "jwt" }).error({ err: error }, "token creation failed");
       throw new Error("Token creation failed");
@@ -78,23 +68,38 @@ export const createJWTService = (
     token: string,
     options: TokenOptions = {},
   ): Promise<T> => {
-    const { payload } = await jwtVerify(token, jwtSecret, {
+    const verifyOptions = {
       issuer: options.issuer,
       audience: options.audience,
       algorithms: [ALGORITHM],
       typ: TYP,
-    });
+    };
 
-    return payload as T;
+    let lastError: unknown = new Error("No JWT secret configured");
+    for (const [index, secret] of jwtSecrets.entries()) {
+      try {
+        const { payload } = await jwtVerify(token, secret, verifyOptions);
+        if (index > 0) {
+          logger("auth")
+            .child({ strategy: "jwt" })
+            .debug({ index }, "token verified with a previous secret");
+        }
+        return payload as T;
+      } catch (error) {
+        // Only a signature mismatch means "try the next secret"; a claim
+        // failure came from the secret that did sign this token.
+        if (!(error instanceof errors.JWSSignatureVerificationFailed)) throw error;
+        lastError = error;
+      }
+    }
+    throw lastError;
   };
 
   const verifyTokenAndGetRole = async (
     authHeader: string | null,
     adminSecretHeader: string | null,
   ): Promise<string> => {
-    // Use timing-safe comparison to prevent timing attacks
-    if (env.admin.secret && adminSecretHeader && safeCompare(adminSecretHeader, env.admin.secret))
-      return env.superadmin.role;
+    if (matchesAnySecret(adminSecretHeader, env.admin.secrets)) return env.superadmin.role;
 
     if (!authHeader) return env.anonymousRole;
 
@@ -115,8 +120,8 @@ export const createJWTService = (
     authHeader: string | null,
     adminSecretHeader: string | null,
   ): Promise<SessionContext> => {
-    if (env.admin.secret && adminSecretHeader && safeCompare(adminSecretHeader, env.admin.secret))
-      return { sub: "superadmin", role: env.superadmin.role };
+    if (matchesAnySecret(adminSecretHeader, env.admin.secrets))
+      return { sub: "superadmin", role: env.superadmin.role, authMethod: "admin_secret" };
 
     if (!authHeader || !authHeader.startsWith("Bearer "))
       return { sub: "anonymous", role: env.anonymousRole };

package/src/authentication/paseto.ts

@@ -1,5 +1,4 @@
-import { timingSafeEqual } from "crypto";
-
+import { PasetoDecryptionFailed, PasetoSignatureInvalid } from "paseto-ts/lib/errors";
 import { decrypt, encrypt, sign, verify } from "paseto-ts/v4";
 
 import type { Env } from "../types/env";
@@ -8,6 +7,7 @@ import type { TokenRepository } from "./tokenRepository";
 import type { TokenGenerationParameters, TokenOptions, TokenResponse, TokenService } from "./types";
 
 import { parseDurationToSeconds, toPasetoDuration } from "./duration";
+import { matchesAnySecret } from "./secrets";
 import { createTokenRepository } from "./tokenRepository";
 import { logger } from "../logging";
 
@@ -15,18 +15,6 @@ import { logger } from "../logging";
 const ACCESS_TOKEN_AUDIENCE = "access";
 const REFRESH_TOKEN_AUDIENCE = "refresh";
 
-// Timing-safe string comparison to prevent timing attacks
-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;
-  }
-};
-
 type PasetoPayload = {
   sub: string;
   role: string;
@@ -56,7 +44,12 @@ export const createPASETOService = (
 ): TokenService => {
   const tokenRepository = tokenRepositoryOverride ?? createTokenRepository(env.cache.redisUrl);
 
-  // Token creation and verification functions based on mode
+  // In local mode the first key encrypts and every key decrypts. In public
+  // mode the secret key signs and every public key verifies. Either way a
+  // rotation can overlap.
+  const verifyingKeys = mode === "local" ? env.paseto.localKeys : env.paseto.publicKeys;
+  const signingKey = mode === "local" ? env.paseto.localKeys[0] : env.paseto.secretKey;
+
   const createPasetoToken = async (
     payload: Record<string, unknown>,
     expiry: string,
@@ -66,19 +59,37 @@ export const createPASETOService = (
       exp: toPasetoDuration(expiry),
     };
 
+    if (!signingKey) throw new Error("No PASETO key configured");
     if (mode === "local") {
-      return encrypt(env.paseto.localKey!, pasetoPayload);
+      return encrypt(signingKey, pasetoPayload);
     }
-    return sign(env.paseto.secretKey!, pasetoPayload);
+    return sign(signingKey, pasetoPayload);
   };
 
   const verifyPasetoToken = async (token: string): Promise<PasetoPayload> => {
-    if (mode === "local") {
-      const { payload } = await decrypt<PasetoPayload>(env.paseto.localKey!, token);
-      return payload;
+    let lastError: unknown = new Error("No PASETO key configured");
+    for (const [index, key] of verifyingKeys.entries()) {
+      try {
+        const { payload } =
+          mode === "local"
+            ? await decrypt<PasetoPayload>(key, token)
+            : await verify<PasetoPayload>(key, token);
+        if (index > 0) {
+          logger("auth")
+            .child({ strategy: "paseto" })
+            .debug({ index }, "token verified with a previous key");
+        }
+        return payload;
+      } catch (error) {
+        // Only a key mismatch means "try the next key"; a claim failure came
+        // from the key that did produce this token.
+        const keyMismatch =
+          error instanceof PasetoDecryptionFailed || error instanceof PasetoSignatureInvalid;
+        if (!keyMismatch) throw error;
+        lastError = error;
+      }
     }
-    const { payload } = await verify<PasetoPayload>(env.paseto.publicKey!, token);
-    return payload;
+    throw lastError;
   };
 
   const createToken = async (
@@ -132,8 +143,7 @@ export const createPASETOService = (
     authHeader: string | null,
     adminSecretHeader: string | null,
   ): Promise<string> => {
-    if (env.admin.secret && adminSecretHeader && safeCompare(adminSecretHeader, env.admin.secret))
-      return env.superadmin.role;
+    if (matchesAnySecret(adminSecretHeader, env.admin.secrets)) return env.superadmin.role;
 
     if (!authHeader) return env.anonymousRole;
 
@@ -153,8 +163,8 @@ export const createPASETOService = (
     authHeader: string | null,
     adminSecretHeader: string | null,
   ): Promise<SessionContext> => {
-    if (env.admin.secret && adminSecretHeader && safeCompare(adminSecretHeader, env.admin.secret))
-      return { sub: "superadmin", role: env.superadmin.role };
+    if (matchesAnySecret(adminSecretHeader, env.admin.secrets))
+      return { sub: "superadmin", role: env.superadmin.role, authMethod: "admin_secret" };
 
     if (!authHeader || !authHeader.startsWith("Bearer "))
       return { sub: "anonymous", role: env.anonymousRole };

package/src/authentication/secrets.ts

@@ -0,0 +1,30 @@
+import { timingSafeEqual } from "crypto";
+
+import { logger } from "../logging";
+
+// Timing-safe string comparison to prevent timing attacks
+export 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;
+  }
+};
+
+/**
+ * True when `candidate` equals any entry of a rotating secret set. The first
+ * entry is the current secret; a match further along means a caller still
+ * holds a previous one, which is logged so the operator knows when it is safe
+ * to drop it.
+ */
+export const matchesAnySecret = (candidate: string | null, secrets: string[]): boolean => {
+  if (!candidate) return false;
+
+  const index = secrets.findIndex((secret) => safeCompare(candidate, secret));
+  if (index > 0) logger("auth").debug({ index }, "matched a previous secret");
+
+  return index >= 0;
+};

package/src/configuration/getSchemas/mergeEntities/index.ts

@@ -7,23 +7,6 @@ import type { TypedOperation } from "../../../types/zod/operation";
 
 import { EntitySource, createResolverEntry } from "../../../types/resolver";
 import { columnFieldName } from "../../../databases/transformers/graphqlName";
-import { SqlTypeCategory, categorizeSqlType } from "../../../databases/sqlTypeUtils";
-
-const dataTypeToOpenApiType = (dataType: string): string => {
-  const category = categorizeSqlType(dataType);
-
-  switch (category) {
-    case SqlTypeCategory.INTEGER:
-    case SqlTypeCategory.FLOAT:
-      return "number";
-    case SqlTypeCategory.BOOLEAN:
-      return "boolean";
-    case SqlTypeCategory.DATE_TIME:
-    case SqlTypeCategory.STRING:
-    default:
-      return "string";
-  }
-};
 
 export const mergeEntities = (
   entityOfRole: EntitiesOfRole,
@@ -236,15 +219,6 @@ export const mergeEntities = (
      */
     columnSqlName: (table: string, fieldName: string): string =>
       queriesMap[table]?.columns.find((c) => columnFieldName(c) === fieldName)?.name ?? fieldName,
-    getColumnTypeForOpenApi: (table: string, column: string) => {
-      const tableObj = queriesMap[table];
-
-      const columnObj = tableObj?.columns.find((c) => c.name === column);
-
-      if (!columnObj) return "string";
-
-      return dataTypeToOpenApiType(columnObj.dataType);
-    },
   };
 };
 

package/src/configuration/gql/gqlAuthOperations.ts

@@ -5,6 +5,7 @@ import type { SessionContext } from "../../utils/sessionVariables";
 
 import { resolveVariableRef } from "../../analyzeQuery/resolveVariables";
 import { checkUserCredentials } from "../../databases";
+import { actorFromSession, audit } from "../../logging/audit";
 import { getTokenService } from "../../singletons/authentication";
 
 // Handle auth mutations: auth_login / auth_refresh / auth_logout
@@ -35,9 +36,23 @@ export const handleAuthMutation = async (
       passwordValue.toString(),
     );
 
+    const actor = { type: "credentials", sub: usernameValue.toString() } as const;
     if (!result.valid) {
+      audit().emit({
+        action: "auth.login",
+        outcome: "failure",
+        actor,
+        target: { kind: "auth", via: "graphql" },
+        reason: "Invalid username or password",
+      });
       throw new Error("Invalid username or password");
     }
+    audit().emit({
+      action: "auth.login",
+      outcome: "success",
+      actor,
+      target: { kind: "auth", via: "graphql", role: result.role },
+    });
 
     const data = await getTokenService().createTokenPair({
       sub: usernameValue.toString(),
@@ -104,9 +119,11 @@ export const handleAuthMutation = async (
 
   if (field.name === "auth_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");
@@ -116,6 +133,7 @@ export const handleAuthMutation = async (
           audience: "refresh",
         });
         await tokenService.revoke(refreshPayload.jti);
+        revoked.push(refreshPayload.jti);
       } catch {
         // tampered or expired cookie — nothing to revoke
       }
@@ -125,6 +143,14 @@ export const handleAuthMutation = async (
       req.cookies.delete("refresh_token");
     }
 
+    if (revoked.length > 0) {
+      audit().emit({
+        action: "auth.logout",
+        actor: actorFromSession(session),
+        target: { kind: "auth", via: "graphql", revoked },
+      });
+    }
+
     return {
       data: {
         [field.alias || field.name]: true,

package/src/configuration/gql/handleGraphQLRequestFactory.ts

@@ -17,6 +17,7 @@ import { resolveVariableRef, resolveVariables } from "../../analyzeQuery/resolve
 import { callStoredProcedure, executeQueryJSON, generateSQL } from "../../databases";
 import { proxyRemoteField } from "../../remoteSchemas/proxy";
 import { getAgent } from "../../singletons/ai";
+import { actorFromSession, audit } from "../../logging/audit";
 import { databasesConnections, repositoryMap } from "../../singletons/databases";
 import { env } from "../../singletons/env";
 import { queueManager } from "../../singletons/queues";
@@ -44,7 +45,7 @@ export const handleGraphQLRequestFactory = (
       ) => Promise<{ data: object }>
     >
   > = {
-    [EntitySource.QUEUE_PUBLISHER]: async (field, variables) => {
+    [EntitySource.QUEUE_PUBLISHER]: async (field, variables, _queryAnalysis, _req, session) => {
       const data = resolveVariableRef(variables, field.arguments?.data);
 
       const publisher = entities.queuesMap[field.name];
@@ -53,6 +54,12 @@ export const handleGraphQLRequestFactory = (
         throw new Error(`Queue publisher not found: ${field.name}`);
       }
 
+      audit().emit({
+        action: "queue.publish",
+        actor: actorFromSession(session),
+        target: { kind: "publisher", name: publisher.resolverName },
+      });
+
       return {
         data: {
           [field.alias || field.name]: await queueManager?.sendMessage(
@@ -100,7 +107,7 @@ export const handleGraphQLRequestFactory = (
       };
     },
 
-    [EntitySource.STORED_PROCEDURE]: async (field, variables, queryAnalysis) => {
+    [EntitySource.STORED_PROCEDURE]: async (field, variables) => {
       const sp = entities.mutationsMap[field.name];
 
       if (!sp) {
@@ -116,7 +123,6 @@ export const handleGraphQLRequestFactory = (
 
       const result = await callStoredProcedure(
         sp,
-        queryAnalysis.operations[0].variables ?? [],
         argumentsReplaced as Record<string, string | number | boolean | null>,
       );
 
@@ -364,8 +370,14 @@ export const handleGraphQLRequestFactory = (
         let aiData: Record<string, unknown> = {};
         for (const field of aiFields) {
           const alias = field.alias || field.name;
-          const prompt = field.arguments?.prompt;
-          aiData[alias] = await getAgent()(String(prompt ?? ""));
+          const prompt = String(field.arguments?.prompt ?? "");
+          audit().emit({
+            action: "ai.ask",
+            actor: actorFromSession(session),
+            target: { kind: "ai", via: "graphql" },
+            prompt,
+          });
+          aiData[alias] = await getAgent()(prompt);
         }
 
         // Skip SQL generation if there are no table fields

package/src/configuration/gql/handleGraphQLSubscriptionFactory.ts

@@ -10,6 +10,7 @@ import { getTokenService } from "../../singletons/authentication";
 import { createSubscriptionStrategyRegistry, getStrategyForSource } from "../../subscriptions";
 import { createQueryEventEmitter } from "../../utils/event-emitter";
 import { logger } from "../../logging";
+import { audit } from "../../logging/audit";
 
 export const queryEventEmitter = createQueryEventEmitter();
 
@@ -60,6 +61,14 @@ const handleGraphQLSubscriptionFactory = (
 
         subscriptionMapping.set(ws, session);
 
+        if (session.authMethod === "admin_secret") {
+          audit().emit({
+            action: "admin_secret.used",
+            actor: { type: "admin_secret", ip: ws.remoteAddress },
+            target: { kind: "websocket" },
+          });
+        }
+
         logger("subscriptions").debug({ role: session.role }, "client connected");
 
         ws.send(