@vertesia/common 1.5.0-dev.20260804.124748Z → 1.5.0-dev.20260807.073259Z

package/src/api-schemas/mcp-api-key.contract.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import type { McpApiKeyStatus } from '../apps.js';
+import { AppInstallationPayloadSchema } from './app-lifecycle.js';
+import { McpApiKeyStatusSchema, SetMcpApiKeyRequestSchema } from './apps.js';
+import { validateApiRequest } from './registry.js';
+
+/** Exact type identity — `extends` in both directions is too weak (any/unknown slip through). */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+function assertType<T extends true>(_ok: T): void {}
+
+/**
+ * Request bodies are enforced by AJV against the EMITTED JSON Schema, not by parsing with Zod. A
+ * Zod-only assertion would pass on transforms (`.trim()`) that leave no trace in the emission and
+ * therefore never run at the endpoint — so the blank-key cases below go through `validateApiRequest`,
+ * which is the path `validatedBody` actually takes.
+ */
+describe('SetMcpApiKeyRequest — as enforced at the endpoint (AJV)', () => {
+    it('accepts a real key', () => {
+        expect(validateApiRequest('SetMcpApiKeyRequest', { api_key: 'sk-live-abcdef' }).valid).toBe(true);
+    });
+
+    it('rejects a whitespace-only key', () => {
+        expect(validateApiRequest('SetMcpApiKeyRequest', { api_key: '   ' }).valid).toBe(false);
+    });
+
+    it('rejects a tab/newline-only key', () => {
+        expect(validateApiRequest('SetMcpApiKeyRequest', { api_key: '\t\n ' }).valid).toBe(false);
+    });
+
+    it('rejects an empty key', () => {
+        expect(validateApiRequest('SetMcpApiKeyRequest', { api_key: '' }).valid).toBe(false);
+    });
+
+    it('rejects a missing key', () => {
+        expect(validateApiRequest('SetMcpApiKeyRequest', {}).valid).toBe(false);
+    });
+
+    it('rejects unknown properties', () => {
+        expect(validateApiRequest('SetMcpApiKeyRequest', { api_key: 'sk-live', collection_id: 'x' }).valid).toBe(false);
+    });
+
+    it('still normalizes surrounding whitespace for Zod consumers', () => {
+        expect(SetMcpApiKeyRequestSchema.parse({ api_key: '  sk-live-abcdef  ' }).api_key).toBe('sk-live-abcdef');
+    });
+});
+
+describe('AppInstallationPayload.api_key_params — as enforced at the endpoint (AJV)', () => {
+    const APP_ID = '68b1779130afe5403a1589bc';
+
+    it('accepts a key per collection', () => {
+        const result = validateApiRequest('AppInstallationPayload', {
+            app_id: APP_ID,
+            api_key_params: { acme_mcp: { api_key: 'sk-install-abcdef' } },
+        });
+        expect(result.valid).toBe(true);
+    });
+
+    it('rejects a whitespace-only key on the install path too', () => {
+        const result = validateApiRequest('AppInstallationPayload', {
+            app_id: APP_ID,
+            api_key_params: { acme_mcp: { api_key: '  ' } },
+        });
+        expect(result.valid).toBe(false);
+    });
+
+    it('stays optional — installs with no api_key collections send nothing', () => {
+        expect(validateApiRequest('AppInstallationPayload', { app_id: APP_ID }).valid).toBe(true);
+        expect(AppInstallationPayloadSchema.parse({ app_id: APP_ID }).api_key_params).toBeUndefined();
+    });
+});
+
+describe('McpApiKeyStatus', () => {
+    it('publishes hint as required-but-nullable, not optional', () => {
+        // Every response sets `hint`, so the field must not be optional in the generated clients.
+        assertType<Equals<McpApiKeyStatus, { configured: boolean; hint: string | null }>>(true);
+        expect(McpApiKeyStatusSchema.safeParse({ configured: false }).success).toBe(false);
+        expect(McpApiKeyStatusSchema.safeParse({ configured: false, hint: null }).success).toBe(true);
+        expect(McpApiKeyStatusSchema.safeParse({ configured: true, hint: 'sk-l...3456' }).success).toBe(true);
+    });
+
+    it('never carries the key itself', () => {
+        expect(McpApiKeyStatusSchema.safeParse({ configured: true, hint: null, api_key: 'sk-live' }).success).toBe(
+            false,
+        );
+    });
+});

