@neuraltrust/trustgate 0.1.0

package/src/schema.ts

@@ -0,0 +1,193 @@
+import type { JSONSchema } from './types.js'
+
+/**
+ * Turning a tool's JSON Schema into what a provider will accept.
+ *
+ * The gateway relays an upstream server's schema exactly as that server wrote
+ * it — that is the honest thing for a gateway to do, and it means the schema
+ * can use anything JSON Schema allows. Every provider's function calling
+ * accepts a smaller language than that. Translating is therefore the client's
+ * job, done here, once, against the format the caller asked for.
+ *
+ * Two of these conversions lose information, so both are reversible and the
+ * original schema is kept: what goes out closed and nullable has to come back
+ * open and absent, or the upstream rejects the call it was asked to make.
+ */
+
+export type StrictResult = {
+	schema: JSONSchema
+	/** False when the schema uses something strict mode cannot express. */
+	strict: boolean
+	/** Why not, for the warning the caller gets. */
+	reason?: string
+}
+
+/**
+ * Inlines local `$ref`s.
+ *
+ * Nothing is lost: a reference and its target describe the same thing. It is
+ * separated from the strict pass because every provider needs it and none of
+ * them object to the result — which is why this is also the part that could
+ * one day move into the gateway.
+ */
+export function inlineRefs(schema: JSONSchema): JSONSchema {
+	const defs = {
+		...((schema.$defs as Record<string, JSONSchema>) ?? {}),
+		...((schema.definitions as Record<string, JSONSchema>) ?? {}),
+	}
+	const seen = new Set<string>()
+
+	const walk = (node: unknown): unknown => {
+		if (Array.isArray(node)) return node.map(walk)
+		if (!isObject(node)) return node
+		const ref = node.$ref
+		if (typeof ref === 'string') {
+			const target = resolveRef(ref, defs)
+			// A cycle cannot be inlined; leaving the $ref in place makes the
+			// strict pass refuse the tool, which is better than looping.
+			if (target && !seen.has(ref)) {
+				seen.add(ref)
+				const resolved = walk({ ...target, ...omit(node, ['$ref']) })
+				seen.delete(ref)
+				return resolved
+			}
+			return node
+		}
+		const out: Record<string, unknown> = {}
+		for (const [key, value] of Object.entries(node)) {
+			if (key === '$defs' || key === 'definitions') continue
+			out[key] = walk(value)
+		}
+		return out
+	}
+
+	return walk(schema) as JSONSchema
+}
+
+function resolveRef(ref: string, defs: Record<string, JSONSchema>): JSONSchema | undefined {
+	const match = /^#\/(?:\$defs|definitions)\/(.+)$/.exec(ref)
+	if (!match) return undefined
+	return defs[decodeURIComponent(match[1])]
+}
+
+/**
+ * Rewrites a schema for OpenAI's strict function calling.
+ *
+ * Strict buys a guarantee worth having — the model cannot invent an argument —
+ * and charges for it in expressiveness: every object closed, every property
+ * required, and optionality expressed by accepting null. Schemas that use what
+ * strict cannot say are returned untouched with `strict: false`, because a tool
+ * the model can still call imperfectly beats a tool it cannot call at all.
+ */
+export function toStrict(schema: JSONSchema): StrictResult {
+	const inlined = inlineRefs(schema)
+	let reason: string | undefined
+
+	const walk = (node: unknown): unknown => {
+		if (Array.isArray(node)) return node.map(walk)
+		if (!isObject(node)) return node
+		if ('$ref' in node) {
+			reason ??= 'it carries a $ref that does not resolve inside the schema'
+			return node
+		}
+		if ('allOf' in node) {
+			reason ??= 'it composes with allOf'
+			return node
+		}
+		if ('prefixItems' in node) {
+			reason ??= 'it uses prefixItems (tuple typing)'
+			return node
+		}
+
+		const out: Record<string, unknown> = {}
+		for (const [key, value] of Object.entries(node)) {
+			out[key] = key === 'required' ? value : walk(value)
+		}
+
+		if (out.type !== 'object' && !isObject(out.properties)) return out
+
+		if (out.additionalProperties !== undefined && out.additionalProperties !== false) {
+			reason ??= 'it accepts properties that are not in its schema'
+			return out
+		}
+		out.additionalProperties = false
+
+		const properties = (out.properties as Record<string, JSONSchema>) ?? {}
+		const required = new Set(Array.isArray(out.required) ? (out.required as string[]) : [])
+		const rewritten: Record<string, JSONSchema> = {}
+		for (const [name, property] of Object.entries(properties)) {
+			rewritten[name] = required.has(name) ? property : nullable(property)
+		}
+		out.properties = rewritten
+		// Strict wants every property named as required. What used to be
+		// optional stays optional in effect, by accepting null.
+		out.required = Object.keys(rewritten)
+		return out
+	}
+
+	const rewritten = walk(inlined) as JSONSchema
+	return reason ? { schema: inlined, strict: false, reason } : { schema: rewritten, strict: true }
+}
+
+/** Lets a schema accept null without losing what it already said. */
+function nullable(schema: JSONSchema): JSONSchema {
+	if (typeof schema.type === 'string') {
+		return { ...schema, type: [schema.type, 'null'] }
+	}
+	if (Array.isArray(schema.type)) {
+		return schema.type.includes('null') ? schema : { ...schema, type: [...schema.type, 'null'] }
+	}
+	// No plain type to widen (an enum, an anyOf): offer null beside it.
+	return { anyOf: [schema, { type: 'null' }] }
+}
+
+/**
+ * Removes the nulls strict mode asked the model to send.
+ *
+ * `toStrict` made every optional property nullable so it could be named in
+ * `required`. The model takes that literally and sends `null` for the ones it
+ * has no value for — and the upstream server, which never agreed to any of
+ * this, rejects them. So the arguments are compared against the *original*
+ * schema on the way back, and a null it never permitted is dropped rather than
+ * forwarded.
+ */
+export function stripInjectedNulls(args: unknown, original: JSONSchema | undefined): unknown {
+	if (Array.isArray(args)) {
+		const items = original?.items as JSONSchema | undefined
+		return args.map((item) => stripInjectedNulls(item, items))
+	}
+	if (!isObject(args)) return args
+	const properties = (original?.properties as Record<string, JSONSchema> | undefined) ?? {}
+	const out: Record<string, unknown> = {}
+	for (const [key, value] of Object.entries(args)) {
+		const property = properties[key]
+		if (value === null && !permitsNull(property)) continue
+		out[key] = stripInjectedNulls(value, property)
+	}
+	return out
+}
+
+function permitsNull(schema: JSONSchema | undefined): boolean {
+	// An unknown property is left alone: the upstream may accept keys this
+	// schema does not describe, and dropping one would lose a real argument.
+	if (!schema) return true
+	if (schema.type === 'null') return true
+	if (Array.isArray(schema.type) && schema.type.includes('null')) return true
+	const anyOf = schema.anyOf ?? schema.oneOf
+	if (Array.isArray(anyOf)) {
+		return anyOf.some((option) => permitsNull(option as JSONSchema))
+	}
+	return false
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function omit(source: Record<string, unknown>, keys: string[]): Record<string, unknown> {
+	const out: Record<string, unknown> = {}
+	for (const [key, value] of Object.entries(source)) {
+		if (!keys.includes(key)) out[key] = value
+	}
+	return out
+}

package/src/types.ts

@@ -0,0 +1,98 @@
+import { TrustGateError } from './errors.js'
+/** Which actor a handle speaks as. The consumer decides this, not the caller. */
+export const Actor = {
+	/** The application itself — principal `app:<consumer_id>`. */
+	Application: 'application',
+	/** One of the application's own end users. */
+	EndUser: 'end_user',
+} as const
+export type Actor = (typeof Actor)[keyof typeof Actor]
+
+/**
+ * The tool shapes the SDK can emit.
+ *
+ * These are model providers, not agent frameworks. A framework brings its own
+ * MCP client, so it takes the gateway's URL and lists the tools itself — there
+ * is nothing to convert. Conversion only happens when you call a provider's
+ * API directly, which is why nothing here is called "langchain".
+ */
+export const ToolFormat = {
+	/** OpenAI Responses API — function tools, flattened. */
+	OpenAIResponses: 'openai-responses',
+	/** OpenAI Chat Completions — function tools, nested under `function`. */
+	OpenAIChat: 'openai-chat',
+	/** Anthropic Messages — `input_schema`. */
+	AnthropicMessages: 'anthropic-messages',
+	/** Google Gemini — a single `functionDeclarations` entry. */
+	Gemini: 'gemini',
+} as const
+export type ToolFormat = (typeof ToolFormat)[keyof typeof ToolFormat]
+
+/** A tool as the gateway serves it, before any provider dialect is applied. */
+export type GatewayTool = {
+	name: string
+	title?: string
+	description?: string
+	inputSchema: JSONSchema
+	outputSchema?: JSONSchema
+}
+
+export type JSONSchema = Record<string, unknown>
+
+/** One upstream account of an actor, as the connections API reports it. */
+export type Connection = {
+	provider: string
+	registry?: string
+	code?: string
+	status: 'connected' | 'needs_reconnect' | 'not_connected'
+	accountRef?: string
+	expiresAt?: Date
+}
+
+/** The link an end user opens to connect their own account. */
+export type ConnectLink = {
+	connectUrl: string
+	ticket: string
+	provider?: string
+	expiresAt: Date
+}
+
+/** Everything a provider's client needs to reach the gateway. */
+export type Endpoint = {
+	url: string
+	headers: Record<string, string>
+}
+
+/** A tool call as the SDK understands it, whatever provider asked for it. */
+export type ToolCall = {
+	/** The provider's own identifier for this call, echoed back in the result. */
+	id: string
+	name: string
+	arguments: Record<string, unknown>
+}
+
+/**
+ * The exposed name of a tool the caller named.
+ *
+ * The gateway prefixes every tool with the server it came from, so Linear's
+ * `list_issues` is served as `linear_list_issues`. That prefix is the gateway's
+ * doing and not the caller's, so a name written without one resolves — as long
+ * as exactly one server serves it. Two that do is a genuine question only the
+ * caller can answer, and it is asked rather than guessed.
+ *
+ * A name that matches nothing is returned unchanged, so the error that follows
+ * is about the tool rather than about this.
+ */
+export function resolveToolName(name: string, tools: GatewayTool[]): string {
+	const names = tools.map((tool) => tool.name)
+	if (names.includes(name)) return name
+	const matches = names.filter((candidate) => candidate.endsWith(`_${name}`))
+	if (matches.length === 1) return matches[0]
+	if (matches.length > 1) {
+		throw new TrustGateError(
+			`"${name}" is served by more than one of this application's servers ` +
+				`(${[...matches].sort().join(', ')}). Name the one you mean.`
+		)
+	}
+	return name
+}

package/src/whoami.ts

@@ -0,0 +1,172 @@
+import type { ResolvedConfig } from './config.js'
+import { PlaneUnavailableError, TrustGateError } from './errors.js'
+import { requestJSON } from './http.js'
+
+/** Whose account an MCP server reads: the one its instance holds, or one per caller. */
+export type UpstreamAccount = 'shared' | 'user'
+
+/**
+ * Who has to act before a server answers a call that runs as the application.
+ *
+ * `administrator` is an instance whose shared account nobody has connected —
+ * no caller can connect it, because it is the account every other caller rides
+ * on. `end_user` is an instance that keeps an account per caller, which an
+ * application is not: it names the person it acts for, and the account becomes
+ * theirs to connect.
+ */
+export type UpstreamBlockedBy = 'administrator' | 'end_user'
+
+/** One MCP server the application is bound to, and what it is waiting for. */
+export type KeyUpstream = {
+	server: string
+	provider?: string
+	account: UpstreamAccount
+	connected: boolean
+	needsReconnect: boolean
+	blocked?: UpstreamBlockedBy
+}
+
+/** One consumer the key reaches, with the address it is served on. */
+export type KeyConsumer = {
+	slug: string
+	name?: string
+	/** The plane this consumer belongs to: MCP, LLM or A2A. */
+	type: string
+	active: boolean
+	/** Where it answers. Empty when the gateway publishes no host for its plane. */
+	url: string
+	/**
+	 * The servers behind it that read a stored account, answered for this key —
+	 * which is the application itself.
+	 *
+	 * `undefined` is not "nothing to connect": it is also what a gateway that
+	 * could not read the accounts answers, and a server carrying its own
+	 * credential is never listed. Read `blocked`, never a length.
+	 */
+	upstreams?: KeyUpstream[]
+}
+
+/** The calling key itself. The secret is never echoed. */
+export type KeyInfo = {
+	name?: string
+	/** When it retires itself. `undefined` means never. */
+	expiresAt?: Date
+}
+
+/** Everything the key can say about itself. */
+export type KeyIdentity = {
+	gateway: string
+	key: KeyInfo
+	consumers: KeyConsumer[]
+}
+
+type Payload = {
+	gateway?: string
+	key?: { name?: string; expires_at?: string }
+	consumers?: {
+		slug: string
+		name?: string
+		type: string
+		active: boolean
+		url?: string
+		upstreams?: {
+			server?: string
+			provider?: string
+			account?: string
+			connected?: boolean
+			needs_reconnect?: boolean
+			blocked?: string
+		}[]
+	}[]
+}
+
+/**
+ * Asks the key what it reaches, when it dies, and what is not connected yet.
+ *
+ * It is what lets a client be configured with one secret: the slugs were
+ * chosen by whoever created the consumers, and the LLM plane is on a host the
+ * MCP URL says nothing about, so both have to come from the gateway. The other
+ * two answers are the failures a client would otherwise meet at runtime — an
+ * expired key as a 401 mid-run, an unconnected server as a refusal on the
+ * first tool call — moved to where something can still be done about them.
+ */
+export async function whoAmI(config: ResolvedConfig, signal?: AbortSignal): Promise<KeyIdentity> {
+	const { body } = await requestJSON<Payload>(config, 'GET', '/whoami', { signal })
+	return {
+		gateway: body?.gateway ?? '',
+		key: {
+			name: body?.key?.name || undefined,
+			expiresAt: parseDate(body?.key?.expires_at),
+		},
+		consumers: (body?.consumers ?? []).map((consumer) => ({
+			slug: consumer.slug,
+			name: consumer.name || undefined,
+			type: String(consumer.type ?? '').toUpperCase(),
+			active: consumer.active !== false,
+			url: consumer.url ?? '',
+			upstreams: consumer.upstreams?.map((upstream) => ({
+				server: upstream.server ?? '',
+				provider: upstream.provider || undefined,
+				account: upstream.account === 'shared' ? 'shared' : 'user',
+				connected: upstream.connected === true,
+				needsReconnect: upstream.needs_reconnect === true,
+				blocked: blockedBy(upstream.blocked),
+			})),
+		})),
+	}
+}
+
+function blockedBy(raw: string | undefined): UpstreamBlockedBy | undefined {
+	return raw === 'administrator' || raw === 'end_user' ? raw : undefined
+}
+
+function parseDate(raw: string | undefined): Date | undefined {
+	if (!raw) return undefined
+	const at = new Date(raw)
+	return Number.isNaN(at.getTime()) ? undefined : at
+}
+
+/**
+ * Picks the one consumer of a plane, or explains why it cannot.
+ *
+ * A key attached to two consumers of the same type is a legitimate setup that
+ * this SDK cannot resolve on its own, so it names them and asks — rather than
+ * guessing and running an agent against the wrong surface.
+ */
+export function selectConsumer(
+	identity: KeyIdentity,
+	plane: 'MCP' | 'LLM',
+	configured: string | undefined,
+	envName: string
+): KeyConsumer {
+	const candidates = identity.consumers.filter((consumer) => consumer.type === plane)
+	if (configured) {
+		const named = candidates.find((consumer) => consumer.slug === configured)
+		if (named) return named
+		throw new PlaneUnavailableError(
+			`this API key does not reach a ${plane} consumer called "${configured}"` +
+				(candidates.length ? `; it reaches ${candidates.map((c) => c.slug).join(', ')}` : '')
+		)
+	}
+	if (candidates.length === 0) {
+		throw new PlaneUnavailableError(
+			`this API key reaches no ${plane} consumer. ` +
+				'Ask the admin who owns this application to attach one, or name it explicitly.'
+		)
+	}
+	if (candidates.length > 1) {
+		throw new TrustGateError(
+			`this API key reaches several ${plane} consumers (${candidates
+				.map((consumer) => consumer.slug)
+				.join(', ')}); name the one this agent uses.`
+		)
+	}
+	const only = candidates[0]
+	if (!only.url) {
+		throw new PlaneUnavailableError(
+			`the gateway publishes no host for its ${plane} plane, so "${only.slug}" has no address. ` +
+				`Set ${envName} and a base URL for it, or ask an operator to configure that plane's domain.`
+		)
+	}
+	return only
+}