Auth logging

Blueprint's shared auth module includes a logging system that lets you control the verbosity of authentication-related logs. This is particularly useful for debugging and monitoring authentication flows in your application.

Configuring log levels

Set the log level by defining the BP_AUTH_LOG_LEVEL environment variable in your application's environment. The available log levels are:

• NONE: No logs will be emitted.
• ERROR: Only error messages will be logged.
• WARN: Warnings and error messages will be logged.
• INFO: Informational messages, warnings, and error messages will be logged.
• DEBUG: All messages, including debug information, will be logged.

By default, the log level is set to INFO, which means that INFO, WARN, and ERROR messages will be logged since they are of higher severity.

Custom GraphQL error severity

createGraphQLHandler converts failed Kraken GraphQL requests into auth log entries. If some GraphQL failures are expected business outcomes for your application, use customization.getGraphQLErrorLogLevel to choose the log severity for each failure.

import { BlueprintAuthErrorCode } from "@krakentech/blueprint-auth";
import { createGraphQLHandler } from "@krakentech/blueprint-auth/server";

export default createGraphQLHandler({
  customization: {
    getGraphQLErrorLogLevel({ errorCode, cause }) {
      const messages = Array.isArray(cause)
        ? cause.map((krakenError) => krakenError?.message)
        : [];
      const isExpectedMeterPointOutcome =
        errorCode === BlueprintAuthErrorCode.OperationGraphQLUnknown &&
        messages.some((message) =>
          ["No meter point found", "Several meter points were found"].includes(
            message
          )
        );

      return isExpectedMeterPointOutcome ? "warn" : "error";
    },
  },
  krakenConfig: {
    graphqlAuthEndpoint: process.env.KRAKEN_GRAPHQL_AUTH_ENDPOINT,
    graphqlEndpoint: process.env.KRAKEN_GRAPHQL_ENDPOINT,
    xClientIpSecretKey: process.env.KRAKEN_X_CLIENT_IP_SECRET_KEY,
  },
  validation: {
    allowedRequestOrigins: ["https://www.example.com"],
  },
});

The callback receives { message, errorCode, cause, source }. cause holds whatever triggered the failure — for Kraken GraphQL errors this is the array of Kraken errors returned by the API, so narrow it (e.g. with Array.isArray) to inspect individual error messages. If the callback throws, or returns a value that isn't a recognised log level, the failure is logged as error by default.