🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
import { env } from "@/src/env.mjs";
import {
createShaHash,
deleteApiKeyFromDb,
formatSubmittedPublicKeyForLog,
recordIncrement,
verifySecretKey,
type AuthHeaderVerificationResult,
CachedApiKey,
OrgEnrichedApiKey,
logger,
instrumentAsync,
addUserToSpan,
invalidateCachedApiKeys as invalidateCachedApiKeysShared,
invalidateCachedOrgApiKeys as invalidateCachedOrgApiKeysShared,
invalidateCachedProjectApiKeys as invalidateCachedProjectApiKeysShared,
createApiKeyCacheKey,
API_KEY_NON_EXISTENT,
} from "@langfuse/shared/src/server";
import {
type PrismaClient,
type ApiKey,
type Prisma,
type ApiKeyScope,
} from "@langfuse/shared/src/db";
import { isPrismaException } from "@/src/utils/exceptions";
import { type Redis, type Cluster } from "ioredis";
import { getOrganizationPlanServerSide } from "@/src/features/entitlements/server/getPlan";
import { type z } from "zod";
import { CloudConfigSchema, isPlan, UnauthorizedError } from "@langfuse/shared";
import { isApiKeyExpired } from "@/src/features/apiKey/helpers/isApiKeyExpired";
type VerifyAuthHeaderOptions = {
allowInAppAgentKey?: boolean;
};
export class ApiAuthService {
prisma: PrismaClient;
redis: Redis | Cluster | null;
constructor(prisma: PrismaClient, redis: Redis | Cluster | null) {
this.prisma = prisma;
this.redis = redis;
}
// this function needs to be called, when the organisation is updated
// - when projects move across organisations, the orgId in the API key cache needs to be updated
// - when the plan of the org changes, the plan in the API key cache needs to be updated as well
async invalidateCachedApiKeys(apiKeys: ApiKey[], identifier: string) {
await invalidateCachedApiKeysShared(apiKeys, identifier, this.redis);
}
async invalidateCachedOrgApiKeys(orgId: string) {
await invalidateCachedOrgApiKeysShared(orgId, this.redis);
}
async invalidateCachedProjectApiKeys(projectId: string) {
await invalidateCachedProjectApiKeysShared(projectId, this.redis);
}
/**
* Deletes an API key from the database and invalidates it in Redis if available.
* @param id - The ID of the API key to delete.
* @param entityId - The ID of the entity (project or organization) to which the API key belongs.
* @param scope - The scope of the API key (either "PROJECT" or "ORGANIZATION").
*/
async deleteApiKey(id: string, entityId: string, scope: ApiKeyScope) {
return deleteApiKeyFromDb({
prisma: this.prisma,
id,
entityId,
scope,
redis: this.redis,
});
}
async verifyAuthHeaderAndReturnScope(
authHeader: string | undefined,
options: VerifyAuthHeaderOptions = {},
): Promise<AuthHeaderVerificationResult> {
const result: AuthHeaderVerificationResult = await instrumentAsync(
{ name: "api-auth-verify" },
async (span) => {
if (!authHeader) {
logger.debug("No authorization header");
return {
validKey: false,
error: "No authorization header",
};
}
try {
// Basic auth, full scope, needs secret key and public key
if (authHeader.startsWith("Basic ")) {
const { username: publicKey, password: secretKey } =
this.extractBasicAuthCredentials(authHeader);
const salt = env.SALT;
const hashFromProvidedKey = createShaHash(secretKey, salt);
// fetches by redis if available, fallback to postgres
// api key from redis does
const apiKey =
await this.fetchApiKeyAndAddToRedis(hashFromProvidedKey);
let finalApiKey = apiKey;
if (!apiKey || !apiKey.fastHashedSecretKey) {
const slowKey = await this.prisma.apiKey.findUnique({
where: { publicKey },
include: {
project: { include: { organization: true } },
organization: true,
},
});
if (!slowKey) {
logger.error(
`No key found for public key: ${formatSubmittedPublicKeyForLog(publicKey)}`,
);
if (this.redis) {
logger.info(
`No key found, storing ${API_KEY_NON_EXISTENT} in redis`,
);
await this.addApiKeyToRedis(
hashFromProvidedKey,
API_KEY_NON_EXISTENT,
);
}
throw new Error("Invalid credentials");
}
const isValid = await verifySecretKey(
secretKey,
slowKey.hashedSecretKey,
);
if (!isValid) {
logger.debug(
`Old key is invalid: ${formatSubmittedPublicKeyForLog(publicKey)}`,
);
throw new Error("Invalid credentials");
}
const shaKey = createShaHash(secretKey, salt);
await this.prisma.apiKey.update({
where: { publicKey },
data: {
fastHashedSecretKey: shaKey,
},
});
finalApiKey = this.convertToRedisRepresentation({
...slowKey,
fastHashedSecretKey: shaKey,
});
}
if (!finalApiKey) {
logger.info(
`No project id found for key: ${formatSubmittedPublicKeyForLog(publicKey)}`,
);
throw new Error("Invalid credentials");
}
if (isApiKeyExpired(finalApiKey.expiresAt)) {
logger.info(`Expired api key: ${finalApiKey.publicKey}`);
throw new UnauthorizedError("Invalid credentials");
}
const plan = finalApiKey.plan;
if (!isPlan(plan)) {
logger.error(`Invalid plan type for key: ${finalApiKey.plan}`);
throw new Error("Invalid credentials");
}
addUserToSpan(
{
projectId: finalApiKey.projectId ?? undefined,
orgId: finalApiKey.orgId,
plan,
apiKeyId: finalApiKey.id,
publicKey: finalApiKey.publicKey,
},
span,
);
const accessLevel =
finalApiKey.scope === "ORGANIZATION"
? ("organization" as const)
: ("project" as const);
// The API key is resolved via the hash of the secret key, so the
// submitted public key may not belong to it, e.g. after a partial
// credential rotation on the client.
if (publicKey !== finalApiKey.publicKey) {
logger.warn(
`Public key mismatch on basic auth: submitted public key ${formatSubmittedPublicKeyForLog(publicKey)} does not match public key ${finalApiKey.publicKey} of the API key resolved via the secret key (apiKeyId ${finalApiKey.id}, projectId ${finalApiKey.projectId}, orgId ${finalApiKey.orgId})`,
);
}
const result = {
validKey: true as const,
scope: {
projectId: finalApiKey.projectId,
accessLevel,
orgId: finalApiKey.orgId,
organizationCreatedAt: finalApiKey.organizationCreatedAt,
plan: plan,
rateLimitOverrides: finalApiKey.rateLimitOverrides ?? [],
apiKeyId: finalApiKey.id,
scope: finalApiKey.scope,
publicKey: finalApiKey.publicKey,
isIngestionSuspended: finalApiKey.isIngestionSuspended,
isInAppAgentKey: finalApiKey.isInAppAgentKey,
accessAuditLogEnabled:
finalApiKey.accessAuditLogEnabled ?? false,
},
};
return result;
}
// Bearer auth, limited scope, only needs public key
if (authHeader.startsWith("Bearer ")) {
const publicKey = authHeader.replace("Bearer ", "");
const dbKey = await this.findDbKeyOrThrow(publicKey);
if (dbKey.scope === "ORGANIZATION") {
throw new Error(
"Unauthorized: Cannot use organization key with bearer auth",
);
}
const {
orgId,
organizationCreatedAt,
cloudConfig,
cloudFreeTierUsageThresholdState,
accessAuditLogEnabled,
} = this.extractOrgIdAndCloudConfig(dbKey);
const plan = getOrganizationPlanServerSide(cloudConfig);
addUserToSpan(
{
projectId: dbKey.projectId ?? undefined,
orgId,
plan,
apiKeyId: dbKey.id,
publicKey: dbKey.publicKey,
},
span,
);
const result = {
validKey: true as const,
scope: {
projectId: dbKey.projectId,
accessLevel: "scores" as const,
orgId,
organizationCreatedAt: organizationCreatedAt.toISOString(),
plan,
rateLimitOverrides: cloudConfig?.rateLimitOverrides ?? [],
apiKeyId: dbKey.id,
scope: dbKey.scope,
publicKey,
isInAppAgentKey: dbKey.isInAppAgentKey,
isIngestionSuspended:
cloudFreeTierUsageThresholdState === "BLOCKED",
accessAuditLogEnabled,
},
};
return result;
}
} catch (error: unknown) {
logger.info(
`Error verifying auth header: ${error instanceof Error ? error.message : null}`,
error,
);
if (isPrismaException(error)) {
throw error;
}
return {
validKey: false,
error:
(error instanceof Error ? error.message : "Authorization error") +
". Confirm that you've configured the correct host.",
};
}
return {
validKey: false,
error: "Invalid authorization header",
};
},
);
if (
result.validKey &&
result.scope.isInAppAgentKey === true &&
options.allowInAppAgentKey !== true
) {
return {
validKey: false,
error:
"Access denied - in-app agent keys are not allowed for this endpoint",
};
}
return result;
}
private extractBasicAuthCredentials(basicAuthHeader: string): {
username: string;
password: string;
} {
const authValue = basicAuthHeader.split(" ")[1];
if (!authValue) throw new Error("Invalid authorization header");
const [username, password] = atob(authValue).split(":");
if (!username || !password) throw new Error("Invalid authorization header");
return { username, password };
}
private async findDbKeyOrThrow(publicKey: string) {
const dbKey = await this.prisma.apiKey.findUnique({
where: { publicKey },
include: {
project: { include: { organization: true } },
organization: true,
},
});
if (!dbKey) {
logger.info(
`No api key found for public key: ${formatSubmittedPublicKeyForLog(publicKey)}`,
);
throw new Error("Invalid public key");
}
if (isApiKeyExpired(dbKey.expiresAt)) {
logger.info(`Expired api key: ${dbKey.publicKey}`);
throw new UnauthorizedError("Invalid public key");
}
return dbKey;
}
private async fetchApiKeyAndAddToRedis(hash: string) {
// first get the API key from redis, this does not throw
const redisApiKey = await this.fetchApiKeyFromRedis(hash);
if (redisApiKey === API_KEY_NON_EXISTENT) {
recordIncrement("langfuse.api_key.cache_hit", 1);
throw new Error("Invalid credentials");
}
// if we found something, return the object.
if (redisApiKey) {
recordIncrement("langfuse.api_key.cache_hit", 1);
return redisApiKey;
}
recordIncrement("langfuse.api_key.cache_miss", 1);
// if redis not available or object not found, try the database
const apiKeyAndOrganisation = await this.prisma.apiKey.findUnique({
where: { fastHashedSecretKey: hash },
include: {
project: { include: { organization: true } },
organization: true,
},
});
// add the key to redis for future use if available, this does not throw
// only do so if the new hashkey exists already.
if (apiKeyAndOrganisation && apiKeyAndOrganisation.fastHashedSecretKey) {
const cachedApiKey = this.convertToRedisRepresentation(
apiKeyAndOrganisation,
);
await this.addApiKeyToRedis(hash, cachedApiKey);
}
return apiKeyAndOrganisation
? this.convertToRedisRepresentation(apiKeyAndOrganisation)
: null;
}
private async addApiKeyToRedis(
hash: string,
newApiKey: z.infer<typeof OrgEnrichedApiKey> | typeof API_KEY_NON_EXISTENT,
) {
if (!this.redis || env.LANGFUSE_CACHE_API_KEY_ENABLED !== "true") {
return;
}
try {
await this.redis.set(
createApiKeyCacheKey(hash),
JSON.stringify(newApiKey),
"EX",
env.LANGFUSE_CACHE_API_KEY_TTL_SECONDS, // redis API is in seconds
);
} catch (error: unknown) {
logger.error("Error adding key to redis", error);
}
}
private async fetchApiKeyFromRedis(hash: string) {
if (!this.redis || env.LANGFUSE_CACHE_API_KEY_ENABLED !== "true") {
return null;
}
try {
// A plain GET, not GETEX: an entry expires a fixed TTL after it was
// written, never a TTL after it was last read. A sliding TTL lets an entry
// that is still being read outlive the API key it caches, so a request
// that repopulates the cache while the key is being revoked could keep the
// revoked key valid for as long as its holder kept using it.
const redisApiKey = await this.redis.get(createApiKeyCacheKey(hash));
if (!redisApiKey) {
return null;
}
const parsedApiKey = CachedApiKey.safeParse(JSON.parse(redisApiKey));
if (parsedApiKey.success) {
return parsedApiKey.data;
}
if (!parsedApiKey.success) {
logger.error(
"Failed to parse API key from Redis, deleting existing key from cache",
parsedApiKey.error,
);
await this.redis.del(createApiKeyCacheKey(hash));
}
return null;
} catch (error: unknown) {
logger.error("Error fetching key from redis", error);
return null;
}
}
private extractOrgIdAndCloudConfig(
apiKeyAndOrganisation: ApiKey & {
project: {
id: string;
organization: {
id: string;
name: string;
createdAt: Date;
updatedAt: Date;
cloudConfig: Prisma.JsonValue;
cloudFreeTierUsageThresholdState: string | null;
accessAuditLogEnabled: boolean;
};
} | null;
} & {
organization: {
id: string;
name: string;
createdAt: Date;
updatedAt: Date;
cloudConfig: Prisma.JsonValue;
cloudFreeTierUsageThresholdState: string | null;
accessAuditLogEnabled: boolean;
} | null;
},
) {
const orgId =
apiKeyAndOrganisation.project?.organization.id ??
apiKeyAndOrganisation.organization?.id;
const organizationCreatedAt =
apiKeyAndOrganisation.project?.organization.createdAt ??
apiKeyAndOrganisation.organization?.createdAt;
const rawCloudConfig =
apiKeyAndOrganisation.project?.organization.cloudConfig ??
apiKeyAndOrganisation.organization?.cloudConfig;
const cloudFreeTierUsageThresholdState =
apiKeyAndOrganisation.project?.organization
.cloudFreeTierUsageThresholdState ??
apiKeyAndOrganisation.organization?.cloudFreeTierUsageThresholdState;
const accessAuditLogEnabled =
apiKeyAndOrganisation.project?.organization.accessAuditLogEnabled ??
apiKeyAndOrganisation.organization?.accessAuditLogEnabled ??
false;
if (!orgId || !organizationCreatedAt) {
logger.error(
`No organization found for key: ${apiKeyAndOrganisation.publicKey}`,
);
throw new Error("Invalid credentials: No organization found for key");
}
const cloudConfig = rawCloudConfig
? CloudConfigSchema.parse(rawCloudConfig)
: undefined;
return {
orgId,
organizationCreatedAt,
cloudConfig,
cloudFreeTierUsageThresholdState,
accessAuditLogEnabled,
};
}
/**
* Converts the API key and organization to a Redis representation.
* For project-scoped API keys, it includes the project ID and organization.
* For organization-scoped API keys, it includes only the organization.
* @param apiKeyAndOrganisation
*/
private convertToRedisRepresentation(
apiKeyAndOrganisation: ApiKey & {
project: {
id: string;
organization: {
id: string;
name: string;
createdAt: Date;
updatedAt: Date;
cloudConfig: Prisma.JsonValue;
cloudFreeTierUsageThresholdState: string | null;
accessAuditLogEnabled: boolean;
};
} | null;
} & {
organization: {
id: string;
name: string;
createdAt: Date;
updatedAt: Date;
cloudConfig: Prisma.JsonValue;
cloudFreeTierUsageThresholdState: string | null;
accessAuditLogEnabled: boolean;
} | null;
},
) {
const {
orgId,
organizationCreatedAt,
cloudConfig,
cloudFreeTierUsageThresholdState,
accessAuditLogEnabled,
} = this.extractOrgIdAndCloudConfig(apiKeyAndOrganisation);
const newApiKey = OrgEnrichedApiKey.parse({
...apiKeyAndOrganisation,
createdAt: apiKeyAndOrganisation.createdAt?.toISOString(),
expiresAt: apiKeyAndOrganisation.expiresAt?.toISOString() ?? null,
orgId,
organizationCreatedAt: organizationCreatedAt.toISOString(),
plan: getOrganizationPlanServerSide(cloudConfig),
rateLimitOverrides: cloudConfig?.rateLimitOverrides,
isIngestionSuspended: cloudFreeTierUsageThresholdState === "BLOCKED",
accessAuditLogEnabled,
});
if (!orgId) {
logger.error("No organization found for key");
throw new Error("Invalid credentials");
}
return newApiKey;
}
}