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

package/src/api-schemas/app-lifecycle.ts

@@ -180,6 +180,8 @@ export const AppPackageScopeSchema = z
         'settings',
         'widgets',
         'activities',
+        'hooks',
+        'subscriptions',
         'all',
     ])
     .meta({ id: 'AppPackageScope' });
@@ -324,6 +326,35 @@ export const DeleteAppVersionResponseSchema = z
     })
     .meta({ id: 'DeleteAppVersionResponse' });
 
+export const AppDeleteSummarySchema = z
+    .strictObject({
+        confirmed: z.boolean().meta({
+            description:
+                'Whether `?confirm=true` was sent. Without it the endpoint reports what WOULD be removed and ' +
+                'deletes nothing — `deleted` stays false.',
+        }),
+        app_id: z.string(),
+        app_name: z.string(),
+        versions: z.number().meta({ description: 'AppVersion records the cascade covers.' }),
+        installations: z.number().meta({ description: 'AppInstallation records the cascade covers.' }),
+        storage_prefix: z.string(),
+        git_repo_url: z.string().optional(),
+        deleted: z.boolean().meta({
+            description: 'Whether the app record itself was removed. False for a dry run.',
+        }),
+        warnings: z.array(z.string()).meta({
+            description:
+                'Cascade steps that failed without aborting the deletion. Credential cleanup is NOT among them — ' +
+                'a failed API key purge fails the request outright and keeps the app row.',
+        }),
+    })
+    .meta({
+        id: 'AppDeleteSummary',
+        description:
+            'Result of `DELETE /apps/:id`. Doubles as the dry-run preview: without `?confirm=true` the same ' +
+            'shape comes back with `deleted: false` describing what the cascade would remove.',
+    });
+
 export const AppRepoBranchSchema = z
     .strictObject({
         name: z.string(),
@@ -469,6 +500,28 @@ export const OAuthClientCredentialsMapSchema = z
 
 export const AppOAuthCollectionParamsSchema = OAuthClientCredentialsMapSchema.meta({ id: 'AppOAuthCollectionParams' });
 
+export const McpApiKeyCredentialSchema = z
+    .strictObject({
+        // Matches SetMcpApiKeyRequest, including the `\S` pattern — see the note there on why the
+        // trim alone does not survive into the AJV-enforced JSON Schema.
+        api_key: z
+            .string()
+            .trim()
+            .min(1)
+            .regex(/\S/, 'API key must not be blank')
+            .meta({
+                description:
+                    'The key the installer holds for this collection. Surrounding whitespace is stripped. Stored ' +
+                    'encrypted in the installing project and never returned.',
+            }),
+    })
+    .meta({ id: 'McpApiKeyCredential' });
+
+export const AppApiKeyCollectionParamsSchema = z
+    .object({})
+    .catchall(McpApiKeyCredentialSchema)
+    .meta({ id: 'AppApiKeyCollectionParams' });
+
 export const AppInspectionIssueSchema = z
     .strictObject({
         severity: z.enum(['error', 'warning']),
@@ -775,6 +828,12 @@ export const AppInstallationPayloadSchema = z
             description:
                 'OAuth credentials for named providers, keyed by the provider key from oauth_providers. Collected from the user at install time for providers with required_at_install. Separate from oauth_params to avoid key collisions between provider keys and collection ids.',
         }).optional(),
+        api_key_params: AppApiKeyCollectionParamsSchema.meta({
+            description:
+                "API keys for auth: 'api_key' collections, keyed by collection.id. Collected from the user at " +
+                'install time for collections with api_key_config.required_at_install. Each key is stored in the ' +
+                "installing project's encrypted secret store, replacing any key already held for that collection.",
+        }).optional(),
     })
     .meta({ id: 'AppInstallationPayload' });
 

package/src/api-schemas/app-runtime.ts

@@ -3,12 +3,15 @@
 import type { JSONSchema } from '@llumiverse/common';
 import { z } from 'zod';
 import type { CompositeAppMenuNavItem } from '../apps.js';
+import type { PlatformEvent } from '../platform-event.js';
 import type { InCodeProcessDefinition } from '../store/process.js';
