diff --git a/packages/api/src/apiKeys/middleware.bound.spec.ts b/packages/api/src/apiKeys/middleware.bound.spec.ts new file mode 100644 index 0000000000..aadc2ae15f --- /dev/null +++ b/packages/api/src/apiKeys/middleware.bound.spec.ts @@ -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; +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(); +}); diff --git a/packages/data-schemas/src/methods/agentApiKey.spec.ts b/packages/data-schemas/src/methods/agentApiKey.spec.ts index 1c1061ef16..98b5b077a7 100644 --- a/packages/data-schemas/src/methods/agentApiKey.spec.ts +++ b/packages/data-schemas/src/methods/agentApiKey.spec.ts @@ -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; 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((resolve) => { + entered = resolve; + }); + const gate = new Promise((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' }); +}); diff --git a/packages/data-schemas/src/methods/agentApiKey.standalone.spec.ts b/packages/data-schemas/src/methods/agentApiKey.standalone.spec.ts new file mode 100644 index 0000000000..6c3fb3c67f --- /dev/null +++ b/packages/data-schemas/src/methods/agentApiKey.standalone.spec.ts @@ -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(); +}); diff --git a/packages/data-schemas/src/methods/agentApiKey.ts b/packages/data-schemas/src/methods/agentApiKey.ts index 3bd29b1f4a..b3bac0773c 100644 --- a/packages/data-schemas/src/methods/agentApiKey.ts +++ b/packages/data-schemas/src/methods/agentApiKey.ts @@ -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 { + 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; - 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; deleteAgentApiKey: ( keyId: string | Types.ObjectId, @@ -27,29 +45,65 @@ export function createAgentApiKeyMethods(mongoose: typeof import('mongoose')): { userId: string | Types.ObjectId, ) => Promise; } { - 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 { 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 => { + 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 { 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, diff --git a/packages/data-schemas/src/methods/channelErasure.ts b/packages/data-schemas/src/methods/channelErasure.ts index fda9038df7..8cdbbf0225 100644 --- a/packages/data-schemas/src/methods/channelErasure.ts +++ b/packages/data-schemas/src/methods/channelErasure.ts @@ -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 { 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 }; diff --git a/packages/data-schemas/src/schema/agentApiKey.ts b/packages/data-schemas/src/schema/agentApiKey.ts index 50334f5f5c..66b19e16c3 100644 --- a/packages/data-schemas/src/schema/agentApiKey.ts +++ b/packages/data-schemas/src/schema/agentApiKey.ts @@ -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 = new Schema( { + binding: { + type: new Schema( + { + 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', diff --git a/packages/data-schemas/src/types/agentApiKey.ts b/packages/data-schemas/src/types/agentApiKey.ts index 7d8979f522..819e77d986 100644 --- a/packages/data-schemas/src/types/agentApiKey.ts +++ b/packages/data-schemas/src/types/agentApiKey.ts @@ -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;