@graphoria/server 0.2.3 → 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/ai/tools/core.ts

@@ -15,8 +15,10 @@ import type { BunRequest } from "bun";
 import type { GraphQLNamedType, GraphQLSchema } from "graphql";
 import type { GetSchemaReturn } from "../../configuration/getSchemas";
 
+import { checkQueryCost } from "../../analyzeQuery/costLimit";
 import { depthLimitRule } from "../../analyzeQuery/depthLimit";
 import { categorizeSqlType, isNumericType, SqlTypeCategory } from "../../databases/sqlTypeUtils";
+import { env } from "../../singletons/env";
 
 /**
  * A per-role compiled schema bundle (tables, operations, handlers, …).
@@ -202,7 +204,10 @@ export type ValidationError = {
   locations?: ReadonlyArray<{ line: number; column: number }>;
 };
 
-export type ValidateQueryFn = (query: string) => {
+export type ValidateQueryFn = (
+  query: string,
+  variables?: Record<string, unknown>,
+) => {
   hasErrors: boolean;
   validationErrors: readonly ValidationError[];
 };
@@ -211,18 +216,37 @@ export type ValidateQueryFn = (query: string) => {
  * Build a query validator for a role. Without a positive depth limit it
  * delegates to the role's own `hasErrors`; with one it layers a depth-limit
  * rule on the standard rule set.
+ *
+ * The cost budget applies on both branches, and there is no MCP-specific
+ * override for it. MCP gets its own depth knob because an agent legitimately
+ * writes deeper queries than an application does; nothing makes the same
+ * argument for asking a database for more rows.
  */
 export const makeValidateQuery =
   (role: RoleEntities, maxQueryDepth?: number): ValidateQueryFn =>