+import { SystemRolesSchema } from './apikey.js';
 import {
     AgentToolDefinitionSchema,
     AppInstallationOAuthBindingSchema,
     AppInstallationProviderBindingSchema,
     AppVersionRecordSchema,
+    EventRefSchema,
 } from './app-lifecycle.js';
 import {
     AppAccessControlSchema,
@@ -19,12 +22,14 @@ import {
     MCPOAuthConfigSchema,
     ToolCollectionObjectSchema,
 } from './apps.js';
+import { AuditMeterSchema } from './audit-trail.js';
 import {
     DashboardDataSourceSchema,
     DashboardLayoutSchema,
     DashboardPanelSchema,
     DashboardQuerySchema,
 } from './dashboard.js';
+import { EventPrioritySchema, EventSubscriptionFilterSchema } from './events.js';
 import { StringValueMapSchema } from './files.js';
 import { RemoteActivityDefinitionSchema } from './integrations.js';
 import { CatalogInteractionRefSchema } from './interaction.js';
@@ -804,6 +809,99 @@ export const CompositeAppConfigSchema = z
             'CompositeApp shell configuration. This is the main configuration interface for storing CompositeApp settings. Used as the MongoDB model for persisting CompositeApp configurations.',
     });
 
+export const AppPackageEventHookSchema = z
+    .strictObject({
+        name: z.string().meta({ description: 'Registered event hook name.' }),
+        path: z.string().meta({ description: 'Authenticated endpoint that receives the event delivery envelope.' }),
+        description: z.string().meta({ description: 'Optional description of the event hook behavior.' }).optional(),
+    })
+    .meta({
+        id: 'AppPackageEventHook',
+        description: 'An authenticated event hook exposed by the app runtime.',
+    });
+
+export const AppPackageHooksSchema = z
+    .strictObject({
+        install: z.string().meta({ description: 'Authenticated endpoint for the app install hook.' }).optional(),
+        uninstall: z.string().meta({ description: 'Authenticated endpoint for the app uninstall hook.' }).optional(),
+        events: z
+            .array(AppPackageEventHookSchema)
+            .meta({ description: 'Named event hooks exposed by the app runtime.' })
+            .optional(),
+    })
+    .meta({
+        id: 'AppPackageHooks',
+        description:
+            'Lifecycle and event hooks exposed by the app runtime. Lifecycle entries are informational; Studio invokes their conventional sibling endpoints directly.',
+    });
+
+const AppEventHookPlatformEventSchema = EventRefSchema.extend({
+    timestamp: z.string(),
+    source: z.string(),
+    audit_trail: z.boolean().optional(),
+    replay_of: z.string().optional(),
+    replay_root_event_id: z.string().optional(),
+    replayed_by: z.string().optional(),
+    request_id: z.string().nullable().optional(),
+    status: z.number().optional(),
+    success: z.boolean().optional(),
+    principal_id: z.string().nullable().optional(),
+    principal_type: z.string().nullable().optional(),
+    effective_principal_id: z.string().nullable().optional(),
+    roles: z.array(z.string()).optional(),
+    account_name: z.string().nullable().optional(),
+    project_name: z.string().nullable().optional(),
+    provider: z.string().nullable().optional(),
+    meters: z.array(AuditMeterSchema).optional(),
+    resource_data: z.record(z.string(), z.unknown()).optional(),
+    resource_version: z.string().optional(),
+    details: z.record(z.string(), z.unknown()).optional(),
+}) satisfies z.ZodType<PlatformEvent>;
+
+export const AppEventHookDeliverySchema = z
+    .strictObject({
+        id: z.string().meta({ description: 'Event-delivery intent id.' }),
+        subscription_id: z.string().meta({ description: 'Event subscription id.' }),
+        attempt: z.number().finite().meta({ description: 'Current delivery attempt number.' }),
+    })
+    .meta({
+        id: 'AppEventHookDelivery',
+        description: 'Delivery metadata accompanying an app event-hook invocation.',
+    });
+
+export const AppEventHookPayloadSchema = z
+    .strictObject({
+        event: AppEventHookPlatformEventSchema,
+        delivery: AppEventHookDeliverySchema,
+    })
+    .meta({
+        id: 'AppEventHookPayload',
+        description: 'Canonical platform event envelope delivered to an authenticated app event hook.',
+    });
+
+export const AppEventSubscriptionDefinitionSchema = z
+    .strictObject({
+        id: z
+            .string()
+            .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+            .meta({ description: 'Stable app-local subscription id in kebab case.' }),
+        name: z.string().meta({ description: 'Human-readable subscription name.' }),
+        description: z.string().meta({ description: 'Optional description of the subscription behavior.' }).optional(),
+        hook: z.string().meta({ description: 'Name of an event hook registered by the same app package.' }),
+        filter: EventSubscriptionFilterSchema,
+        run_as_role: SystemRolesSchema.meta({
+            description:
+                'Identity used for event delivery. Use automation for the standard event-triggered execution identity.',
+        }),
+        enabled: z.boolean().meta({ description: 'Whether the installed subscription is enabled.' }).optional(),
+        priority: EventPrioritySchema.meta({ description: 'Delivery priority for matching events.' }).optional(),
+    })
+    .meta({
+        id: 'AppEventSubscriptionDefinition',
+        description:
+            'An app-owned event subscription. Studio derives its project scope and delivery target from the app installation and referenced event hook.',
+    });
+
 export const AppPackageSchema = z
     .strictObject({
         ui: AppUIConfigSchema.meta({ description: 'The UI configuration of the app' }).optional(),
@@ -850,6 +948,11 @@ export const AppPackageSchema = z
         settings_schema: JSONSchemaRefSchema.meta({
             description: 'A JSON chema for the app installation settings.',
         }).optional(),
+        hooks: AppPackageHooksSchema.optional(),
+        subscriptions: z
+            .array(AppEventSubscriptionDefinitionSchema)
+            .meta({ description: 'Event subscriptions contributed by the app.' })
+            .optional(),
     })
     .meta({ id: 'AppPackage' });
 

