Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

refactor: Refactor access token usage for truefoundry apis (#867)

Chirag Jain59e41775900a
diff --git a/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts b/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts
index f34b0d730..adef757da 100644
--- a/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts
+++ b/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts
@@ -17,7 +17,7 @@ import { PostgresAgentStore } from '../db/postgres/agent-store/PostgresAgentStor
import type { Database } from '../db/postgres/types';
import { AGENT_DESCRIPTION_MAX_LENGTH } from '../schemas/agent';
import { captureCriticalException } from '../sentry';
-import { callerAccessToken, type ResolveAccessToken } from './accessToken';
+import { callerAccessToken, type ResolveServiceFoundryAuthorization } from './accessToken';
import {
TrueFoundryServiceFoundryServerClient,
type PutRemoteAgentInput,
@@ -78,7 +78,7 @@ function toPutRemoteAgentPayload({
export class TrueFoundryAgentStore implements IAgentStore<Transaction<Database>> {
readonly #inner: PostgresAgentStore;
readonly #client: TrueFoundryServiceFoundryServerClient;
- readonly #resolveAccessToken: ResolveAccessToken;
+ readonly #resolveAccessToken: ResolveServiceFoundryAuthorization;
readonly #db: Kysely<Database>;
constructor(input: {
diff --git a/packages/trueforge/src/truefoundry/TrueFoundryMcpServerStore.ts b/packages/trueforge/src/truefoundry/TrueFoundryMcpServerStore.ts
index 25553b72a..26d189cd2 100644
--- a/packages/trueforge/src/truefoundry/TrueFoundryMcpServerStore.ts
+++ b/packages/trueforge/src/truefoundry/TrueFoundryMcpServerStore.ts
@@ -20,7 +20,13 @@ import {
import type { TurnMetadata } from '../db/turnMetadata';
import type { OAuthClientRecord } from '../mcp/auth/types';
import { resolveMcpAuthStatus, type McpAuthStatus } from '../schemas/mcpServer';
-import { accessTokenForRequest, asTrueFoundryRequestContext, type ResolveAccessToken } from './accessToken';
+import {
+ accessTokenForRequest,
+ asTrueFoundryRequestContext,
+ gatewayHeaders,
+ type ResolveGatewayAuthorization,
+ type ResolveServiceFoundryAuthorization,
+} from './accessToken';
import { trueFoundryManaged } from './errors';
import { gatewayMetadataHeadersForTurn } from './gatewayMetadata';
import { resolveDefaultGatewayUrl } from './mapEnabledModels';
@@ -75,8 +81,8 @@ export function resolveAuthorizeRedirectURL(input: { returnTo?: string; publicBa
/** Read-only MCP registry for TrueFoundry mode (writes managed elsewhere). */
export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServerWithAuthStore<TTransaction> {
readonly #client: TrueFoundryMcpApiClient;
- readonly #asAgent: ResolveAccessToken;
- readonly #asUser: ResolveAccessToken;
+ readonly #resolveServiceFoundryAuthorization: ResolveServiceFoundryAuthorization;
+ readonly #resolveGatewayAuthorization: ResolveGatewayAuthorization;
readonly #subject: RequestSubject;
readonly #perServerHeaders: PerServerMcpHeaders;
#gatewayUrl: string | undefined;
@@ -96,8 +102,8 @@ export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServ
agent: input.agent,
logger: input.logger,
});
- this.#asAgent = tokens.asAgent;
- this.#asUser = tokens.asUser;
+ this.#resolveServiceFoundryAuthorization = tokens.resolveServiceFoundryAuthorization;
+ this.#resolveGatewayAuthorization = tokens.resolveGatewayAuthorization;
this.#subject = requestContext.subject;
this.#perServerHeaders = input.perServerHeaders ?? {};
}
@@ -109,10 +115,6 @@ export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServ
turnMetadata?: TurnMetadata;
}): RemoteMcpHeaders {
const { record, userRef, turnMetadata } = input;
- const headers = async (): Promise<Record<string, string>> => ({
- ...withoutAuthorization(this.#perServerHeaders[record.name]),
- Authorization: `Bearer ${await this.#asUser()}`,
- });
return async () => {
const status = await this.authorize({
tenant_id: record.tenant_id,
@@ -132,11 +134,13 @@ export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServ
},
};
}
- const invokeHeaders = await headers();
- if (turnMetadata === undefined) {
- return { headers: invokeHeaders };
- }
- return { headers: { ...invokeHeaders, ...gatewayMetadataHeadersForTurn(turnMetadata) } };
+ const authorization = await this.#resolveGatewayAuthorization();
+ const invokeHeaders = {
+ ...withoutAuthorization(this.#perServerHeaders[record.name]),
+ ...gatewayHeaders(authorization),
+ ...gatewayMetadataHeadersForTurn(turnMetadata),
+ };
+ return { headers: invokeHeaders };
};
}
@@ -146,7 +150,7 @@ export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServ
return [];
}
- const accessToken = await this.#asAgent();
+ const accessToken = await this.#resolveServiceFoundryAuthorization();
const [rows, gatewayUrl] = await Promise.all([
this.#client.listMcpServers({
accessToken,
@@ -159,7 +163,7 @@ export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServ
async getServer(input: GetMcpServerInput, transaction?: TTransaction): Promise<McpServerRecord | undefined> {
void transaction;
- const accessToken = await this.#asAgent();
+ const accessToken = await this.#resolveServiceFoundryAuthorization();
const [row, gatewayUrl] = await Promise.all([
this.#client.getMcpServerByName({ accessToken, name: input.name }),
this.#resolveGatewayUrl(),
@@ -221,10 +225,11 @@ export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServ
return out;
}
+ const gatewayAuthorization = await this.#resolveGatewayAuthorization();
out.set(
record.name,
await this.#client.getMcpAuthStatus({
- accessToken: await this.#asUser(),
+ accessToken: gatewayAuthorization.subjectToken,
mcpServerId: record.id,
subjectId: this.#subject.id,
subjectType: this.#subject.type,
@@ -240,8 +245,9 @@ export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServ
throw new McpServerNotFoundError(input.name);
}
const publicBaseUrl = await this.#client.getTenantControlPlaneUrl({ tenantName: input.tenant_id });
+ const gatewayAuthorization = await this.#resolveGatewayAuthorization();
return this.#client.getMcpAuthorize({
- accessToken: await this.#asUser(),
+ accessToken: gatewayAuthorization.subjectToken,
mcpServerId: record.id,
redirectURL: resolveAuthorizeRedirectURL({
publicBaseUrl,
@@ -256,8 +262,9 @@ export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServ
if (record === undefined) {
throw new McpServerNotFoundError(input.name);
}
+ const gatewayAuthorization = await this.#resolveGatewayAuthorization();
await this.#client.deleteMcpAuth({
- accessToken: await this.#asUser(),
+ accessToken: gatewayAuthorization.subjectToken,
mcpServerId: record.id,
subjectId: this.#subject.id,
subjectType: this.#subject.type,
@@ -267,7 +274,8 @@ export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServ
async #resolveGatewayUrl(): Promise<string> {
if (this.#gatewayUrl === undefined) {
- const installations = await this.#client.listGatewayInstallations(await this.#asAgent());
+ const accessToken = await this.#resolveServiceFoundryAuthorization();
+ const installations = await this.#client.listGatewayInstallations(accessToken);
this.#gatewayUrl = resolveDefaultGatewayUrl(installations);
}
return this.#gatewayUrl;
diff --git a/packages/trueforge/src/truefoundry/TrueFoundryModelProviderStore.ts b/packages/trueforge/src/truefoundry/TrueFoundryModelProviderStore.ts
index 3eede1b84..89536eb9c 100644
--- a/packages/trueforge/src/truefoundry/TrueFoundryModelProviderStore.ts
+++ b/packages/trueforge/src/truefoundry/TrueFoundryModelProviderStore.ts
@@ -13,7 +13,13 @@ import {
} from '../db/modelProviderStore';
import type { TurnMetadata } from '../db/turnMetadata';
import type { AvailableModel, ModelProviderManifest } from '../schemas/modelProvider';
-import { accessTokenForRequest, asTrueFoundryRequestContext, type ResolveAccessToken } from './accessToken';
+import {
+ accessTokenForRequest,
+ actorAuthorizationHeaders,
+ asTrueFoundryRequestContext,
+ type ResolveGatewayAuthorization,
+ type ResolveServiceFoundryAuthorization,
+} from './accessToken';
import { trueFoundryManaged } from './errors';
import { gatewayMetadataHeadersForTurn } from './gatewayMetadata';
import {
@@ -26,8 +32,8 @@ import { TrueFoundryServiceFoundryServerClient } from './TrueFoundryServiceFound
export class TrueFoundryModelProviderStore<TTransaction = never> implements IModelProviderStore<TTransaction> {
readonly #client: TrueFoundryServiceFoundryServerClient;
- readonly #asAgent: ResolveAccessToken;
- readonly #asUser: ResolveAccessToken;
+ readonly #resolveServiceFoundryAuthorization: ResolveServiceFoundryAuthorization;
+ readonly #resolveGatewayAuthorization: ResolveGatewayAuthorization;
constructor(input: {
client: TrueFoundryServiceFoundryServerClient;
@@ -42,8 +48,8 @@ export class TrueFoundryModelProviderStore<TTransaction = never> implements IMod
agent: input.agent,
logger: input.logger,
});
- this.#asAgent = tokens.asAgent;
- this.#asUser = tokens.asUser;
+ this.#resolveServiceFoundryAuthorization = tokens.resolveServiceFoundryAuthorization;
+ this.#resolveGatewayAuthorization = tokens.resolveGatewayAuthorization;
}
async listProviders(input: ListModelProvidersInput, transaction?: TTransaction): Promise<ModelProviderRecord[]> {
@@ -88,28 +94,32 @@ export class TrueFoundryModelProviderStore<TTransaction = never> implements IMod
return flattenProviderModels(await this.listProviders(input, transaction));
}
- resolveInvokeHeaders(input: {
+ async resolveInvokeHeaders(input: {
record: ModelProviderRecord;
turnMetadata?: TurnMetadata;
}): Promise<Record<string, string>> {
void input.record;
- if (input.turnMetadata === undefined) {
- return Promise.resolve({});
- }
- return Promise.resolve(gatewayMetadataHeadersForTurn(input.turnMetadata));
+ const authorization = await this.#resolveGatewayAuthorization();
+ return {
+ ...actorAuthorizationHeaders(authorization),
+ ...gatewayMetadataHeadersForTurn(input.turnMetadata),
+ };
}
async #records(input: {
tenant_id: string;
filter?: { provider_account_name: string; name: string };
}): Promise<ModelProviderRecord[]> {
- const [agentToken, userToken] = await Promise.all([this.#asAgent(), this.#asUser()]);
+ const [serviceFoundryAccessToken, gatewayAuthorization] = await Promise.all([
+ this.#resolveServiceFoundryAuthorization(),
+ this.#resolveGatewayAuthorization(),
+ ]);
const [integrations, installations] = await Promise.all([
this.#client.listProviderIntegrations({
- accessToken: agentToken,
+ accessToken: serviceFoundryAccessToken,
...(input.filter !== undefined ? { filter: input.filter } : {}),
}),
- this.#client.listGatewayInstallations(agentToken),
+ this.#client.listGatewayInstallations(serviceFoundryAccessToken),
]);
const gatewayUrl = resolveDefaultGatewayUrl(installations);
const models = filterEnvModels({
@@ -119,7 +129,7 @@ export class TrueFoundryModelProviderStore<TTransaction = never> implements IMod
return toRecords({
tenant_id: input.tenant_id,
gatewayUrl,
- accessToken: userToken,
+ accessToken: gatewayAuthorization.subjectToken,
models,
});
}
diff --git a/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts b/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts
index ab07a91b7..1526d7896 100644
--- a/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts
+++ b/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts
@@ -614,7 +614,7 @@ export class TrueFoundryServiceFoundryServerClient {
/**
* Exchange a TrueFoundry API key for dual agent-scoped tokens.
- * Wire `actorToken` is the agent identity (`asAgent`); wire `subjectToken` is the user with agent in `act` (`asUser`).
+ * Wire `actorToken` is the agent identity. Wire `subjectToken` is the user with the agent in `act`.
* Authenticated with the server API key, not the user bearer.
*/
async vendToken(input: {
diff --git a/packages/trueforge/src/truefoundry/TrueFoundrySkillStore.ts b/packages/trueforge/src/truefoundry/TrueFoundrySkillStore.ts
index 02c77725f..471b6b1b4 100644
--- a/packages/trueforge/src/truefoundry/TrueFoundrySkillStore.ts
+++ b/packages/trueforge/src/truefoundry/TrueFoundrySkillStore.ts
@@ -10,7 +10,7 @@ import type {
UpsertSkillInput,
} from '../db/skillStore';
import type { SkillVersion, TrueFoundryRegistrySkill } from '../schemas/skill';
-import { callerAccessToken, type ResolveAccessToken } from './accessToken';
+import { callerAccessToken, type ResolveServiceFoundryAuthorization } from './accessToken';
import { trueFoundryManaged } from './errors';
import {
mapSfyRegistrySkills,
@@ -110,7 +110,7 @@ export class TrueFoundrySkillStore<TTransaction = never>
implements ISkillStore<TTransaction>
{
readonly #client: TrueFoundrySkillApiClient;
- readonly #resolveAccessToken: ResolveAccessToken;
+ readonly #resolveAccessToken: ResolveServiceFoundryAuthorization;
constructor(input: { client: TrueFoundrySkillApiClient; context: RequestContext }) {
super(input);
diff --git a/packages/trueforge/src/truefoundry/accessToken.ts b/packages/trueforge/src/truefoundry/accessToken.ts
index 8f2d42ff4..982b4cbe3 100644
--- a/packages/trueforge/src/truefoundry/accessToken.ts
+++ b/packages/trueforge/src/truefoundry/accessToken.ts
@@ -5,20 +5,30 @@ import type { AgentRecord } from '../db/agentStore';
import { requireTrueFoundryAgentExternalId } from './errors';
import type { TrueFoundryServiceFoundryServerClient, VendedTokens } from './TrueFoundryServiceFoundryServerClient';
-/**
- * Token for one TrueFoundry call. Resolved on first use and reused for later calls on the same
- * callable.
- */
-export type ResolveAccessToken = () => Promise<string>;
+/** Token for one TrueFoundry call. Resolved on first use and reused for later calls on the same callable. */
+export type ResolveServiceFoundryAuthorization = () => Promise<string>;
+export type ResolveGatewayAuthorization = () => Promise<GatewayAuthorization>;
+export const ACTOR_AUTHORIZATION_HEADER = 'x-tfy-actor-authorization';
/**
- * Dual tokens from vend-token (or the caller credential when there is no saved agent).
- * - `asAgent` — agent identity (vend-token `actorToken`)
- * - `asUser` — triggering user with agent in `act` (vend-token `subjectToken`)
+ * Model gateway and MCP gateway invoke authorization.
+ * - caller — unsaved agent; authorization is the live caller token
+ * - delegated — saved agent with a caller token; actorAuthorization is vend actorToken
+ * - exchanged — saved agent with no caller token; authorization is vend subjectToken
*/
-export interface AccessTokens {
- asAgent: ResolveAccessToken;
- asUser: ResolveAccessToken;
+export type AuthorizationType = 'caller' | 'delegated' | 'exchanged';
+
+export interface GatewayAuthorization {
+ type: AuthorizationType;
+ subjectToken: string;
+ /** Set only for delegated. Do not send with exchanged: the subject token already carries the actor. */
+ actorAgentToken?: string;
+}
+
+export interface TrueFoundryAccess {
+ /** ServiceFoundry list/get. Saved agent: vend actorToken. Otherwise the caller token. */
+ resolveServiceFoundryAuthorization: ResolveServiceFoundryAuthorization;
+ resolveGatewayAuthorization: ResolveGatewayAuthorization;
}
type AgentTokenVendor = Pick<TrueFoundryServiceFoundryServerClient, 'vendToken'>;
@@ -31,7 +41,7 @@ const accessTokenCache: unique symbol = Symbol('truefoundryAccessTokenCache');
* lifetime of one HTTP request; a later request gets a new context and vends again.
*/
export type TrueFoundryRequestContext = RequestContext & {
- readonly [accessTokenCache]: Map<string, AccessTokens>;
+ readonly [accessTokenCache]: Map<string, TrueFoundryAccess>;
};
export function createTrueFoundryRequestContext(base: RequestContext): TrueFoundryRequestContext {
@@ -49,27 +59,31 @@ export function asTrueFoundryRequestContext(context: RequestContext): TrueFoundr
return context;
}
-function accessTokensFromCaller(context: RequestContext): AccessTokens {
+function callerAccess(context: RequestContext): TrueFoundryAccess {
const resolve = callerAccessToken(context);
- return { asAgent: resolve, asUser: resolve };
+ return {
+ resolveServiceFoundryAuthorization: resolve,
+ resolveGatewayAuthorization: async () => ({ type: 'caller', subjectToken: await resolve() }),
+ };
}
/**
- * Dual tokens scoped to a saved agent, for work the agent does on the caller's behalf.
+ * Saved-agent authorization. Vends once.
+ * Caller token present → delegated. Absent → exchanged (schedule creator on the subject).
* Throws 500 up front when the agent was never registered with TrueFoundry.
- * Vends once; callers pick `asAgent` or `asUser`.
*/
-export function agentAccessToken(input: {
+export function savedAgentAccess(input: {
client: AgentTokenVendor;
- requestContext: Pick<RequestContext, 'tenant_id' | 'subject'>;
+ requestContext: Pick<RequestContext, 'tenant_id' | 'subject' | 'user_credential'>;
agent: AgentRecord;
logger: Pick<Logger, 'info'>;
-}): AccessTokens {
+}): TrueFoundryAccess {
const { client, requestContext: context } = input;
const agentId = requireTrueFoundryAgentExternalId(input.agent);
+ const callerAuthorization = context.user_credential;
let pending: Promise<VendedTokens> | undefined;
- const vended = (): Promise<VendedTokens> => {
+ const vendToken = (): Promise<VendedTokens> => {
if (pending === undefined) {
input.logger.info('Exchanging user context for agent access token', {
subject: context.subject.id,
@@ -86,13 +100,26 @@ export function agentAccessToken(input: {
};
return {
- asAgent: async () => (await vended()).actorToken,
- asUser: async () => (await vended()).subjectToken,
+ resolveServiceFoundryAuthorization: async () => {
+ const vendTokenResult = await vendToken();
+ return vendTokenResult.actorToken;
+ },
+ resolveGatewayAuthorization: async () => {
+ const vendTokenResult = await vendToken();
+ if (callerAuthorization !== null) {
+ return {
+ type: 'delegated',
+ subjectToken: callerAuthorization,
+ actorAgentToken: vendTokenResult.actorToken,
+ };
+ }
+ return { type: 'exchanged', subjectToken: vendTokenResult.subjectToken };
+ },
};
}
/** Token of whoever made the request. */
-export function callerAccessToken(context: RequestContext): ResolveAccessToken {
+export function callerAccessToken(context: RequestContext): ResolveServiceFoundryAuthorization {
if (context.user_credential === null) {
throw new HTTPException(401, {
message: 'Authentication token required to list or call TrueFoundry models, MCP servers, skills, and agents',
@@ -111,9 +138,9 @@ export function accessTokenForRequest(input: {
requestContext: TrueFoundryRequestContext;
agent: AgentRecord | undefined;
logger: Pick<Logger, 'info'>;
-}): AccessTokens {
+}): TrueFoundryAccess {
if (input.agent === undefined) {
- return accessTokensFromCaller(input.requestContext);
+ return callerAccess(input.requestContext);
}
const agentId = requireTrueFoundryAgentExternalId(input.agent);
const cache = input.requestContext[accessTokenCache];
@@ -121,7 +148,7 @@ export function accessTokenForRequest(input: {
if (existing !== undefined) {
return existing;
}
- const tokens = agentAccessToken({
+ const tokens = savedAgentAccess({
client: input.client,
requestContext: input.requestContext,
agent: input.agent,
@@ -130,3 +157,18 @@ export function accessTokenForRequest(input: {
cache.set(agentId, tokens);
return tokens;
}
+
+/** Actor header for delegated mode. Empty for caller and exchanged. */
+export function actorAuthorizationHeaders(authorization: GatewayAuthorization): Record<string, string> {
+ if (authorization.actorAgentToken === undefined) {
+ return {};
+ }
+ return { [ACTOR_AUTHORIZATION_HEADER]: `Bearer ${authorization.actorAgentToken}` };
+}
+
+export function gatewayHeaders(authorization: GatewayAuthorization): Record<string, string> {
+ return {
+ Authorization: `Bearer ${authorization.subjectToken}`,
+ ...actorAuthorizationHeaders(authorization),
+ };
+}
diff --git a/packages/trueforge/src/truefoundry/gatewayMetadata.ts b/packages/trueforge/src/truefoundry/gatewayMetadata.ts
index c09ec78aa..213f31ea1 100644
--- a/packages/trueforge/src/truefoundry/gatewayMetadata.ts
+++ b/packages/trueforge/src/truefoundry/gatewayMetadata.ts
@@ -88,14 +88,17 @@ export function gatewayMetadataHeaders(metadata: Record<string, string>): Record
}
/** Metadata header for a turn. Reads `x-tfy-metadata` from the raw request headers. */
-export function gatewayMetadataHeadersForTurn(turnMetadata: TurnMetadata): Record<string, string> {
+export function gatewayMetadataHeadersForTurn(turnMetadata: TurnMetadata | undefined): Record<string, string> {
+ if (turnMetadata === undefined) {
+ return {};
+ }
const raw = headerValue(turnMetadata.requestHeaders, X_TFY_METADATA);
return gatewayMetadataHeaders(
mergeGatewayMetadata({
sessionId: turnMetadata.sessionId,
turnId: turnMetadata.turnId,
...(turnMetadata.agent === undefined ? {} : { agent: turnMetadata.agent }),
- requestMetadata: raw === undefined ? undefined : parseGatewayMetadataHeader(raw),
+ requestMetadata: raw === undefined ? {} : parseGatewayMetadataHeader(raw),
}),
);
}
diff --git a/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.ts b/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.ts
index 4cdf67db5..edf5e2a38 100644
--- a/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.ts
+++ b/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.ts
@@ -2,7 +2,7 @@ import { AgentSpecSchema } from '@truefoundry/trueforge-core/agent-session';
import { createLogger } from 'winston';
import type { AgentRecord } from '../../../src/db/agentStore';
import { McpServerNotFoundError, type McpServerRecord } from '../../../src/db/mcpServerStore';
-import { createTrueFoundryRequestContext } from '../../../src/truefoundry/accessToken';
+import { ACTOR_AUTHORIZATION_HEADER, createTrueFoundryRequestContext } from '../../../src/truefoundry/accessToken';
import { X_TFY_METADATA } from '../../../src/truefoundry/gatewayMetadata';
import { MCP_PROXY_BASE_URL_TEMPLATE } from '../../../src/truefoundry/mapSfyMcpServers';
import type { TrueFoundryMcpApiClient } from '../../../src/truefoundry/TrueFoundryMcpServerStore';
@@ -59,6 +59,7 @@ function createMockClient(): MockClient {
function createStore(input?: {
accessToken?: string;
+ userCredential?: string | null;
client?: MockClient;
subject?: { id: string; type: string; display_name: string };
agent?: AgentRecord;
@@ -81,7 +82,8 @@ function createStore(input?: {
tenant_id: TENANT,
subject: input?.subject ?? { id: 'user-1', type: 'user', display_name: 'user-1' },
roles: [],
- user_credential: input?.accessToken ?? ACCESS_TOKEN,
+ user_credential:
+ input?.userCredential !== undefined ? input.userCredential : (input?.accessToken ?? ACCESS_TOKEN),
}),
agent: input?.agent,
logger: createLogger({ silent: true }),
@@ -209,10 +211,11 @@ describe('TrueFoundryMcpServerStore', () => {
});
});
- it('uses asUser with a saved agent', async () => {
+ it('uses the caller credential for delete with a saved agent', async () => {
const { store, client } = createStore({ agent: AGENT });
await store.deleteAuthorization({ tenant_id: TENANT, name: 'github', userRef: 'ignored' });
- expect(client.deleteMcpAuth).toHaveBeenCalledWith(expect.objectContaining({ accessToken: SUBJECT_TOKEN }));
+ expect(client.deleteMcpAuth).toHaveBeenCalledWith(expect.objectContaining({ accessToken: ACCESS_TOKEN }));
+ expect(client.getMcpServerByName).toHaveBeenCalledWith(expect.objectContaining({ accessToken: ACTOR_TOKEN }));
});
});
@@ -250,10 +253,10 @@ describe('TrueFoundryMcpServerStore', () => {
});
});
- it('uses asUser for live status with a saved agent', async () => {
+ it('uses the caller credential for live status with a saved agent', async () => {
const { store, client } = createStore({ agent: AGENT });
await store.resolveAuthStatuses({ records: [dcrRecord()], userRef: 'user-1' });
- expect(client.getMcpAuthStatus).toHaveBeenCalledWith(expect.objectContaining({ accessToken: SUBJECT_TOKEN }));
+ expect(client.getMcpAuthStatus).toHaveBeenCalledWith(expect.objectContaining({ accessToken: ACCESS_TOKEN }));
});
it('calls live status for a single truefoundry record without wire auth', async () => {
@@ -364,17 +367,29 @@ describe('TrueFoundryMcpServerStore', () => {
});
});
- it('uses asUser for authorize and gateway Bearer, asAgent for SFY lookups with a saved agent', async () => {
+ it('delegates invoke: caller bearer, actor header, actor token for SFY lookups', async () => {
const { store, client } = createStore({ agent: AGENT });
await expect(invoke(store)).resolves.toEqual({
- headers: { Authorization: `Bearer ${SUBJECT_TOKEN}` },
+ headers: {
+ Authorization: `Bearer ${ACCESS_TOKEN}`,
+ [ACTOR_AUTHORIZATION_HEADER]: `Bearer ${ACTOR_TOKEN}`,
+ },
});
- expect(client.getMcpAuthorize).toHaveBeenCalledWith(expect.objectContaining({ accessToken: SUBJECT_TOKEN }));
+ expect(client.getMcpAuthorize).toHaveBeenCalledWith(expect.objectContaining({ accessToken: ACCESS_TOKEN }));
expect(client.getMcpServerByName).toHaveBeenCalledWith(expect.objectContaining({ accessToken: ACTOR_TOKEN }));
expect(client.listGatewayInstallations).toHaveBeenCalledWith(ACTOR_TOKEN);
expect(client.vendToken).toHaveBeenCalledTimes(1);
});
+ it('exchanges invoke: subject token bearer and no actor header', async () => {
+ const { store, client } = createStore({ agent: AGENT, userCredential: null });
+ await expect(invoke(store)).resolves.toEqual({
+ headers: { Authorization: `Bearer ${SUBJECT_TOKEN}` },
+ });
+ expect(client.getMcpAuthorize).toHaveBeenCalledWith(expect.objectContaining({ accessToken: SUBJECT_TOKEN }));
+ expect(client.getMcpServerByName).toHaveBeenCalledWith(expect.objectContaining({ accessToken: ACTOR_TOKEN }));
+ });
+
it('throws 422 when auth_required lacks authorization_url', async () => {
const { store, client } = createStore();
client.getMcpAuthorize.mockResolvedValue({ status: 'auth_required' });
diff --git a/packages/trueforge/tests/unit/truefoundry/TrueFoundryModelProviderStore.test.ts b/packages/trueforge/tests/unit/truefoundry/TrueFoundryModelProviderStore.test.ts
index cc4c76835..06cf9dfe8 100644
--- a/packages/trueforge/tests/unit/truefoundry/TrueFoundryModelProviderStore.test.ts
+++ b/packages/trueforge/tests/unit/truefoundry/TrueFoundryModelProviderStore.test.ts
@@ -1,11 +1,13 @@
import { AgentSpecSchema } from '@truefoundry/trueforge-core/agent-session';
import { createLogger } from 'winston';
import type { AgentRecord } from '../../../src/db/agentStore';
-import { createTrueFoundryRequestContext } from '../../../src/truefoundry/accessToken';
+import { ACTOR_AUTHORIZATION_HEADER, createTrueFoundryRequestContext } from '../../../src/truefoundry/accessToken';
+import { X_TFY_METADATA } from '../../../src/truefoundry/gatewayMetadata';
import { TrueFoundryModelProviderStore } from '../../../src/truefoundry/TrueFoundryModelProviderStore';
import type { TrueFoundryServiceFoundryServerClient } from '../../../src/truefoundry/TrueFoundryServiceFoundryServerClient';
const TENANT = 'acme';
+const CALLER_TOKEN = 'caller-token';
const SUBJECT_TOKEN = 'subject-token';
const ACTOR_TOKEN = 'actor-token';
@@ -21,8 +23,8 @@ const AGENT: AgentRecord = {
updated_at: '2026-01-01T00:00:00.000Z',
};
-describe('TrueFoundryModelProviderStore dual tokens', () => {
- it('uses asAgent for SFY list calls and asUser as gateway api_key', async () => {
+describe('TrueFoundryModelProviderStore authorization', () => {
+ it('lists with the actor token and invokes with the caller credential when delegated', async () => {
const client = {
listProviderIntegrations: jest.fn().mockResolvedValue([
{
@@ -43,7 +45,7 @@ describe('TrueFoundryModelProviderStore dual tokens', () => {
tenant_id: TENANT,
subject: { id: 'user-1', type: 'user', display_name: 'User' },
roles: [],
- user_credential: 'caller-token',
+ user_credential: CALLER_TOKEN,
}),
agent: AGENT,
logger: createLogger({ silent: true }),
@@ -58,7 +60,62 @@ describe('TrueFoundryModelProviderStore dual tokens', () => {
expect(providers[0]?.manifest).toMatchObject({
type: 'truefoundry',
base_url: 'https://gateway.example',
- auth: { api_key: SUBJECT_TOKEN },
+ auth: { api_key: CALLER_TOKEN },
});
+ expect(providers[0]?.manifest).not.toHaveProperty('headers');
+
+ const provider = providers[0];
+ if (provider === undefined) {
+ throw new Error('expected a provider');
+ }
+ const headers = await store.resolveInvokeHeaders({
+ record: provider,
+ turnMetadata: { sessionId: 'sess-1', turnId: 'turn-1', agent: { id: 'agent-1', name: 'named' } },
+ });
+ expect(headers[ACTOR_AUTHORIZATION_HEADER]).toBe(`Bearer ${ACTOR_TOKEN}`);
+ expect(headers['Authorization']).toBeUndefined();
+ expect(JSON.parse(headers[X_TFY_METADATA] ?? '')).toMatchObject({
+ 'tfg.session_id': 'sess-1',
+ 'tfg.agent_id': 'agent-1',
+ });
+ expect(client.vendToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('uses the subject token as api_key and sends no actor header when exchanged', async () => {
+ const client = {
+ listProviderIntegrations: jest.fn().mockResolvedValue([
+ {
+ name: 'gpt-4',
+ manifest: { model_types: ['chat'] },
+ providerAccount: { name: 'openai-main' },
+ },
+ ]),
+ listGatewayInstallations: jest
+ .fn()
+ .mockResolvedValue([{ isDefault: true, manifest: { url: 'https://gateway.example' } }]),
+ vendToken: jest.fn().mockResolvedValue({ subjectToken: SUBJECT_TOKEN, actorToken: ACTOR_TOKEN }),
+ } as unknown as TrueFoundryServiceFoundryServerClient;
+
+ const store = new TrueFoundryModelProviderStore({
+ client,
+ requestContext: createTrueFoundryRequestContext({
+ tenant_id: TENANT,
+ subject: { id: 'user-1', type: 'user', display_name: 'User' },
+ roles: [],
+ user_credential: null,
+ }),
+ agent: AGENT,
+ logger: createLogger({ silent: true }),
+ });
+
+ const providers = await store.listProviders({ tenant_id: TENANT });
+ expect(client.listProviderIntegrations).toHaveBeenCalledWith(expect.objectContaining({ accessToken: ACTOR_TOKEN }));
+ expect(providers[0]?.manifest).toMatchObject({ auth: { api_key: SUBJECT_TOKEN } });
+ const provider = providers[0];
+ if (provider === undefined) {
+ throw new Error('expected a provider');
+ }
+ await expect(store.resolveInvokeHeaders({ record: provider })).resolves.toEqual({});
+ expect(client.vendToken).toHaveBeenCalledTimes(1);
});
});
diff --git a/packages/trueforge/tests/unit/truefoundry/accessToken.test.ts b/packages/trueforge/tests/unit/truefoundry/accessToken.test.ts
index 43268cb90..9240d7fd9 100644
--- a/packages/trueforge/tests/unit/truefoundry/accessToken.test.ts
+++ b/packages/trueforge/tests/unit/truefoundry/accessToken.test.ts
@@ -3,11 +3,13 @@ import { HTTPException } from 'hono/http-exception';
import type { RequestContext } from '../../../src/auth/identity';
import type { AgentRecord } from '../../../src/db/agentStore';
import {
+ ACTOR_AUTHORIZATION_HEADER,
accessTokenForRequest,
- agentAccessToken,
asTrueFoundryRequestContext,
callerAccessToken,
createTrueFoundryRequestContext,
+ gatewayHeaders,
+ savedAgentAccess,
} from '../../../src/truefoundry/accessToken';
const CONTEXT: RequestContext = {
@@ -44,14 +46,32 @@ describe('callerAccessToken', () => {
});
});
-describe('agentAccessToken', () => {
- it('vends dual tokens scoped to the agent, naming the caller as the subject', async () => {
+describe('gatewayHeaders', () => {
+ it('sends the actor header only when the credential has one', () => {
+ expect(gatewayHeaders({ type: 'caller', subjectToken: 'caller-token' })).toEqual({
+ Authorization: 'Bearer caller-token',
+ });
+ expect(gatewayHeaders({ type: 'delegated', subjectToken: 'caller-token', actorAgentToken: 'agent-token' })).toEqual(
+ {
+ Authorization: 'Bearer caller-token',
+ [ACTOR_AUTHORIZATION_HEADER]: 'Bearer agent-token',
+ },
+ );
+ });
+});
+
+describe('savedAgentAccess', () => {
+ it('delegates when the caller credential is present', async () => {
const client = { vendToken: jest.fn().mockResolvedValue(VENDED) };
const logger = { info: jest.fn() };
- const tokens = agentAccessToken({ client, requestContext: CONTEXT, agent: AGENT, logger });
- await expect(tokens.asAgent()).resolves.toBe('agent-token');
- await expect(tokens.asUser()).resolves.toBe('user-token');
+ const access = savedAgentAccess({ client, requestContext: CONTEXT, agent: AGENT, logger });
+ await expect(access.resolveServiceFoundryAuthorization()).resolves.toBe('agent-token');
+ await expect(access.resolveGatewayAuthorization()).resolves.toEqual({
+ type: 'delegated',
+ subjectToken: 'caller-token',
+ actorAgentToken: 'agent-token',
+ });
expect(logger.info).toHaveBeenCalledWith('Exchanging user context for agent access token', {
subject: 'user-1',
agentId: 'ext-agent',
@@ -61,17 +81,23 @@ describe('agentAccessToken', () => {
agentId: 'ext-agent',
tenantName: 'acme',
});
+ expect(client.vendToken).toHaveBeenCalledTimes(1);
});
- it('vends once and reuses both tokens for later calls', async () => {
+ it('exchanges when the caller credential is absent', async () => {
const client = { vendToken: jest.fn().mockResolvedValue(VENDED) };
- const tokens = agentAccessToken({ client, requestContext: CONTEXT, agent: AGENT, logger: LOGGER });
+ const access = savedAgentAccess({
+ client,
+ requestContext: { ...CONTEXT, user_credential: null },
+ agent: AGENT,
+ logger: LOGGER,
+ });
- await expect(Promise.all([tokens.asAgent(), tokens.asUser(), tokens.asAgent()])).resolves.toEqual([
- 'agent-token',
- 'user-token',
- 'agent-token',
- ]);
+ await expect(access.resolveGatewayAuthorization()).resolves.toEqual({
+ type: 'exchanged',
+ subjectToken: 'user-token',
+ });
+ await expect(access.resolveServiceFoundryAuthorization()).resolves.toBe('agent-token');
expect(client.vendToken).toHaveBeenCalledTimes(1);
});
@@ -79,10 +105,14 @@ describe('agentAccessToken', () => {
const client = {
vendToken: jest.fn().mockRejectedValueOnce(new Error('vend failed')).mockResolvedValue(VENDED),
};
- const tokens = agentAccessToken({ client, requestContext: CONTEXT, agent: AGENT, logger: LOGGER });
+ const access = savedAgentAccess({ client, requestContext: CONTEXT, agent: AGENT, logger: LOGGER });
- await expect(tokens.asAgent()).rejects.toThrow('vend failed');
- await expect(tokens.asUser()).resolves.toBe('user-token');
+ await expect(access.resolveServiceFoundryAuthorization()).rejects.toThrow('vend failed');
+ await expect(access.resolveGatewayAuthorization()).resolves.toEqual({
+ type: 'delegated',
+ subjectToken: 'caller-token',
+ actorAgentToken: 'agent-token',
+ });
expect(client.vendToken).toHaveBeenCalledTimes(2);
});
@@ -90,7 +120,7 @@ describe('agentAccessToken', () => {
const client = { vendToken: jest.fn() };
expect(() =>
- agentAccessToken({
+ savedAgentAccess({
client,
requestContext: CONTEXT,
agent: { ...AGENT, external_id: null },
@@ -108,29 +138,35 @@ describe('asTrueFoundryRequestContext', () => {
});
describe('accessTokenForRequest', () => {
- it('uses the caller token for both identities without an agent', async () => {
+ it('uses the caller token for catalog and gateway without an agent', async () => {
const client = { vendToken: jest.fn() };
const context = createTrueFoundryRequestContext(CONTEXT);
- const tokens = accessTokenForRequest({
+ const access = accessTokenForRequest({
client,
requestContext: context,
agent: undefined,
logger: LOGGER,
});
- await expect(tokens.asAgent()).resolves.toBe('caller-token');
- await expect(tokens.asUser()).resolves.toBe('caller-token');
- expect(tokens.asAgent).toBe(tokens.asUser);
+ await expect(access.resolveServiceFoundryAuthorization()).resolves.toBe('caller-token');
+ await expect(access.resolveGatewayAuthorization()).resolves.toEqual({
+ type: 'caller',
+ subjectToken: 'caller-token',
+ });
expect(client.vendToken).not.toHaveBeenCalled();
});
- it('maps vend actorToken to asAgent and subjectToken to asUser', async () => {
+ it('delegates a saved agent that still has the caller credential', async () => {
const client = { vendToken: jest.fn().mockResolvedValue(VENDED) };
const context = createTrueFoundryRequestContext(CONTEXT);
- const tokens = accessTokenForRequest({ client, requestContext: context, agent: AGENT, logger: LOGGER });
- await expect(tokens.asAgent()).resolves.toBe('agent-token');
- await expect(tokens.asUser()).resolves.toBe('user-token');
+ const access = accessTokenForRequest({ client, requestContext: context, agent: AGENT, logger: LOGGER });
+ await expect(access.resolveServiceFoundryAuthorization()).resolves.toBe('agent-token');
+ await expect(access.resolveGatewayAuthorization()).resolves.toEqual({
+ type: 'delegated',
+ subjectToken: 'caller-token',
+ actorAgentToken: 'agent-token',
+ });
expect(client.vendToken).toHaveBeenCalledTimes(1);
});
@@ -142,11 +178,12 @@ describe('accessTokenForRequest', () => {
const mcp = accessTokenForRequest({ client, requestContext: context, agent: AGENT, logger: LOGGER });
expect(model).toBe(mcp);
- await expect(Promise.all([model.asAgent(), mcp.asUser(), model.asUser()])).resolves.toEqual([
- 'agent-token',
- 'user-token',
- 'user-token',
- ]);
+ await expect(model.resolveServiceFoundryAuthorization()).resolves.toBe('agent-token');
+ await expect(mcp.resolveGatewayAuthorization()).resolves.toEqual({
+ type: 'delegated',
+ subjectToken: 'caller-token',
+ actorAgentToken: 'agent-token',
+ });
expect(client.vendToken).toHaveBeenCalledTimes(1);
});
@@ -156,11 +193,21 @@ describe('accessTokenForRequest', () => {
const secondRequest = createTrueFoundryRequestContext(CONTEXT);
await expect(
- accessTokenForRequest({ client, requestContext: firstRequest, agent: AGENT, logger: LOGGER }).asAgent(),
+ accessTokenForRequest({
+ client,
+ requestContext: firstRequest,
+ agent: AGENT,
+ logger: LOGGER,
+ }).resolveServiceFoundryAuthorization(),
).resolves.toBe('agent-token');
await expect(
- accessTokenForRequest({ client, requestContext: secondRequest, agent: AGENT, logger: LOGGER }).asUser(),
- ).resolves.toBe('user-token');
+ accessTokenForRequest({
+ client,
+ requestContext: secondRequest,
+ agent: AGENT,
+ logger: LOGGER,
+ }).resolveGatewayAuthorization(),
+ ).resolves.toMatchObject({ type: 'delegated', subjectToken: 'caller-token' });
expect(client.vendToken).toHaveBeenCalledTimes(2);
});
});
diff --git a/packages/trueforge/tests/unit/truefoundry/gatewayMetadata.test.ts b/packages/trueforge/tests/unit/truefoundry/gatewayMetadata.test.ts
index 427c1d7b6..a23a5ecba 100644
--- a/packages/trueforge/tests/unit/truefoundry/gatewayMetadata.test.ts
+++ b/packages/trueforge/tests/unit/truefoundry/gatewayMetadata.test.ts
@@ -96,6 +96,10 @@ describe('mergeGatewayMetadata', () => {
});
describe('gatewayMetadataHeadersForTurn', () => {
+ it('returns no header when the turn is absent', () => {
+ expect(gatewayMetadataHeadersForTurn(undefined)).toEqual({});
+ });
+
it('reads x-tfy-metadata from the raw request headers', () => {
const headers = gatewayMetadataHeadersForTurn({
sessionId: 'sess-1',