🔑 feat: Bind Agent API Keys to Source Authority (#17597)

* 🔑 feat: Bind Agent API Keys to Source Authority

* fix: isolate bound key digests and fence owner issuance

* fix: redact grant authorization failures and type owner lookup

* refactor: separate bound grant validation from personal-key authentication

* test: Drain Concurrent Key Creation and Erasure Before Teardown

* test: Observe and Drain Concurrent Fixture Work
This commit is contained in:
Dustin Healy 2026-11-10 21:03:58 -08:00 • committed by GitHub
parent 7212fd6229
commit 24b0a74ead
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 395 additions and 19 deletions

View file

@ -0,0 +1,53 @@
import express from 'express';
import request from 'supertest';
import mongoose from 'mongoose';
import { MongoMemoryReplSet } from 'mongodb-memory-server';
import { createModels, createMethods } from '@librechat/data-schemas';
import type { ApiKeyAuthRequest } from './middleware';
import { createRequireApiKeyAuth } from './middleware';
let mongo: MongoMemoryReplSet;
let methods: ReturnType<typeof createMethods>;
beforeAll(async () => {
mongo = await MongoMemoryReplSet.create({ replSet: { count: 1 } });
await mongoose.connect(mongo.getUri(), { autoIndex: false });
createModels(mongoose);
methods = createMethods(mongoose);
});
afterAll(async () => {
await mongoose.disconnect();
await mongo?.stop();
});
it('keeps ordinary HTTP authentication working while bound grants require their separate validator', async () => {
const user = await mongoose.models.User.create({
email: 'key-owner@example.com',
provider: 'openid',
});
const userId = String(user._id);
const ordinary = await methods.createAgentApiKey({ userId, name: 'ordinary' });
const binding = { kind: 'grant', id: 'source-authority' };
const bound = await methods.createAgentApiKey({ userId, name: 'bound', binding });
const app = express();
const authenticate = createRequireApiKeyAuth({
validateAgentApiKey: methods.validateAgentApiKey,
findUser: methods.findUser,
isPrincipalActive: methods.isAgentTriggerPrincipalActive,
});
app.get(
'/',
async (req, res, next) => {
await authenticate(req as ApiKeyAuthRequest, res, next);
},
(_req, res) => {
res.status(200).end();
},
);
expect((await request(app).get('/').auth(ordinary.key, { type: 'bearer' })).status).toBe(200);
const rejected = await request(app).get('/').auth(bound.key, { type: 'bearer' });
expect(rejected.status).toBe(401);
expect(rejected.body.error.code).toBe('invalid_api_key');
expect(await methods.validateBoundAgentApiKey(bound.key)).toMatchObject({ binding });
expect(await methods.validateBoundAgentApiKey(ordinary.key)).toBeNull();
});

View file

@ -1,15 +1,19 @@
import mongoose from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { MongoMemoryReplSet } from 'mongodb-memory-server';
import { createAgentApiKeyMethods } from './agentApiKey';
import { runAsSystem } from '~/config/tenantContext';
import { waitForPause } from './test-helpers';
import { createUserMethods } from './user';
import { createModels } from '~/models';
import { hashToken } from '~/crypto';
let mongoServer: MongoMemoryServer;
let mongoServer: MongoMemoryReplSet;
let methods: ReturnType<typeof createAgentApiKeyMethods>;
const userId = new mongoose.Types.ObjectId();
beforeAll(async () => {
mongoServer = await MongoMemoryServer.create();
await mongoose.connect(mongoServer.getUri());
mongoServer = await MongoMemoryReplSet.create({ replSet: { count: 1 } });
await mongoose.connect(mongoServer.getUri(), { autoIndex: false });
createModels(mongoose);
methods = createAgentApiKeyMethods(mongoose);
});
@ -24,6 +28,92 @@ afterEach(() => {
});
describe('validateAgentApiKey', () => {
const binding = { kind: 'test-grant', id: 'grant-1' };
it('persists and returns the exact bound grant with a domain-separated hash', async () => {
const created = await methods.createAgentApiKey({ userId, name: 'bound', binding });
const stored = await mongoose.models.AgentApiKey.findById(created.id)
.select('+keyHash')
.lean<{ keyHash: string } | null>();
expect(created.key).toMatch(/^sk-bound-[a-f0-9]{64}$/);
expect(stored?.keyHash).toBe(`bound-v1:${await hashToken(`bound:${created.key}`)}`);
expect(stored?.keyHash).not.toBe(await hashToken(created.key));
expect(
await mongoose.models.AgentApiKey.findOne({ keyHash: await hashToken(created.key) }),
).toBeNull();
expect(await methods.validateAgentApiKey(created.key)).toBeNull();
expect(await methods.validateBoundAgentApiKey(created.key)).toEqual({
userId,
keyId: new mongoose.Types.ObjectId(created.id),
binding,
});
expect(await methods.getAgentApiKeyById(created.id, userId)).toEqual(
expect.objectContaining({ binding }),
);
});
it('keeps ordinary keys compatible with the existing raw-token hash', async () => {
const created = await methods.createAgentApiKey({ userId, name: 'ordinary' });
const stored = await mongoose.models.AgentApiKey.findById(created.id)
.select('+keyHash')
.lean<{ keyHash: string } | null>();
expect(created.key).toMatch(/^sk-[a-f0-9]{64}$/);
expect(stored?.keyHash).toBe(await hashToken(created.key));
expect(await methods.validateAgentApiKey(created.key)).toEqual({
userId,
keyId: new mongoose.Types.ObjectId(created.id),
});
expect(await methods.validateBoundAgentApiKey(created.key)).toBeNull();
});
it('rejects a bound-prefix token when its stored grant is missing', async () => {
const created = await methods.createAgentApiKey({ userId, name: 'missing-binding', binding });
// Seed an inconsistent stored row without bypassing the validator under test.
await mongoose.models.AgentApiKey.collection.updateOne(
{ _id: new mongoose.Types.ObjectId(created.id) },
{ $unset: { binding: 1 } },
);
await expect(methods.validateAgentApiKey(created.key)).resolves.toBeNull();
await expect(methods.validateBoundAgentApiKey(created.key)).resolves.toBeNull();
});
it('rejects an ordinary-prefix token with a stored binding', async () => {
const created = await methods.createAgentApiKey({ userId, name: 'wrong-prefix' });
await mongoose.models.AgentApiKey.collection.updateOne(
{ _id: new mongoose.Types.ObjectId(created.id) },
{ $set: { binding } },
);
await expect(methods.validateAgentApiKey(created.key)).resolves.toBeNull();
await expect(methods.validateBoundAgentApiKey(created.key)).resolves.toBeNull();
});
it.each([false, true])('rejects expired keys (bound=%s)', async (bound) => {
const created = await methods.createAgentApiKey({
userId,
name: `expired-${bound}`,
expiresAt: new Date(Date.now() - 60_000),
...(bound ? { binding } : {}),
});
await expect(methods.validateAgentApiKey(created.key)).resolves.toBeNull();
await expect(methods.validateBoundAgentApiKey(created.key)).resolves.toBeNull();
});
it('propagates a bound-key lookup failure instead of treating it as absence', async () => {
const created = await methods.createAgentApiKey({ userId, name: 'lookup-failure', binding });
jest.spyOn(mongoose.models.AgentApiKey, 'findOne').mockImplementation(() => {
throw new Error('bound lookup unavailable');
});
await expect(methods.validateBoundAgentApiKey(created.key)).rejects.toThrow(
'bound lookup unavailable',
);
});
it('resolves the owner of a stored key', async () => {
const { key } = await methods.createAgentApiKey({ userId, name: 'remote' });
@ -44,3 +134,104 @@ describe('validateAgentApiKey', () => {
await expect(methods.validateAgentApiKey('lc-any')).rejects.toThrow('connection reset');
});
});
it('keeps every attacker-chosen public wrapper outside the legacy validator digest namespace', async () => {
const created = await methods.createAgentApiKey({
userId,
name: 'legacy-namespace',
binding: { kind: 'grant', id: 'one' },
});
const legacyLookup = async (token: string) =>
mongoose.models.AgentApiKey.findOne({ keyHash: await hashToken(token) }).lean();
for (const token of [
created.key,
`bound:${created.key}`,
`bound-v1:${created.key}`,
`bound:bound:${created.key}`,
]) {
expect(await legacyLookup(token)).toBeNull();
if (token !== created.key) expect(await methods.validateAgentApiKey(token)).toBeNull();
}
const ordinary = await methods.createAgentApiKey({ userId, name: 'legacy-control' });
expect(await legacyLookup(ordinary.key)).not.toBeNull();
expect(await methods.validateAgentApiKey(created.key)).toBeNull();
expect(await methods.validateBoundAgentApiKey(created.key)).toMatchObject({
binding: { id: 'one' },
});
});
it('serializes bound-key creation with final account erasure', async () => {
const user = await mongoose.models.User.create({
email: 'bound-key-owner@example.com',
provider: 'local',
});
const ownerId = String(user._id);
let entered!: () => void;
let release!: () => void;
const started = new Promise<void>((resolve) => {
entered = resolve;
});
const gate = new Promise<void>((resolve) => {
release = resolve;
});
const collection = mongoose.models.AgentApiKey.collection;
const insert = collection.insertOne.bind(collection);
const paused = jest.spyOn(collection, 'insertOne').mockImplementation(async (...args) => {
entered();
await gate;
return insert(...args);
});
const creating = methods.createAgentApiKey({
userId: ownerId,
name: 'in-flight',
binding: { kind: 'grant', id: 'one' },
});
await waitForPause(started, creating);
let deleted = false;
const deleting = createUserMethods(mongoose)
.deleteUserById(ownerId)
.then((value) => {
deleted = true;
return value;
});
const drained = Promise.allSettled([creating, deleting]);
try {
await new Promise((resolve) => setTimeout(resolve, 50));
expect(deleted).toBe(false);
} finally {
release();
paused.mockRestore();
await drained;
}
const [created] = await Promise.all([creating, deleting]);
expect(await methods.validateAgentApiKey(created.key)).toBeNull();
expect(await methods.validateBoundAgentApiKey(created.key)).toBeNull();
expect(await mongoose.models.AgentApiKey.exists({ userId: user._id })).toBeNull();
await expect(
methods.createAgentApiKey({
userId: ownerId,
name: 'late',
binding: { kind: 'grant', id: 'one' },
}),
).rejects.toThrow('owner unavailable');
});
it('uses the real owner partition when a system operation issues a bound grant', async () => {
const user = await runAsSystem(async () =>
mongoose.models.User.create({
email: 'system-bound-key-owner@example.com',
provider: 'local',
tenantId: 'owner-tenant',
}),
);
const created = await runAsSystem(async () =>
methods.createAgentApiKey({
userId: String(user._id),
name: 'system-grant',
binding: { kind: 'grant', id: 'one' },
}),
);
expect(
await runAsSystem(async () => mongoose.models.AgentApiKey.findById(created.id).lean()),
).toMatchObject({ tenantId: 'owner-tenant' });
});

View file

@ -0,0 +1,26 @@
import mongoose from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { createAgentApiKeyMethods } from './agentApiKey';
import { createModels } from '~/models';
import { hashToken } from '~/crypto';
let server: MongoMemoryServer;
beforeAll(async () => {
server = await MongoMemoryServer.create();
await mongoose.connect(server.getUri());
createModels(mongoose);
});
afterAll(async () => {
await mongoose.disconnect();
await server?.stop();
});
it('preserves ordinary key issuance and the legacy hash on standalone MongoDB', async () => {
const methods = createAgentApiKeyMethods(mongoose);
const userId = new mongoose.Types.ObjectId();
const created = await methods.createAgentApiKey({ userId, name: 'ordinary' });
expect(await methods.validateAgentApiKey(created.key)).toMatchObject({ userId });
expect(
await mongoose.models.AgentApiKey.findOne({ keyHash: await hashToken(created.key) }).lean(),
).not.toBeNull();
});

View file

@ -1,21 +1,39 @@
import type { ClientSession } from 'mongoose';
import type { Types } from 'mongoose';
import type {
AgentApiKeyCreateResult,
AgentApiKeyCreateData,
AgentApiKeyListItem,
IAgentApiKey,
AgentApiKeyBinding,
} from '~/types';
import { getTenantId, SYSTEM_TENANT_ID } from '~/config/tenantContext';
import { prepareChannelOwnerAdmission } from './channelOwner';
import { createChannelIndexGate } from './channelIndexes';
import { hashToken, getRandomValues } from '~/crypto';
import logger from '~/config/winston';
const API_KEY_PREFIX = 'sk-';
const API_KEY_LENGTH = 32;
async function keyDigest(key: string, bound: boolean): Promise<string> {
const digest = await hashToken(bound ? `bound:${key}` : key);
// Legacy validators produce only hex digests, even for attacker-chosen wrappers.
return bound ? `bound-v1:${digest}` : digest;
}
export function createAgentApiKeyMethods(mongoose: typeof import('mongoose')): {
createAgentApiKey: (data: AgentApiKeyCreateData) => Promise<AgentApiKeyCreateResult>;
validateAgentApiKey: (
apiKey: string,
) => Promise<{ userId: Types.ObjectId; keyId: Types.ObjectId } | null>;
validateAgentApiKey: (apiKey: string) => Promise<{
userId: Types.ObjectId;
keyId: Types.ObjectId;
} | null>;
/** Private grant lookup; its caller must authorize the binding before authentication. */
validateBoundAgentApiKey: (apiKey: string) => Promise<{
userId: Types.ObjectId;
keyId: Types.ObjectId;
binding: AgentApiKeyBinding;
} | null>;
listAgentApiKeys: (userId: string | Types.ObjectId) => Promise<AgentApiKeyListItem[]>;
deleteAgentApiKey: (
keyId: string | Types.ObjectId,
@ -27,29 +45,65 @@ export function createAgentApiKeyMethods(mongoose: typeof import('mongoose')): {
userId: string | Types.ObjectId,
) => Promise<AgentApiKeyListItem | null>;
} {
async function generateApiKey(): Promise<{ key: string; keyHash: string; keyPrefix: string }> {
const ensureBoundKeyIndexes = createChannelIndexGate(() => [mongoose.models.AgentApiKey]);
async function generateApiKey(
bound: boolean,
): Promise<{ key: string; keyHash: string; keyPrefix: string }> {
const randomPart = await getRandomValues(API_KEY_LENGTH);
const key = `${API_KEY_PREFIX}${randomPart}`;
const keyHash = await hashToken(key);
const keyPrefix = key.slice(0, 8);
const key = `${bound ? 'sk-bound-' : API_KEY_PREFIX}${randomPart}`;
const keyHash = await keyDigest(key, bound);
const keyPrefix = key.slice(0, bound ? 16 : 8);
return { key, keyHash, keyPrefix };
}
async function createAgentApiKey(data: AgentApiKeyCreateData): Promise<AgentApiKeyCreateResult> {
try {
const AgentApiKey = mongoose.models.AgentApiKey;
const { key, keyHash, keyPrefix } = await generateApiKey();
const { key, keyHash, keyPrefix } = await generateApiKey(data.binding != null);
const apiKeyDoc = await AgentApiKey.create({
let tenantId = getTenantId();
if (data.binding && tenantId === SYSTEM_TENANT_ID) {
const owner = await mongoose.models.User.findById(data.userId)
.select('tenantId')
.lean<{ tenantId?: string } | null>();
if (!owner) throw new Error('Bound-key owner unavailable');
tenantId = owner.tenantId || undefined;
}
const record = {
userId: data.userId,
name: data.name,
keyHash,
keyPrefix,
expiresAt: data.expiresAt || undefined,
});
...(data.binding ? { binding: data.binding } : {}),
...(data.binding && tenantId ? { tenantId } : {}),
};
const persist = async (session?: ClientSession): Promise<IAgentApiKey> => {
const [created] = await AgentApiKey.create([record], session ? { session } : {});
return created;
};
let apiKeyDoc: IAgentApiKey;
if (data.binding) {
await ensureBoundKeyIndexes();
const admit = await prepareChannelOwnerAdmission(mongoose, {
userId: String(data.userId),
tenantId,
});
const session = await mongoose.startSession();
try {
const created = await session.withTransaction(async () => {
if (!(await admit(session))) throw new Error('Bound-key owner unavailable');
return persist(session);
});
if (!created) throw new Error('Bound-key write did not commit');
apiKeyDoc = created;
} finally {
await session.endSession();
}
} else apiKeyDoc = await persist();
return {
id: apiKeyDoc._id.toString(),
id: String(apiKeyDoc._id),
name: apiKeyDoc.name,
keyPrefix,
key,
@ -62,17 +116,20 @@ export function createAgentApiKeyMethods(mongoose: typeof import('mongoose')): {
}
}
async function validateAgentApiKey(
apiKey: string,
): Promise<{ userId: Types.ObjectId; keyId: Types.ObjectId } | null> {
async function lookupKey(apiKey: string): Promise<{
userId: Types.ObjectId;
keyId: Types.ObjectId;
binding?: AgentApiKeyBinding;
} | null> {
const AgentApiKey = mongoose.models.AgentApiKey;
const keyHash = await hashToken(apiKey);
const keyHash = await keyDigest(apiKey, apiKey.startsWith('sk-bound-'));
const keyDoc = (await AgentApiKey.findOne({ keyHash }).lean()) as IAgentApiKey | null;
if (!keyDoc) {
return null;
}
if (apiKey.startsWith('sk-bound-') !== (keyDoc.binding != null)) return null;
if (keyDoc.expiresAt && new Date(keyDoc.expiresAt) < new Date()) {
return null;
@ -87,9 +144,30 @@ export function createAgentApiKeyMethods(mongoose: typeof import('mongoose')): {
return {
userId: keyDoc.userId,
keyId: keyDoc._id as Types.ObjectId,
...(keyDoc.binding ? { binding: keyDoc.binding } : {}),
};
}
/** Ordinary production authentication never accepts a source-bound credential. */
async function validateAgentApiKey(apiKey: string): Promise<{
userId: Types.ObjectId;
keyId: Types.ObjectId;
} | null> {
if (apiKey.startsWith('sk-bound-')) return null;
const key = await lookupKey(apiKey);
return key ? { userId: key.userId, keyId: key.keyId } : null;
}
async function validateBoundAgentApiKey(apiKey: string): Promise<{
userId: Types.ObjectId;
keyId: Types.ObjectId;
binding: AgentApiKeyBinding;
} | null> {
if (!apiKey.startsWith('sk-bound-')) return null;
const key = await lookupKey(apiKey);
return key?.binding ? { userId: key.userId, keyId: key.keyId, binding: key.binding } : null;
}
async function listAgentApiKeys(userId: string | Types.ObjectId): Promise<AgentApiKeyListItem[]> {
try {
const AgentApiKey = mongoose.models.AgentApiKey;
@ -158,6 +236,7 @@ export function createAgentApiKeyMethods(mongoose: typeof import('mongoose')): {
lastUsedAt: keyDoc.lastUsedAt,
expiresAt: keyDoc.expiresAt,
createdAt: keyDoc.createdAt,
...(keyDoc.binding ? { binding: keyDoc.binding } : {}),
};
} catch (error) {
logger.error('[getAgentApiKeyById] Error getting API key:', error);
@ -168,6 +247,7 @@ export function createAgentApiKeyMethods(mongoose: typeof import('mongoose')): {
return {
createAgentApiKey,
validateAgentApiKey,
validateBoundAgentApiKey,
listAgentApiKeys,
deleteAgentApiKey,
deleteAllAgentApiKeys,

View file

@ -4,6 +4,7 @@ import type { ResponseOwner } from '~/models/response';
import { createAgentChannelModel, createAgentChannelThreadModel } from '~/models/channel';
import { createChannelRunModel, createChannelLaneModel } from '~/models/channelRun';
import { createChannelIdentityModel } from '~/models/channelIdentity';
import { createAgentApiKeyModel } from '~/models/agentApiKey';
import { createIndexesWithRetry } from '~/utils/retry';
import { retireAgentChannel } from './channelScope';
@ -22,6 +23,10 @@ export async function eraseChannelPersistenceForUser(
): Promise<void> {
const { erasureBatchSize } = resolveChannelErasureConfig(options);
const tenantId = owner.tenantId || '_';
await createAgentApiKeyModel(mongoose).deleteMany({
userId: owner.userId,
tenantId: owner.tenantId || { $in: [null, ''] },
});
const runs = createChannelRunModel(mongoose);
const lanes = createChannelLaneModel(mongoose);
const filter = { tenantId, 'principal.userId': owner.userId };

View file

@ -1,6 +1,8 @@
import mongoose, { Schema, Document, Types } from 'mongoose';
import type { AgentApiKeyBinding } from '~/types/agentApiKey';
export interface IAgentApiKey extends Document {
binding?: AgentApiKeyBinding;
userId: Types.ObjectId;
name: string;
keyHash: string;
@ -14,6 +16,16 @@ export interface IAgentApiKey extends Document {
const agentApiKeySchema: Schema<IAgentApiKey> = new Schema(
{
binding: {
type: new Schema<AgentApiKeyBinding>(
{
kind: { type: String, required: true, maxlength: 64 },
id: { type: String, required: true, maxlength: 256 },
},
{ _id: false },
),
immutable: true,
},
userId: {
type: mongoose.Schema.Types.ObjectId,
ref: 'User',

View file

@ -1,6 +1,13 @@
import { Document, Types } from 'mongoose';
/** Server-only integration grant; a bound key is never an unrestricted personal key. */
export interface AgentApiKeyBinding {
kind: string;
id: string;
}
export interface IAgentApiKey extends Document {
binding?: AgentApiKeyBinding;
userId: Types.ObjectId;
name: string;
keyHash: string;
@ -13,6 +20,7 @@ export interface IAgentApiKey extends Document {
}
export interface AgentApiKeyCreateData {
binding?: AgentApiKeyBinding;
userId: Types.ObjectId | string;
name: string;
expiresAt?: Date | null;
@ -28,6 +36,7 @@ export interface AgentApiKeyCreateResult {
}
export interface AgentApiKeyListItem {
binding?: AgentApiKeyBinding;
id: string;
name: string;
keyPrefix: string;