package/src/api-schemas/registry.ts

@@ -80,7 +80,7 @@ import {
     SystemRoleDefinitionArraySchema,
 } from './access-control.js';
 import { AccountSchema, StripeBillingStatusResponseSchema, UpdateAccountPayloadSchema } from './account.js';
-import { findUnprunablePaths, type JsonObject, pruneToSchema, toOpenApiComponents } from './adapter.js';
+import { findUnprunablePaths, isPlainObject, type JsonObject, pruneToSchema, toOpenApiComponents } from './adapter.js';
 import * as AgentRunSchemas from './agent-runs.js';
 import {
     AnalyticsAxisSchema,
@@ -109,9 +109,11 @@ import {
     AgentRunTypeSchema,
     AgentToolApprovalClassSchema,
     AgentToolDefinitionSchema,
+    AppApiKeyCollectionParamsSchema,
     AppBuildProgressSchema,
     AppBuildProgressStatusSchema,
     AppBuildTriggerSchema,
+    AppDeleteSummarySchema,
     AppDevelopmentTaskDetailsSchema,
     AppDevelopmentTaskListSchema,
     AppDevelopmentTaskSchema,
@@ -155,6 +157,7 @@ import {
     EventRefSchema,
     Extract_AppVersionGitRefType_branch_tag_commitSchema,
     InCodeTypeRefSchema,
+    McpApiKeyCredentialSchema,
     OAuthClientCredentialsMapSchema,
     OAuthClientCredentialsSchema,
     RunKindSchema,
@@ -178,6 +181,7 @@ import {
     AppSourceConfigSchema,
     AppUIConfigSchema,
     MCPToolAnnotationsSchema,
+    McpApiKeyStatusSchema,
     McpOAuthConnectResponseSchema,
     McpOAuthDisconnectResponseSchema,
     McpOAuthTokenRequestSchema,
@@ -186,6 +190,7 @@ import {
     OAuthAuthStatusArraySchema,
     OAuthAuthStatusSchema,
     OAuthMetadataResponseSchema,
+    SetMcpApiKeyRequestSchema,
     ToolCollectionObjectSchema,
 } from './apps.js';
 import {
@@ -1585,17 +1590,21 @@ const EVENT_DELIVERY_SCHEMAS = {
     EventOutboxStatus: EventSchemas.EventOutboxStatusSchema,
     EventDeliverySortField: EventSchemas.EventDeliverySortFieldSchema,
     WebhookEventDeliveryTarget: EventSchemas.WebhookEventDeliveryTargetSchema,
+    AppEventDeliveryTarget: EventSchemas.AppEventDeliveryTargetSchema,
     WorkflowEventDeliveryTarget: EventSchemas.WorkflowEventDeliveryTargetSchema,
     EventDeliveryQueueFailureSummary: EventSchemas.EventDeliveryQueueFailureSummarySchema,
     EventOutboxQueueSummary: EventSchemas.EventOutboxQueueSummarySchema,
     EventDeliveryQueueSortField: EventSchemas.EventDeliveryQueueSortFieldSchema,
     AgentEventDeliveryTarget: EventSchemas.AgentEventDeliveryTargetSchema,
     WebhookEventDeliveryTargetInput: EventSchemas.WebhookEventDeliveryTargetInputSchema,
+    AppEventDeliveryTargetInput: EventSchemas.AppEventDeliveryTargetInputSchema,
     WorkflowEventDeliveryTargetInput: EventSchemas.WorkflowEventDeliveryTargetInputSchema,
     SemanticEvaluator: EventSchemas.SemanticEvaluatorSchema,
     SemanticEvaluationRecord: EventSchemas.SemanticEvaluationRecordSchema,
     EventDeliveryQueueSubscriptionSummary: EventSchemas.EventDeliveryQueueSubscriptionSummarySchema,
     EventDeliveryQueueSummaryPayload: EventSchemas.EventDeliveryQueueSummaryPayloadSchema,
+    CancelEventDeliveryIntentsPayload: EventSchemas.CancelEventDeliveryIntentsPayloadSchema,
+    CancelEventDeliveryIntentsResponse: EventSchemas.CancelEventDeliveryIntentsResponseSchema,
     EventSemanticCondition: EventSchemas.EventSemanticConditionSchema,
     EventDeliveryIntentSummary: EventSchemas.EventDeliveryIntentSummarySchema,
     EventDeliveryQueueSummaryResponse: EventSchemas.EventDeliveryQueueSummaryResponseSchema,
@@ -1806,6 +1815,10 @@ const REMOTE_MCP_SCHEMAS = {
     McpOAuthConnectResponse: McpOAuthConnectResponseSchema,
     OAuthAuthorizeResponse: OAuthAuthorizeResponseSchema,
     OAuthAuthStatusArray: OAuthAuthStatusArraySchema,
+    // The static-key alternative to that handshake: the key itself is write-only, so only the
+    // setter payload and the configured/hint projection are published.
+    SetMcpApiKeyRequest: SetMcpApiKeyRequestSchema,
+    McpApiKeyStatus: McpApiKeyStatusSchema,
 } as const satisfies Record<string, z.ZodType>;
 
 const AUDIT_TRAIL_SCHEMAS = {
@@ -1919,6 +1932,7 @@ const APP_LIFECYCLE_SCHEMAS = {
     RunType: RunTypeSchema,
     AppBuildProgressStatus: AppBuildProgressStatusSchema,
     DeleteAppVersionResponse: DeleteAppVersionResponseSchema,
+    AppDeleteSummary: AppDeleteSummarySchema,
     AppRepoBranch: AppRepoBranchSchema,
     AppRepoDocumentCommit: AppRepoDocumentCommitSchema,
     AppVersionGitSource: AppVersionGitSourceSchema,
@@ -1928,6 +1942,8 @@ const APP_LIFECYCLE_SCHEMAS = {
     AppDevelopmentTaskList: AppDevelopmentTaskListSchema,
     OAuthClientCredentialsMap: OAuthClientCredentialsMapSchema,
     AppOAuthCollectionParams: AppOAuthCollectionParamsSchema,
+    McpApiKeyCredential: McpApiKeyCredentialSchema,
+    AppApiKeyCollectionParams: AppApiKeyCollectionParamsSchema,
     AppInspectionIssue: AppInspectionIssueSchema,
     AppScaffoldProgress: AppScaffoldProgressSchema,
     AppRepoTree: AppRepoTreeSchema,
@@ -2077,6 +2093,7 @@ const STS_SCHEMAS = {
     ServiceAccountTokenRequest: StsSchemas.ServiceAccountTokenRequestSchema,
     IssueTokenRequest: StsSchemas.IssueTokenRequestSchema,
     IssueTokenResponse: StsSchemas.IssueTokenResponseSchema,
+    IssueTokenForbiddenResponse: StsSchemas.IssueTokenForbiddenResponseSchema,
     IssueTokenUnavailableResponse: StsSchemas.IssueTokenUnavailableResponseSchema,
 } as const satisfies Record<string, z.ZodType>;
 
@@ -2224,6 +2241,7 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'AgentTokenRequest',
     'ServiceAccountTokenRequest',
     'IssueTokenResponse',
+    'IssueTokenForbiddenResponse',
     'IssueTokenUnavailableResponse',
     'ApiKeyListQuery',
     // These payloads previously referenced closed generated utility components. They now own their
@@ -2371,6 +2389,7 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'AppUIConfig',
     'AppUINavItem',
     'MCPOAuthConfig',
+    'MCPApiKeyConfig',
     'MCPToolCollectionObject',
     'VertesiaSDKToolCollectionObject',
     // File, task, content-type and command components. Every one is published closed
@@ -2662,6 +2681,8 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'ListWorkflowRunsResponse',
     'EventDeliveryQueueSubscriptionSummary',
     'EventDeliveryQueueSummaryPayload',
+    'CancelEventDeliveryIntentsPayload',
+    'CancelEventDeliveryIntentsResponse',
     'ContentObjectExportStatusResponse',
     'TimerTask',
     'SignalTask',
@@ -2929,6 +2950,8 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'McpOAuthDisconnectResponse',
     'McpOAuthConnectResponse',
     'OAuthAuthorizeResponse',
+    'SetMcpApiKeyRequest',
+    'McpApiKeyStatus',
     'AuditMeter',
     'AuditAggregationDimensionMap',
     'AuditAggregationRow',
@@ -2982,6 +3005,7 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'AppInstallationProviderBinding',
     'AppInstallationOAuthBinding',
     'OAuthClientCredentials',
+    'McpApiKeyCredential',
     'AppInspectionCapabilityReport',
     'AppRepoTreeEntry',
     'AppRepoRef',
@@ -2990,6 +3014,7 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'InCodeTypeRef',
     'StoredTypeRef',
     'DeleteAppVersionResponse',
+    'AppDeleteSummary',
     'AppRepoBranch',
     'AppRepoDocumentCommit',
     'AppVersionGitSource',
@@ -3331,14 +3356,88 @@ const validators = new Map<string, ValidateFunction>();
  */
 let ajvInstance: Ajv2020 | undefined;
 
+/**
+ * The published components as AJV can consume them: the same schemas, with the two adjustments
+ * AJV's discriminator support requires and the OpenAPI document must not have.
+ *
+ * `discriminator: true` below is what makes AJV validate a discriminated union through the branch
+ * its tag names, instead of trying every branch and reporting all of their failures at once. The
+ * difference is not cosmetic — a legacy MCP tool collection missing `id` used to report the real
+ * error alongside two impossible ones from the branch it was never meant to match:
+ *
+ *     / must have required property 'id'                        <- the real one
+ *     / must NOT have additional properties: oauth_app          <- vertesia_sdk branch
+ *     /type must be equal to constant                           <- vertesia_sdk branch
+ *     / must match exactly one schema in oneOf
+ *
+ * AJV rejects `mapping` outright ("discriminator: mapping is not supported"), because it derives
+ * the tag-to-branch map from each branch's own `const`/`enum` instead. The OpenAPI document still
+ * needs the mapping — a generated Java or Go client reads it to pick a concrete subtype — so both
+ * fixups here apply to AJV's copy only, and `ApiSchemaComponents` is published exactly as built.
+ *
+ * AJV's remaining requirements — the tag required in every branch, carrying `const` or a
+ * single-valued `enum`, with the union node typed as an object — are what `synthesizeDiscriminator`
+ * in the adapter already checks before it emits a discriminator at all, and what the hand-written
+ * `.meta({ discriminator })` declarations restate. `api-discriminators.test.ts` compiles every
+ * registered component so a union satisfying neither fails the build rather than the request.
+ */
+function toAjvComponents(): Record<string, JsonObject> {
+    const schemas = structuredClone(ApiSchemaComponents) as Record<string, JsonObject>;
+    const resolve = (value: unknown): JsonObject | undefined => {
+        if (!isPlainObject(value)) return undefined;
+        const ref = value.$ref;
+        if (typeof ref !== 'string' || !ref.startsWith(COMPONENT_REF_PREFIX)) return value;
+        return schemas[ref.slice(COMPONENT_REF_PREFIX.length)];
+    };
+
+    visitSchemaNodes(schemas, (node) => {
+        const discriminator = node.discriminator;
+        if (!isPlainObject(discriminator) || !Array.isArray(node.oneOf)) return;
+        // AJV derives the tag-to-branch map from each branch's own literal, so `mapping` is both
+        // redundant and rejected.
+        delete discriminator.mapping;
+
+        const tag = discriminator.propertyName;
+        if (typeof tag !== 'string') return;
+        for (const member of node.oneOf) {
+            const branch = resolve(member);
+            const properties = branch && isPlainObject(branch.properties) ? branch.properties : undefined;
+            const tagSchema = properties?.[tag];
+            if (!isPlainObject(tagSchema) || tagSchema.const !== undefined || tagSchema.enum !== undefined) continue;
+            // The tag is a `$ref` to a named literal component — `TaskType_ACTIVITY`,
+            // `SupportedIntegrations_gladia` — because the literal carries its own `.meta({ id })`.
+            // AJV reads `properties/<tag>` looking for `const` or `enum` and does not follow a
+            // `$ref` to find one, so it refuses to compile the union at all. Restating the resolved
+            // literal ALONGSIDE the `$ref` is validation-neutral: `$ref` has no special precedence
+            // in 2020-12, both keywords apply, and they carry the same value by construction.
+            const target = resolve(tagSchema);
+            if (!target) continue;
+            if (target.const !== undefined) tagSchema.const = target.const;
+            else if (Array.isArray(target.enum)) tagSchema.enum = target.enum;
+        }
+    });
+    return schemas;
+}
+
+/** Every object node in the component graph, parents before children. */
+function visitSchemaNodes(value: unknown, visit: (node: JsonObject) => void): void {
+    if (Array.isArray(value)) {
+        for (const item of value) visitSchemaNodes(item, visit);
+        return;
+    }
+    if (!isPlainObject(value)) return;
+    visit(value);
+    for (const item of Object.values(value)) visitSchemaNodes(item, visit);
+}
+
 function getAjv(): Ajv2020 {
     if (ajvInstance) return ajvInstance;
-    const ajv = new Ajv2020({ strictSchema: false, allErrors: true });
+    const ajv = new Ajv2020({ strictSchema: false, allErrors: true, discriminator: true });
     // Without this, AJV treats `format` as an annotation and ignores it, so a `date-time` property
     // would document a constraint nothing checks — the exact spec/enforcement gap this design is
     // meant to close.
     addFormats(ajv);
-    ajv.addSchema({ $id: 'vertesia://openapi', components: { schemas: ApiSchemaComponents } });
+    ajv.addSchema({ $id: 'vertesia://openapi', components: { schemas: toAjvComponents() } });
     ajvInstance = ajv;
     return ajv;
 }
@@ -3351,20 +3450,101 @@ function getValidator(name: ApiComponentName): ValidateFunction {
     return validate;
 }
 
-function formatErrors(validate: ValidateFunction): string[] {
-    return (validate.errors ?? []).map((error) => {
+function additionalProperty(error: { params?: unknown }): string | undefined {
+    // AJV writes "must NOT have additional properties" and puts the offending key in `params`,
+    // so the message alone says a body is wrong without saying which property made it wrong.
+    // Every other keyword names its subject already — `required` quotes the missing property,
+    // `enum` and `type` describe the value in place — and this is the one a caller most often
+    // trips, so it is the one worth spelling out rather than reformatting all of them.
+    return (error.params as { additionalProperty?: string } | undefined)?.additionalProperty;
+}
+
+/**
+ * One validation failure, with the undeclared property names kept AS NAMES.
+ *
+ * The structure exists because the rendered line cannot be taken apart again. Property names are
+ * arbitrary JSON strings: `{"customer secret token": 1}` and `{"a, b": 1}` are both valid, so
+ * neither a space nor a comma is a reliable separator once the names have been joined. Any consumer
+ * that needs to shorten the list — the HTTP boundary does, the log does not — has to do it here,
+ * on the array, where a name can be dropped whole.
+ */
+export interface ApiValidationIssue {
+    /**
+     * AJV's `instancePath` for the failing value, with `'/'` substituted for the root.
+     *
+     * Not quite a JSON Pointer: the pointer for a document root is the empty string, which reads as
+     * a missing path in a message. `'/'` is a display sentinel, so treat this as human-facing rather
+     * than as something to resolve against the payload.
+     */
+    path: string;
+    /** AJV's own message, e.g. `must NOT have additional properties`. */
+    message: string;
+    /** Undeclared property names at {@link path}, in the order AJV reported them. */
+    undeclared?: string[];
+}
+
+/**
+ * The failures, with all undeclared properties at a given path gathered into ONE issue.
+ *
+ * AJV reports `additionalProperties` per property, so a value carrying a whole foreign object —
+ * a Mongoose document that reached the response mapper unmapped, say — produces one error per own
+ * key and buries every other failure in the payload. Gathering is lossless: every name is kept, in
+ * the order AJV found it, on the issue for the path it belongs to.
+ */
+function collectIssues(validate: ValidateFunction): ApiValidationIssue[] {
+    const errors = validate.errors ?? [];
+    const undeclaredByPath = new Map<string, Set<string>>();
+    for (const error of errors) {
+        const additional = additionalProperty(error);
+        if (additional === undefined) continue;
         const where = error.instancePath || '/';
-        // AJV writes "must NOT have additional properties" and puts the offending key in `params`,
-        // so the message alone says a body is wrong without saying which property made it wrong.
-        // Every other keyword names its subject already — `required` quotes the missing property,
-        // `enum` and `type` describe the value in place — and this is the one a caller most often
-        // trips, so it is the one worth spelling out rather than reformatting all of them.
-        const additional = (error.params as { additionalProperty?: string } | undefined)?.additionalProperty;
-        return additional ? `${where} ${error.message}: ${additional}` : `${where} ${error.message}`;
-    });
+        const names = undeclaredByPath.get(where);
+        // A union whose branches all reject the same property reports it once per branch. The name
+        // is the same fact each time, so it is listed once.
+        if (names) names.add(additional);
+        else undeclaredByPath.set(where, new Set([additional]));
+    }
+
+    const gathered = new Set<string>();
+    const issues: ApiValidationIssue[] = [];
+    for (const error of errors) {
+        const path = error.instancePath || '/';
+        const message = error.message ?? 'is invalid';
+        if (additionalProperty(error) === undefined) {
+            issues.push({ path, message });
+            continue;
+        }
+        if (gathered.has(path)) continue;
+        gathered.add(path);
+        issues.push({ path, message, undeclared: [...(undeclaredByPath.get(path) ?? [])] });
+    }
+    return issues;
+}
+
+/**
+ * The complete rendering of one issue — every name, no budget.
+ *
+ * This is what gets logged. A caller-facing message renders from {@link ApiValidationIssue} itself
+ * with a length limit rather than shortening this string; see `reportableErrors` in the enforcer.
+ */
+export function renderApiValidationIssue(issue: ApiValidationIssue): string {
+    const head = `${issue.path} ${issue.message}`;
+    return issue.undeclared?.length ? `${head}: ${issue.undeclared.join(', ')}` : head;
+}
+
+/** The failed branch of every validator here, so the two views cannot be built inconsistently. */
+function invalidResult(validate: ValidateFunction): { valid: false; errors: string[]; issues: ApiValidationIssue[] } {
+    const issues = collectIssues(validate);
+    return { valid: false, errors: issues.map(renderApiValidationIssue), issues };
 }
 
-export type ValidateApiPayloadResult<T> = { valid: true; data: T } | { valid: false; errors: string[] };
+export type ValidateApiPayloadResult<T> =
+    | { valid: true; data: T }
+    /**
+     * `errors` is the rendered form, complete and ready to log; `issues` is the same failures with
+     * the property names still separable. Shorten from `issues`, never from `errors`.
+     */
+    | { valid: false; errors: string[]; issues: ApiValidationIssue[] };
 
 /**
  * Validates an untyped request body against the component the endpoint publishes.
@@ -3386,7 +3566,7 @@ export function validateApiRequest<N extends ApiComponentName>(
     if (validate(value)) {
         return { valid: true, data: value as ApiComponentType<N> };
     }
-    return { valid: false, errors: formatErrors(validate) };
+    return invalidResult(validate);
 }
 
 /**
@@ -3404,7 +3584,7 @@ export function validateApiResponse<N extends ApiComponentName>(
     if (validate(value)) {
         return { valid: true, data: value as ApiComponentType<N> };
     }
-    return { valid: false, errors: formatErrors(validate) };
+    return invalidResult(validate);
 }
 
 /**
@@ -3432,7 +3612,9 @@ export function pruneApiResponse<N extends ApiComponentName>(name: N, value: Api
     return pruneToSchema(value, { $ref: apiComponentRef(name) }, ApiSchemaComponents) as ApiComponentType<N>;
 }
 
-export type PruneAndValidateResult<T> = { valid: true; data: T } | { valid: false; data: unknown; errors: string[] };
+export type PruneAndValidateResult<T> =
+    | { valid: true; data: T }
+    | { valid: false; data: unknown; errors: string[]; issues: ApiValidationIssue[] };
 
 /**
  * Prunes an untyped payload and validates the result against the published component.
@@ -3453,7 +3635,7 @@ export function pruneAndValidateApiResponse<N extends ApiComponentName>(
     if (validate(pruned)) {
         return { valid: true, data: pruned as ApiComponentType<N> };
     }
-    return { valid: false, data: pruned, errors: formatErrors(validate) };
+    return { ...invalidResult(validate), data: pruned };
 }
 
 /**

package/src/api-schemas/store.contract.test.ts

@@ -131,6 +131,27 @@ describe.skipIf(!publishedDocument)('gate — generated artifact = canonical com
     });
 });
 
+describe('content object response classification', () => {
+    it('accepts the current sensitivity and compartments fields', () => {
+        const result = validateApiResponse('ContentObjectApiResponse', {
+            id: 'content-object-id',
+            name: 'Classified document',
+            updated_by: 'user-id',
+            created_by: 'user-id',
+            created_at: '2026-08-06T09:00:00.000Z',
+            updated_at: '2026-08-06T09:00:00.000Z',
+            location: '/',
+            status: 'completed',
+            properties: {},
+            revision: { root: 'content-object-id', head: true },
+            sensitivity: 3,
+            compartments: ['legal'],
+        });
+
+        expect(result).toMatchObject({ valid: true });
+    });
+});
+
 /**
  * Bodies that probe where the two validators could disagree.
  *

package/src/api-schemas/sts.contract.test.ts

@@ -4,6 +4,7 @@ import type {
     AgentTokenRequest,
     ApiKeyTokenRequest,
     EnvironmentTokenRequest,
+    IssueTokenForbiddenResponse,
     IssueTokenRequest,
     IssueTokenResponse,
     ProjectTokenRequest,
@@ -16,6 +17,7 @@ import type {
     AgentTokenRequestSchema,
     ApiKeyTokenRequestSchema,
     EnvironmentTokenRequestSchema,
+    IssueTokenForbiddenResponseSchema,
     IssueTokenRequestSchema,
     IssueTokenResponseSchema,
     ProjectTokenRequestSchema,
@@ -38,6 +40,7 @@ describe('STS canonical contracts', () => {
         assertType<Equals<ServiceAccountTokenRequest, z.infer<typeof ServiceAccountTokenRequestSchema>>>(true);
         assertType<Equals<IssueTokenRequest, z.infer<typeof IssueTokenRequestSchema>>>(true);
         assertType<Equals<IssueTokenResponse, z.infer<typeof IssueTokenResponseSchema>>>(true);
+        assertType<Equals<IssueTokenForbiddenResponse, z.infer<typeof IssueTokenForbiddenResponseSchema>>>(true);
         expect(true).toBe(true);
     });
 
@@ -60,9 +63,38 @@ describe('STS canonical contracts', () => {
         expect(validateApiRequest('IssueTokenRequest', { type: 'project', account_id: 'acc_1' }).valid).toBe(false);
     });
 
-    it('checks both documented response shapes', () => {
+    it('checks every documented response shape and forbidden error-code literal', () => {
         expect(validateApiResponse('IssueTokenResponse', { token: 'signed', token_type: 'Bearer' }).valid).toBe(true);
         expect(validateApiResponse('IssueTokenResponse', { token: 'signed', token_type: 'bearer' }).valid).toBe(false);
+        for (const errorCode of [
+            'requested_scope_unavailable',
+            'no_accessible_account',
+            'restricted_environment',
+            'token_issuance_forbidden',
+        ]) {
+            expect(
+                validateApiResponse('IssueTokenForbiddenResponse', {
+                    error: 'Forbidden',
+                    message: 'The requested scope is unavailable',
+                    errorCode,
+                }).valid,
+            ).toBe(true);
+        }
+        expect(
+            validateApiResponse('IssueTokenForbiddenResponse', {
+                error: 'Forbidden',
+                message: 'No',
+                errorCode: 'resource_not_found',
+            }).valid,
+        ).toBe(false);
+        expect(
+            validateApiResponse('IssueTokenForbiddenResponse', {
+                error: 'Forbidden',
+                message: 'No',
+                errorCode: 'requested_scope_unavailable',
+                project_id: 'secret',
+            }).valid,
+        ).toBe(false);
         expect(
             validateApiResponse('IssueTokenUnavailableResponse', {
                 error: 'Service Unavailable',

package/src/api-schemas/sts.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { ISSUE_TOKEN_FORBIDDEN_ERROR_CODES } from '../sts-errors.js';
 import { SystemRolesSchema } from './apikey.js';
 
 const ALGORITHM_DESCRIPTION = 'Signing algorithm - defaults to ES256. Use RS256 for Azure AD compatibility.';
@@ -105,6 +106,18 @@ export const IssueTokenResponseSchema = z
     })
     .meta({ id: 'IssueTokenResponse' });
 
+export const IssueTokenForbiddenResponseSchema = z
+    .strictObject({
+        error: z.string(),
+        message: z.string(),
+        errorCode: z.enum(ISSUE_TOKEN_FORBIDDEN_ERROR_CODES),
+    })
+    .meta({
+        id: 'IssueTokenForbiddenResponse',
+        description:
+            'A safe, machine-readable denial response. Requested resources are intentionally not identified or confirmed.',
+    });
+
 export const IssueTokenUnavailableResponseSchema = z
     .strictObject({ error: z.string(), message: z.string() })
     .meta({ id: 'IssueTokenUnavailableResponse' });