-  (query) => {
+  (query, variables) => {
     if (maxQueryDepth === undefined || maxQueryDepth <= 0) {
-      return role.handlers.gql.hasErrors(query);
+      return role.handlers.gql.hasErrors(query, { variables });
     }
-    const errors = validate(role.schema, parse(query), [
+    const document = parse(query);
+    const errors = validate(role.schema, document, [
       ...specifiedRules,
       depthLimitRule(maxQueryDepth),
     ]);
-    return { hasErrors: errors.length > 0, validationErrors: errors };
+    if (errors.length > 0) return { hasErrors: true, validationErrors: errors };
+
+    if (env.maxQueryCost > 0) {
+      const costError = checkQueryCost(
+        document,
+        role.schema,
+        variables ?? {},
+        { defaultPageSize: env.defaultPageSize, maxPageSize: env.maxPageSize },
+        env.maxQueryCost,
+      );
+      if (costError) return { hasErrors: true, validationErrors: [costError] };
+    }
+
+    return { hasErrors: false, validationErrors: errors };
   };
 
 // ---- graphql_execute ----
@@ -246,7 +270,7 @@ export const executeGraphqlCore = async (
   try {
     if (containsNonQueryOperation(query)) return { kind: "non_query" };
 
-    const { hasErrors, validationErrors } = validateQuery(query);
+    const { hasErrors, validationErrors } = validateQuery(query, variables);
     if (hasErrors) {
       return {
         kind: "validation",

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/analyzeQuery/costLimit.ts

@@ -0,0 +1,236 @@
+import { GraphQLError, GraphQLObjectType, Kind } from "graphql";
+
+import type {
+  DocumentNode,
+  FieldNode,
+  FragmentDefinitionNode,
+  GraphQLSchema,
+  OperationDefinitionNode,
+  SelectionSetNode,
+  ValueNode,
+} from "graphql";
+
+import { collectFragments } from "./fragments";
+import { getFieldType, unwrapType } from "./typeUtils";
+
+/**
+ * Page bounds the estimate is drawn against. `maxPageSize` is carried, not read:
+ * a resolved limit above it is rejected at execution, so the walk never has to
+ * clamp — but the estimator needs it the day that ordering changes.
+ */
+export type CostPageLimits = {
+  defaultPageSize: number;
+  maxPageSize: number;
+};
+
+type WalkContext = {
+  schema: GraphQLSchema;
+  variables: Record<string, unknown>;
+  pageLimits: CostPageLimits;
+  fragments: Map<string, FragmentDefinitionNode>;
+  // A fragment's cost depends only on its own body and type condition, so one
+  // expansion serves every spread of it. Without this a document whose
+  // fragments each spread the next one twice costs 2^n to estimate.
+  fragmentCosts: Map<string, number>;
+};
+
+// Resolve an argument to a number, following a variable into the runtime values.
+// Mirrors `resolveLimitValue` in databases/common.ts so the estimate and the
+// page-size cap agree on what "resolves to a number" means.
+const resolveIntValue = (
+  value: ValueNode | undefined,
+  variables: Record<string, unknown>,
+): number | undefined => {
+  if (!value) return undefined;
+
+  if (value.kind === Kind.INT) return Number.parseInt(value.value, 10);
+
+  if (value.kind === Kind.VARIABLE) {
+    const resolved = variables[value.name.value];
+    return typeof resolved === "number" ? resolved : undefined;
+  }
+
+  return undefined;
+};
+
+// How many rows a field's children are paid for. Only a list field multiplies:
+// a to-one relationship, a single-row field and a scalar each cost their subtree
+// once.
+const multiplierFor = (field: FieldNode, isArray: boolean, ctx: WalkContext): number => {
+  if (!isArray) return 1;
+
+  const limit = field.arguments?.find((argument) => argument.name.value === "limit")?.value;
+
+  return resolveIntValue(limit, ctx.variables) ?? ctx.pageLimits.defaultPageSize;
+};
+
+const objectTypeNamed = (schema: GraphQLSchema, name: string): GraphQLObjectType | undefined => {
+  const type = schema.getType(name);
+  return type instanceof GraphQLObjectType ? type : undefined;
+};
+
+const costOfFragment = (name: string, ctx: WalkContext, onPath: Set<string>): number => {
+  const memoised = ctx.fragmentCosts.get(name);
+  if (memoised !== undefined) return memoised;
+
+  // A fragment already on the path is a cycle. `validate` rejects those before
+  // the estimate runs; cutting here only keeps a hand-built document finite.
+  if (onPath.has(name)) return 0;
+
+  const fragment = ctx.fragments.get(name);
+  if (!fragment) return 0;
+
+  onPath.add(name);
+  const cost = costOfSelectionSet(
+    fragment.selectionSet,
+    objectTypeNamed(ctx.schema, fragment.typeCondition.name.value),
+    ctx,
+    onPath,
+  );
+  onPath.delete(name);
+
+  ctx.fragmentCosts.set(name, cost);
+  return cost;
+};
+
+/**
+ * `cost(field) = 1 + multiplier(field) × Σ cost(child)`, summed across the
+ * selection set. An unresolved parent type costs its children once — the
+ * estimate degrades, it does not throw.
+ */
+const costOfSelectionSet = (
+  selectionSet: SelectionSetNode | undefined,
+  parentType: GraphQLObjectType | undefined,
+  ctx: WalkContext,
+  onPath: Set<string>,
+): number => {
+  if (!selectionSet) return 0;
+
+  let total = 0;
+
+  for (const selection of selectionSet.selections) {
+    switch (selection.kind) {
+      case Kind.FIELD: {
+        if (selection.name.value.startsWith("__")) continue;
+
+        const fieldType = parentType ? getFieldType(parentType, selection.name.value) : undefined;
+        const unwrapped = fieldType ? unwrapType(fieldType) : undefined;
+        const childType = unwrapped?.type instanceof GraphQLObjectType ? unwrapped.type : undefined;
+
+        const children = costOfSelectionSet(selection.selectionSet, childType, ctx, onPath);
+
+        total += 1 + multiplierFor(selection, unwrapped?.isArray ?? false, ctx) * children;
+        break;
+      }
+
+      case Kind.FRAGMENT_SPREAD: {
+        total += costOfFragment(selection.name.value, ctx, onPath);
+        break;
+      }
+
+      case Kind.INLINE_FRAGMENT: {
+        const condition = selection.typeCondition
+          ? objectTypeNamed(ctx.schema, selection.typeCondition.name.value)
+          : parentType;
+
+        total += costOfSelectionSet(selection.selectionSet, condition, ctx, onPath);
+        break;
+      }
+    }
+  }
+
+  return total;
+};
+
+const rootTypeFor = (
+  schema: GraphQLSchema,
+  operation: OperationDefinitionNode,
+): GraphQLObjectType | undefined => {
+  switch (operation.operation) {
+    case "mutation":
+      return schema.getMutationType() ?? undefined;
+    case "subscription":
+      return schema.getSubscriptionType() ?? undefined;
+    default:
+      return schema.getQueryType() ?? undefined;
+  }
+};
+
+const costliestOperation = (
+  document: DocumentNode,
+  schema: GraphQLSchema,
+  variables: Record<string, unknown>,
+  pageLimits: CostPageLimits,
+): { cost: number; operation: OperationDefinitionNode | undefined } => {
+  const ctx: WalkContext = {
+    schema,
+    variables,
+    pageLimits,
+    fragments: collectFragments(document),
+    fragmentCosts: new Map(),
+  };
+
+  let worst: { cost: number; operation: OperationDefinitionNode | undefined } = {
+    cost: 0,
+    operation: undefined,
+  };
+
+  for (const definition of document.definitions) {
+    if (definition.kind !== Kind.OPERATION_DEFINITION) continue;
+
+    const cost = costOfSelectionSet(
+      definition.selectionSet,
+      rootTypeFor(schema, definition),
+      ctx,
+      new Set<string>(),
+    );
+
+    if (cost > worst.cost || worst.operation === undefined) {
+      worst = { cost, operation: definition };
+    }
+  }
+
+  return worst;
+};
+
+/**
+ * Estimate how many rows a document asks a database for, before executing it.
+ *
+ * Every field costs 1 for itself plus the cost of its children multiplied by the
+ * page size it requests — the `limit` argument for a list field, resolved through
+ * `variables`, falling back to `defaultPageSize`; 1 for anything that returns a
+ * single row. Fragment spreads are expanded, so moving a fan-out into a fragment
+ * does not hide it.
+ *
+ * A document carrying several operations is scored by its most expensive one:
+ * a request executes one of them.
+ */
+export const estimateQueryCost = (
+  document: DocumentNode,
+  schema: GraphQLSchema,
+  variables: Record<string, unknown>,
+  pageLimits: CostPageLimits,
+): number => costliestOperation(document, schema, variables, pageLimits).cost;
+
+/**
+ * Reject a document whose estimated cost exceeds `maxCost`. Returns `null` when
+ * it is within budget.
+ */
+export const checkQueryCost = (
+  document: DocumentNode,
+  schema: GraphQLSchema,
+  variables: Record<string, unknown>,
+  pageLimits: CostPageLimits,
+  maxCost: number,
+): GraphQLError | null => {
+  const { cost, operation } = costliestOperation(document, schema, variables, pageLimits);
+
+  if (cost <= maxCost) return null;
+
+  const operationName = operation?.name?.value ?? "anonymous";
+
+  return new GraphQLError(
+    `Estimated query cost of ${cost} exceeds the maximum allowed cost of ${maxCost} (operation: "${operationName}"). Raise MAX_QUERY_COST to allow more expensive queries.`,
+    { nodes: operation ? [operation] : undefined },
+  );
+};

package/src/analyzeQuery/depthLimit.ts

@@ -1,12 +1,8 @@
 import { GraphQLError, Kind } from "graphql";
 
-import type {
-  ASTNode,
-  ASTVisitor,
-  DocumentNode,
-  FragmentDefinitionNode,
-  ValidationContext,
-} from "graphql";
+import type { ASTNode, ASTVisitor, FragmentDefinitionNode, ValidationContext } from "graphql";
+
+import { collectFragments } from "./fragments";
 
 /**
  * Compute the depth of a selection set, resolving fragment spreads.
@@ -68,21 +64,6 @@ function computeDepth(
   return max;
 }
 
-/**
- * Collect all fragment definitions from a document.
- */
-function collectFragments(document: DocumentNode): Map<string, FragmentDefinitionNode> {
-  const fragments = new Map<string, FragmentDefinitionNode>();
-
-  for (const def of document.definitions) {
-    if (def.kind === Kind.FRAGMENT_DEFINITION) {
-      fragments.set(def.name.value, def);
-    }
-  }
-
-  return fragments;
-}
-
 /**
  * GraphQL validation rule that rejects queries exceeding a maximum nesting depth.
  *
@@ -113,7 +94,7 @@ export const depthLimitRule =
 
             context.reportError(
               new GraphQLError(
-                `Query depth of ${depth} exceeds the maximum allowed depth of ${maxDepth} (operation: "${operationName}")`,
+                `Query depth of ${depth} exceeds the maximum allowed depth of ${maxDepth} (operation: "${operationName}"). Raise MAX_QUERY_DEPTH to allow deeper queries.`,
                 { nodes: [def] },
               ),
             );

package/src/analyzeQuery/fragments.ts

@@ -0,0 +1,18 @@
+import { Kind } from "graphql";
+
+import type { DocumentNode, FragmentDefinitionNode } from "graphql";
+
+/**
+ * Collect all fragment definitions from a document.
+ */
+export const collectFragments = (document: DocumentNode): Map<string, FragmentDefinitionNode> => {
+  const fragments = new Map<string, FragmentDefinitionNode>();
+
+  for (const def of document.definitions) {
+    if (def.kind === Kind.FRAGMENT_DEFINITION) {
+      fragments.set(def.name.value, def);
+    }
+  }
+
+  return fragments;
+};

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 };