package/src/api-schemas/apps.ts

@@ -112,9 +112,13 @@ export const AppUIConfigSchema = z
     })
     .meta({ id: 'AppUIConfig' });
 
-export const ToolCollectionAuthTypeSchema = z
-    .enum(['oauth', 'other'])
-    .meta({ id: 'ToolCollectionAuthType', description: 'Authentication type for tool collections' });
+export const ToolCollectionAuthTypeSchema = z.enum(['oauth', 'api_key', 'other']).meta({
+    id: 'ToolCollectionAuthType',
+    description:
+        "Authentication type for tool collections.\n- 'oauth': the runtime resolves a per-user or per-project " +
+        "OAuth access token\n- 'api_key': a static key held in the project's secret store is sent as the RFC 6750 " +
+        'bearer token (`Authorization: Bearer <key>`)',
+});
 
 export const MCPOAuthConfigSchema = z
     .strictObject({
@@ -162,6 +166,33 @@ export const MCPOAuthConfigSchema = z
             'oauth_bindings on AppInstallation.',
     });
 
+export const MCPApiKeyConfigSchema = z
+    .strictObject({
+        required_at_install: z
+            .boolean()
+            .optional()
+            .meta({
+                description:
+                    'When true, the installer must supply the key in the install dialog. Use this for a manifest ' +
+                    'published to projects that each hold their own key. Leave unset when the key was already ' +
+                    'stored by whoever registered the server.',
+            }),
+        instructions: z
+            .string()
+            .optional()
+            .meta({
+                description:
+                    'Shown in the install dialog above the key field — typically where to generate the key on the ' +
+                    'remote service.',
+            }),
+    })
+    .meta({
+        id: 'MCPApiKeyConfig',
+        description:
+            "Install-time provisioning blueprint for an `auth: 'api_key'` MCP collection. Declares whether the " +
+            'installer is prompted for the key. Never holds the key itself — manifests are shareable documents.',
+    });
+
 /**
  * The two collection kinds share a base interface, so their published components both begin with
  * `url` and `auth`. Spreading one shape is what keeps that true of the emission as well.
@@ -211,6 +242,11 @@ export const MCPToolCollectionObjectSchema = z
                 'required_at_install params. The created app is recorded in AppInstallation.oauth_bindings. ' +
                 'Mutually exclusive with oauth_provider.',
         }),
+        api_key_config: MCPApiKeyConfigSchema.optional().meta({
+            description:
+                "Install-time provisioning blueprint for auth: 'api_key' collections. Only meaningful alongside " +
+                "auth: 'api_key'; ignored otherwise.",
+        }),
         oauth_provider: z
             .string()
             .optional()
@@ -371,6 +407,39 @@ export const McpOAuthTokenRequestSchema = z
     })
     .meta({ id: 'McpOAuthTokenRequest' });
 
+export const SetMcpApiKeyRequestSchema = z
+    .strictObject({
+        // `.regex(/\S/)` rather than `.trim().min(1)` alone: request bodies are validated by AJV
+        // against the EMITTED JSON Schema, where a Zod transform like `.trim()` leaves no trace —
+        // `minLength: 1` on its own happily accepts "   ". The pattern emits and is enforced, so a
+        // whitespace-only key is rejected at the boundary instead of becoming an encrypted empty
+        // key that still reports `configured: true`. The trim still normalizes for Zod consumers.
+        api_key: z
+            .string()
+            .trim()
+            .min(1)
+            .regex(/\S/, 'API key must not be blank')
+            .meta({
+                description:
+                    'The static key issued by the remote MCP server. Surrounding whitespace is stripped. Stored ' +
+                    'encrypted in the project secret store and sent as the RFC 6750 bearer token on every request ' +
+                    'to the collection URL. Never returned by the API.',
+            }),
+    })
+    .meta({ id: 'SetMcpApiKeyRequest' });
+
+export const McpApiKeyStatusSchema = z
+    .strictObject({
+        configured: z.boolean().meta({ description: 'Whether a key is stored for this collection.' }),
+        // Always present — null when unset, never absent. `.nullable()` rather than `.nullish()`
+        // so the published contract says so and generated clients do not treat it as optional.
+        hint: z
+            .string()
+            .nullable()
+            .meta({ description: 'Last few characters of the stored key, for display only. Null when unset.' }),
+    })
+    .meta({ id: 'McpApiKeyStatus', description: 'Whether an API key is configured for an MCP tool collection' });
+
 export const OAuthAuthStatusSchema = z
     .strictObject({
         collection_id: z.string(),

package/src/api-schemas/content.ts

@@ -787,6 +787,19 @@ export const ContentObjectApiResponseSchema = z
         parts_etag: z.string().optional(),
         transcript: z.looseObject({}).optional(),
         security: StringArrayMapSchema.optional(),
+        sensitivity: z
+            .number()
+            .meta({
+                description:
+                    'BLP sensitivity level — set directly or inherited from collections (max across collections).',
+            })
+            .optional(),
+        compartments: z
+            .array(z.string())
+            .meta({
+                description: 'Compartments — set directly or inherited from collections (union across collections).',
+            })
+            .optional(),
         inherited_properties: z.array(InheritedPropertyMetadataSchema).optional(),
     })
     .meta({ id: 'ContentObjectApiResponse' });

package/src/api-schemas/events.ts

@@ -184,6 +184,17 @@ export const WebhookEventDeliveryTargetSchema = z
     })
     .meta({ id: 'WebhookEventDeliveryTarget' });
 
+export const AppEventDeliveryTargetSchema = z
+    .strictObject({
+        type: z.literal('app'),
+        app_id: z.string(),
+        installation_id: z.string(),
+        hook: z.string(),
+        url: z.string(),
+        timeout_ms: z.number().optional(),
+    })
+    .meta({ id: 'AppEventDeliveryTarget' });
+
 export const WorkflowEventDeliveryTargetSchema = z
     .strictObject({
         type: z.literal('workflow'),
@@ -432,6 +443,17 @@ export const WebhookEventDeliveryTargetInputSchema = z
     })
     .meta({ id: 'WebhookEventDeliveryTargetInput' });
 
+export const AppEventDeliveryTargetInputSchema = z
+    .strictObject({
+        type: z.literal('app'),
+        app_id: z.string(),
+        installation_id: z.string(),
+        hook: z.string(),
+        url: z.string(),
+        timeout_ms: z.number().optional(),
+    })
+    .meta({ id: 'AppEventDeliveryTargetInput' });
+
 export const WorkflowEventDeliveryTargetInputSchema = z
     .strictObject({
         type: z.literal('workflow'),
@@ -615,7 +637,7 @@ export const EventDeliveryQueueSubscriptionSummarySchema = z
     .strictObject({
         subscription_id: z.string(),
         subscription_name: z.string(),
-        target_type: z.enum(['workflow', 'webhook', 'agent', 'process']),
+        target_type: z.enum(['workflow', 'webhook', 'app', 'agent', 'process']),
         total: z.number(),
         queued: z.number(),
         deferred: z.number(),
@@ -632,12 +654,45 @@ export const EventDeliveryQueueSubscriptionSummarySchema = z
 export const EventDeliveryQueueSummaryPayloadSchema = z
     .strictObject({
         subscription_id: z.string().optional(),
-        target_type: z.array(z.enum(['workflow', 'webhook', 'agent', 'process'])).optional(),
+        target_type: z.array(z.enum(['workflow', 'webhook', 'app', 'agent', 'process'])).optional(),
         sort_by: EventDeliveryQueueSortFieldSchema.optional(),
         sort_order: z.enum(['asc', 'desc']).optional(),
     })
     .meta({ id: 'EventDeliveryQueueSummaryPayload' });
 
+export const CancelEventDeliveryIntentsPayloadSchema = z
+    .strictObject({
+        subscription_id: z
+            .string()
+            .min(1)
+            .meta({ description: 'Restrict cancellation to one subscription.' })
+            .optional(),
+        target_type: z
+            .array(z.enum(['workflow', 'webhook', 'app', 'agent', 'process']))
+            .min(1)
+            .meta({ description: 'Restrict cancellation to one or more delivery target types.' })
+            .optional(),
+    })
+    .meta({ id: 'CancelEventDeliveryIntentsPayload' });
+
+export const CancelEventDeliveryIntentsResponseSchema = z
+    .strictObject({
+        environment: z.string().meta({ description: 'Deployment environment whose queue was changed.' }),
+        cleared_through: z.string().meta({
+            description: 'Server-side watermark; intents created after this time were not changed.',
+            format: 'date-time',
+        }),
+        cancelled: z
+            .number()
+            .int()
+            .nonnegative()
+            .meta({ description: 'Pending or retrying intents moved to the cancelled terminal state.' }),
+        active_untouched: z.number().int().nonnegative().meta({
+            description: 'Matching evaluating, starting, or running intents left for normal reconciliation.',
+        }),
+    })
+    .meta({ id: 'CancelEventDeliveryIntentsResponse' });
+
 export const EventIngestChannelMutationResponseSchema = z
     .strictObject({
         channel: EventIngestChannelSchema,
@@ -724,7 +779,7 @@ export const EventDeliveryIntentSummarySchema = z
         event_id: z.string(),
         subscription_id: z.string(),
         subscription_name: z.string(),
-        target_type: z.enum(['workflow', 'webhook', 'agent', 'process']),
+        target_type: z.enum(['workflow', 'webhook', 'app', 'agent', 'process']),
         workflow_class: nullableStringSchema.optional(),
         priority: EventPrioritySchema,
         status: EventDeliveryIntentStatusSchema,
@@ -812,6 +867,7 @@ export const EventDeliveryTargetSchema: z.ZodType = z
     .discriminatedUnion('type', [
         WorkflowEventDeliveryTargetSchema,
         WebhookEventDeliveryTargetSchema,
+        AppEventDeliveryTargetSchema,
         AgentEventDeliveryTargetSchema,
         z.lazy(() => ProcessEventDeliveryTargetSchema) as unknown as z.ZodObject,
     ])
@@ -821,6 +877,7 @@ export const EventDeliveryTargetInputSchema: z.ZodType = z
     .discriminatedUnion('type', [
         WorkflowEventDeliveryTargetInputSchema,
         WebhookEventDeliveryTargetInputSchema,
+        AppEventDeliveryTargetInputSchema,
         AgentEventDeliveryTargetSchema,
         z.lazy(() => ProcessEventDeliveryTargetSchema) as unknown as z.ZodObject,
     ])
@@ -841,6 +898,9 @@ export const EventSubscriptionSchema: z.ZodType = z
         protected: z.boolean(),
         enabled: z.boolean(),
         priority: EventPrioritySchema.optional(),
+        app_installation_id: z.string().optional(),
+        app_id: z.string().optional(),
+        app_subscription_id: z.string().optional(),
         created_by: z.string().optional(),
         updated_by: z.string().optional(),
         created_at: z.string().optional(),

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

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import type { AsyncConversationExecutionPayload } from '../interaction.js';
+import { AsyncConversationExecutionPayloadSchema } from './interaction.js';
+
+describe('AsyncConversationExecutionPayload contract', () => {
+    it('retains an immutable app-version execution target', () => {
+        const payload: AsyncConversationExecutionPayload = {
+            type: 'conversation',
+            interaction: 'sys:AppTester',
+            app_version: '20260804T022611971Z',
+        };
+
+        expect(AsyncConversationExecutionPayloadSchema.parse(payload)).toMatchObject({
+            app_version: '20260804T022611971Z',
+        });
+    });
+
+    it('rejects a non-string app-version target', () => {
+        expect(() =>
+            AsyncConversationExecutionPayloadSchema.parse({
+                type: 'conversation',
+                interaction: 'sys:AppTester',
+                app_version: 42,
+            }),
+        ).toThrow();
+    });
+});

package/src/api-schemas/interaction.ts

@@ -1996,6 +1996,13 @@ export const AsyncConversationExecutionPayloadSchema = z
             description:
                 'The interaction name and suffixed by an optional tag or version separated from the name using a @ character If no version/tag part is specified then the latest version is used. Example: ReviewContract, ReviewContract@draft, ReviewContract@1, ReviewContract@some-tag',
         }),
+        app_version: z
+            .string()
+            .meta({
+                description:
+                    'Immutable app-version target inherited by this conversation execution. The workflow applies it to app-owned resource resolution; callers normally set the x-vertesia-app-version header instead of populating this field directly.',
+            })
+            .optional(),
         data: z
             .unknown()
             .meta({

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,
+        );
+    });
+});