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

package/src/api-schemas/sts.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { SystemRolesSchema } from './apikey.js';
+
+const ALGORITHM_DESCRIPTION = 'Signing algorithm - defaults to ES256. Use RS256 for Azure AD compatibility.';
+
+export const TokenTypeSchema = z.enum(['apikey', 'user', 'project', 'environment', 'agent', 'service_account']);
+
+export const SigningAlgorithmSchema = z.enum(['ES256', 'RS256']).meta({ id: 'SigningAlgorithm' });
+
+const baseTokenRequestShape = {
+    audience: z.string().optional(),
+    algorithm: SigningAlgorithmSchema.meta({ description: ALGORITHM_DESCRIPTION }).optional(),
+};
+
+export const ApiKeyTokenRequestSchema = z
+    .strictObject({
+        type: z.literal('apikey'),
+        ...baseTokenRequestShape,
+        key: z.string(),
+    })
+    .meta({ id: 'ApiKeyTokenRequest', required: ['key', 'type'] });
+
+export const UserTokenRequestSchema = z
+    .strictObject({
+        type: z.literal('user'),
+        ...baseTokenRequestShape,
+        user_id: z.string().optional(),
+        account_id: z.string().optional(),
+        project_id: z.string().optional(),
+        expires_at: z.number().optional(),
+        on_behalf_of: z.string().optional(),
+    })
+    .meta({ id: 'UserTokenRequest' });
+
+export const ProjectTokenRequestSchema = z
+    .strictObject({
+        type: z.literal('project'),
+        ...baseTokenRequestShape,
+        project_id: z.string(),
+        account_id: z.string(),
+    })
+    .meta({ id: 'ProjectTokenRequest', required: ['account_id', 'project_id', 'type'] });
+
+export const EnvironmentTokenRequestSchema = z
+    .strictObject({
+        type: z.literal('environment'),
+        ...baseTokenRequestShape,
+        environment_id: z.string(),
+        environment_name: z.string(),
+        project_id: z.string(),
+        account_id: z.string(),
+    })
+    .meta({
+        id: 'EnvironmentTokenRequest',
+        required: ['account_id', 'environment_id', 'environment_name', 'project_id', 'type'],
+    });
+
+export const AgentTokenRequestSchema = z
+    .strictObject({
+        type: z.literal('agent'),
+        ...baseTokenRequestShape,
+        account_id: z.string(),
+        project_id: z.string(),
+        name: z.string().optional(),
+        on_behalf_of: z.string().meta({
+            description:
+                'User information.\n\nThe value of this field can be either:   - a signed Vertesia token used to verify the user context   - a user ID prefixed with `user:` to indicate the user on behalf of whom the agent is     acting.',
+        }),
+    })
+    .meta({
+        id: 'AgentTokenRequest',
+        required: ['account_id', 'on_behalf_of', 'project_id', 'type'],
+        description:
+            'Agent token for a service account to act as agent on behalf of a user.\n\nTwo trust paths are supported:\n\n- `user_access_token`: a live signed Vertesia token. STS verifies the user context from that token.\n- `workload_id_token`: a workload acts on behalf of a user. It implies that a full verification   will be performed based on the workload identity.',
+    });
+
+export const ServiceAccountTokenRequestSchema = z
+    .strictObject({
+        type: z.literal('service_account'),
+        ...baseTokenRequestShape,
+        account_id: z.string(),
+        project_id: z.string(),
+        roles: z.array(SystemRolesSchema).optional(),
+        name: z.string().optional(),
+        email: z.string().optional(),
+    })
+    .meta({ id: 'ServiceAccountTokenRequest', required: ['account_id', 'project_id', 'type'] });
+
+export const IssueTokenRequestSchema = z
+    .discriminatedUnion('type', [
+        ApiKeyTokenRequestSchema,
+        UserTokenRequestSchema,
+        ProjectTokenRequestSchema,
+        EnvironmentTokenRequestSchema,
+        AgentTokenRequestSchema,
+        ServiceAccountTokenRequestSchema,
+    ])
+    .meta({ id: 'IssueTokenRequest' });
+
+export const IssueTokenResponseSchema = z
+    .strictObject({
+        token: z.string(),
+        token_type: z.literal('Bearer'),
+        expires_in: z.number().optional(),
+    })
+    .meta({ id: 'IssueTokenResponse' });
+
+export const IssueTokenUnavailableResponseSchema = z
+    .strictObject({ error: z.string(), message: z.string() })
+    .meta({ id: 'IssueTokenUnavailableResponse' });

package/src/api-schemas/task.ts

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+
+export const CompleteTaskPayloadSchema = z
+    .strictObject({
+        result: z.looseObject({}),
+    })
+    .meta({ id: 'CompleteTaskPayload' });
+
+export const TaskFieldTypeSchema = z
+    .enum(['string', 'number', 'boolean', 'select', 'text'])
+    .meta({ id: 'TaskFieldType' });
+
+export const DurableTaskStatusSchema = z.enum(['pending', 'in_progress', 'completed', 'cancelled']).meta({
+    id: 'DurableTaskStatus',
+    description: 'Durable human task types used by process human_task nodes and agent asks.',
+});
+
+export const TaskSourceSchema = z
+    .strictObject({
+        type: z.enum(['process', 'agent']),
+        run_id: z.string(),
+        node: z.string().optional(),
+        ask_id: z.string().optional(),
+    })
+    .meta({ id: 'TaskSource' });
+
+export const TaskFieldSchema = z
+    .strictObject({
+        name: z.string(),
+        type: TaskFieldTypeSchema,
+        required: z.boolean().optional(),
+        label: z.string().optional(),
+        options: z.array(z.string()).optional(),
+        default: z.unknown().optional(),
+    })
+    .meta({ id: 'TaskField' });
+
+export const CreateTaskPayloadSchema = z
+    .strictObject({
+        title: z.string(),
+        description: z.string().optional(),
+        assignee: z.string().optional(),
+        fields: z.array(TaskFieldSchema).optional(),
+        source: TaskSourceSchema,
+        due_at: z.string().meta({ format: 'date-time' }).optional(),
+    })
+    .meta({ id: 'CreateTaskPayload' });
+
+export const TaskSchema = z
+    .strictObject({
+        id: z.string(),
+        account: z.string(),
+        project: z.string(),
+        title: z.string(),
+        description: z.string().optional(),
+        status: DurableTaskStatusSchema,
+        assignee: z.string().optional(),
+        fields: z.array(TaskFieldSchema),
+        result: z.looseObject({}).optional(),
+        source: TaskSourceSchema,
+        due_at: z.string().meta({ format: 'date-time' }).optional(),
+        created_at: z.string().meta({ format: 'date-time' }),
+        completed_at: z.string().meta({ format: 'date-time' }).optional(),
+        updated_at: z.string().meta({ format: 'date-time' }).optional(),
+    })
+    .meta({ id: 'Task' });
+
+export const UpdateTaskPayloadSchema = z
+    .strictObject({
+        title: z.string().optional(),
+        description: z.string().optional(),
+        status: DurableTaskStatusSchema.optional(),
+        assignee: z.string().nullable().optional(),
+        fields: z.array(TaskFieldSchema).optional(),
+        due_at: z.union([z.string().meta({ format: 'date-time' }), z.null()]).optional(),
+    })
+    .meta({ id: 'UpdateTaskPayload' });
+
+export const TaskArraySchema = z.array(TaskSchema).meta({ id: 'TaskArray' });
+
+/**
+ * The `GET /tasks` query contract.
+ *
+ * `source_type` reuses `TaskSourceSchema.shape.type` rather than restating `'process' | 'agent'`.
+ * The scanner-opacity problem that forced spelling it out in TypeScript was specific to
+ * `TaskSource['type']`: an indexed access into a canonical alias reads as nothing to a scanner that
+ * works from source text, and the parameter silently vanished from the published operation. Zod is a
+ * value, so reaching into its shape is an ordinary property read and the enum arrives intact.
+ *
+ * `status` is published as a single `type: array` parameter with `explode: true` — the scanner
+ * collapses `X | X[]` that way, because repeated keys are the only serialization OpenAPI has for it.
+ * The runtime additionally accepts the comma-joined spelling the SDK emits; see `commaSafeEnum` in
+ * `./parameters.js` for why that is safe for an enum specifically.
+ */
+export const ListTasksQuerySchema = z
+    .strictObject({
+        status: z.union([DurableTaskStatusSchema, z.array(DurableTaskStatusSchema)]).optional(),
+        assignee: z.string().optional(),
+        run_id: z.string().optional(),
+        source_type: TaskSourceSchema.shape.type.optional(),
+        limit: z.number().optional(),
+        offset: z.number().optional(),
+    })
+    .meta({ id: 'ListTasksQuery' });

package/src/api-schemas/tools.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+import { MCPToolAnnotationsSchema } from './apps.js';
+
+// The unified project-scoped tool registry as `GET /tools` and `POST /tools/validate` publish it.
+//
+// `//` rather than `/** */` throughout: a JSDoc block immediately preceding an exported declaration
+// is picked up by the OpenAPI scanner and published as that component's `description`, which would
+// double up with the `description` stated in `.meta()`.
+
+export const ToolSourceSchema = z.enum(['builtin', 'app', 'interaction']).meta({
+    id: 'ToolSource',
+    description:
+        'Origin of a tool in the unified project-scoped tool registry.\n\n- `builtin`: anything statically registered on the worker — workflow builtins, studio agent tools, and sys skills\n- `app`: tools contributed by an installed app for the project\n- `interaction`: a project interaction exposed via `tag=tool` / `is_tool=true` / `is_skill=true`\n\nSkill semantics (the tool unlocks others when invoked) are NOT part of the source. They are identified universally by the `learn_` prefix in the tool name. This matches how the runtime registry stores them and avoids splitting one logical origin into two sources.',
+});
+
+export const ValidateToolNamesPayloadSchema = z
+    .strictObject({
+        names: z.array(z.string()).meta({
+            description:
+                'Bare tool names as they appear in `agent_runner_options.tool_names`. `+`/`-` prefixes are stripped before lookup.',
+        }),
+    })
+    .meta({ id: 'ValidateToolNamesPayload', description: 'Request payload for `POST /tools/validate`.' });
+
+export const ToolValidationResultSchema = z
+    .strictObject({
+        name: z.string().meta({ description: 'The name the caller asked about.' }),
+        valid: z
+            .boolean()
+            .meta({ description: "True if the name resolves to exactly one tool in the project's unified registry." }),
+        source: ToolSourceSchema.meta({ description: 'When `valid`: which source the tool came from.' }).optional(),
+        app_install_id: z
+            .string()
+            .meta({ description: "When `valid` and `source === 'app'`: the app installation that provides the tool." })
+            .optional(),
+        app_name: z
+            .string()
+            .meta({ description: "When `valid` and `source === 'app'`: the app's manifest name." })
+            .optional(),
+        suggestion: z
+            .string()
+            .meta({
+                description:
+                    'When `!valid` and a close match exists: the suggested replacement name (Levenshtein-based).',
+            })
+            .optional(),
+        collisions: z
+            .array(
+                z.strictObject({
+                    source: ToolSourceSchema,
+                    app_install_id: z.string().optional(),
+                }),
+            )
+            .meta({
+                description:
+                    'Populated when a name appears in more than one source. Validation does not fail on this, but exposes the ambiguity so callers can surface a warning (last-write-wins resolution applies).',
+            })
+            .optional(),
+    })
+    .meta({ id: 'ToolValidationResult', description: 'Per-name resolution result for `POST /tools/validate`.' });
+
+export const AggregatedToolSchema = z
+    .strictObject({
+        name: z.string().meta({
+            description:
+                'Name as referenced from `agent_runner_options.tool_names`. For interaction skills this is `learn_<endpoint>`.',
+        }),
+        source: ToolSourceSchema,
+        description: z.string().optional(),
+        title: z.string().optional(),
+        is_default: z
+            .boolean()
+            .meta({
+                description:
+                    'Whether the tool is part of the default toolkit when no explicit `tool_names` is provided.',
+            })
+            .optional(),
+        annotations: MCPToolAnnotationsSchema.optional(),
+        unlocked_tools: z
+            .array(z.string())
+            .meta({ description: 'For skills (`learn_*`): tool names this skill unlocks when invoked.' })
+            .optional(),
+        app_install_id: z
+            .string()
+            .meta({ description: "Present when `source === 'app'`: the app installation that provides this tool." })
+            .optional(),
+        app_name: z
+            .string()
+            .meta({
+                description:
+                    "Present when `source === 'app'`: the app's manifest name (used for `principal.apps` filtering).",
+            })
+            .optional(),
+        interaction_id: z
+            .string()
+            .meta({ description: "Present when `source === 'interaction'`: the interaction document id." })
+            .optional(),
+        is_agent: z
+            .boolean()
+            .meta({
+                description:
+                    "Present when `source === 'interaction'`: true if the interaction has `agent_runner_options.is_agent === true`. Lets UI consumers distinguish sub-agents (autonomous, run-to-completion) from regular interaction tools.",
+            })
+            .optional(),
+    })
+    .meta({
+        id: 'AggregatedTool',
+        description:
+            'A single tool entry in the unified registry, regardless of where it came from. Returned by `GET /tools` and the resolution map of `POST /tools/validate`.',
+    });
+
+export const ValidateToolNamesResponseSchema = z
+    .strictObject({
+        results: z
+            .array(ToolValidationResultSchema)
+            .meta({ description: 'One entry per requested name, in the same order.' }),
+        invalid_count: z.number().min(0).meta({
+            description: 'Convenience count of `results.filter(r => !r.valid).length`.',
+            // `type`/`format` in meta rather than `z.int()`: the latter also emits Zod's
+            // safe-integer `maximum`, which the published component does not carry.
+            type: 'integer',
+            format: 'int32',
+        }),
+    })
+    .meta({ id: 'ValidateToolNamesResponse', description: 'Response from `POST /tools/validate`.' });
+
+export const AggregatedToolArraySchema = z.array(AggregatedToolSchema).meta({ id: 'AggregatedToolArray' });
+
+// Query contracts are registry components even though the scanner expands them into parameters.
+export const ListProjectToolsQuerySchema = z
+    .strictObject({
+        sources: z.array(ToolSourceSchema).meta({ description: 'Include only these sources.' }).optional(),
+        exclude: z
+            .array(ToolSourceSchema)
+            .meta({
+                description: 'Drop these sources from the result (and skip their fetch). Applied after `sources`.',
+            })
+            .optional(),
+    })
+    .meta({ id: 'ListProjectToolsQuery' });

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

@@ -0,0 +1,191 @@
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { describe, expect, it } from 'vitest';
+import type { PrincipalContext, PrincipalIdentity } from '../principal-context.js';
+import type { UpdateUserPayload, User } from '../user.js';
+import type { JsonObject } from './adapter.js';
+import { ApiSchemaComponents, apiComponentRef, validateApiRequest, validateApiResponse } from './registry.js';
+import type { PrincipalContextFromSchema, UserArrayFromSchema } from './user.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 {}
+
+function compile(name: string, components: Readonly<Record<string, JsonObject>> = ApiSchemaComponents) {
+    const ajv = new Ajv2020({ strictSchema: false, allErrors: true });
+    ajv.addSchema({ $id: 'vertesia://openapi', components: { schemas: components } });
+    return ajv.compile({ $ref: `vertesia://openapi${apiComponentRef(name as never)}` });
+}
+
+const VALID_USER = {
+    id: 'u1',
+    email: 'someone@acme.com',
+    name: 'Someone',
+    created_at: '2026-07-30T10:00:00.000Z',
+    updated_at: '2026-07-30T10:00:00.000Z',
+};
+
+describe('gate 1 — the schema is the single source of truth for the public IAM types', () => {
+    it('publishes the exact schema-derived type, not a hand-written twin', () => {
+        assertType<Equals<UserArrayFromSchema, User[]>>(true);
+        assertType<Equals<PrincipalContext, PrincipalContextFromSchema>>(true);
+        expect(true).toBe(true);
+    });
+
+    it('derives the inherited principal fields rather than restating them', () => {
+        // PrincipalIdentity used to `extends PrincipalContext`, so composing the schemas is what
+        // keeps the five inherited fields from becoming a twin one level down — the failure mode
+        // this batch was scoped to avoid.
+        assertType<Equals<PrincipalIdentity['clearance'], PrincipalContext['clearance']>>(true);
+        assertType<Equals<PrincipalIdentity['compartments'], PrincipalContext['compartments']>>(true);
+        assertType<Equals<PrincipalIdentity['email'], PrincipalContext['email']>>(true);
+        assertType<Equals<PrincipalIdentity['tags'], PrincipalContext['tags']>>(true);
+        assertType<Equals<PrincipalIdentity['properties'], PrincipalContext['properties']>>(true);
+        assertType<Equals<PrincipalIdentity['id'], string>>(true);
+        expect(true).toBe(true);
+    });
+
+    it('derives the update payload from the user rather than restating nine fields', () => {
+        // A `.pick()` of UserSchema plus `.partial()`: the field types and constraints come from the
+        // response declaration, and the ONLY thing the payload changes about them is requiredness.
+        assertType<Equals<UpdateUserPayload['name'], string | undefined>>(true);
+        assertType<Equals<UpdateUserPayload['clearance'], User['clearance']>>(true);
+        assertType<Equals<UpdateUserPayload['compartments'], User['compartments']>>(true);
+        assertType<Equals<UpdateUserPayload['properties'], User['properties']>>(true);
+        // What is NOT picked is the whitelist. `email`, `source`, `annotations` and the timestamps
+        // are server- or IdP-owned, and adding one now means naming it in the pick.
+        assertType<
+            Equals<
+                keyof UpdateUserPayload,
+                | 'name'
+                | 'username'
+                | 'picture'
+                | 'language'
+                | 'phone'
+                | 'last_selected_account'
+                | 'properties'
+                | 'clearance'
+                | 'compartments'
+            >
+        >(true);
+        expect(true).toBe(true);
+    });
+
+    it('keeps the wire type optionality the document declares', () => {
+        assertType<Equals<User['email'], string>>(true);
+        assertType<Equals<User['created_at'], string>>(true);
+        assertType<Equals<User['source'], 'firebase' | 'scim' | undefined>>(true);
+        assertType<Equals<User['clearance'], number | undefined>>(true);
+        expect(true).toBe(true);
+    });
+});
+
+describe('gate 2 — the published components match the closure the types come from', () => {
+    it('does not hoist PrincipalContext into a component of its own', () => {
+        // It is a public TYPE but has never been a published component. Hoisting it would add a
+        // $ref to PrincipalIdentity that every generated client would have to follow.
+        expect(Object.keys(ApiSchemaComponents)).not.toContain('PrincipalContext');
+        const props = ApiSchemaComponents.PrincipalIdentity.properties as Record<string, JsonObject>;
+        expect(props.clearance).toEqual({ type: 'number' });
+        expect(props.id).toEqual({ type: 'string' });
+    });
+
+    it('publishes the composed property order, id last', () => {
+        // `.extend()` appends, which is what `interface … extends …` produced and what the document
+        // already carries.
+        const props = ApiSchemaComponents.PrincipalIdentity.properties as JsonObject;
+        expect(Object.keys(props)).toEqual(['clearance', 'compartments', 'email', 'tags', 'properties', 'id']);
+    });
+
+    it('declares the timestamps the endpoint has always shipped', () => {
+        // The published component was closed and did not declare these, while the handler
+        // serialized the whole Mongo document — so every response violated its own schema.
+        const props = ApiSchemaComponents.User.properties as Record<string, JsonObject>;
+        expect(props.created_at.type).toBe('string');
+        expect(props.updated_at.type).toBe('string');
+        expect(ApiSchemaComponents.User.required).toContain('created_at');
+        expect(ApiSchemaComponents.User.additionalProperties).toBe(false);
+    });
+});
+
+describe('gate 3 — AJV validates the same canonical objects that are published', () => {
+    it('accepts a minimal user and rejects a missing required field', () => {
+        const validate = compile('User');
+        expect(validate(VALID_USER)).toBe(true);
+        const { created_at: _dropped, ...incomplete } = VALID_USER;
+        expect(validate(incomplete)).toBe(false);
+    });
+
+    it('rejects a source outside the published enum', () => {
+        expect(compile('User')({ ...VALID_USER, source: 'ldap' })).toBe(false);
+        expect(compile('User')({ ...VALID_USER, source: 'scim' })).toBe(true);
+    });
+
+    it('rejects an undeclared property on the closed user component', () => {
+        // Specifically the internal fields a spread of the Mongo document would have leaked.
+        expect(compile('User')({ ...VALID_USER, _id: 'deadbeef' })).toBe(false);
+    });
+
+    it('accepts an empty update payload but rejects an undeclared field', () => {
+        const validate = compile('UpdateUserPayload');
+        expect(validate({})).toBe(true);
+        expect(validate({ name: 'New name' })).toBe(true);
+        // `email` is deliberately not updatable through this endpoint and never has been.
+        expect(validate({ email: 'new@acme.com' })).toBe(false);
+    });
+});
+
+describe('gate 4 — runtime enforcement uses the published components', () => {
+    it('rejects an undeclared update field without removing it', () => {
+        // The handler used to whitelist fields and silently ignore the rest; the published schema
+        // has always said additionalProperties: false. Enforcement makes the two agree.
+        const payload: Record<string, unknown> = { name: 'Acme', rogue_field: 42 };
+        const result = validateApiRequest('UpdateUserPayload', payload);
+        expect(result.valid).toBe(false);
+        expect(payload.rogue_field).toBe(42);
+    });
+
+    it('accepts a conforming update payload and hands back the component type', () => {
+        const result = validateApiRequest('UpdateUserPayload', { name: 'Acme', clearance: 3 });
+        expect(result.valid).toBe(true);
+        if (result.valid) {
+            assertType<Equals<typeof result.data, UpdateUserPayload>>(true);
+            expect(result.data.clearance).toBe(3);
+        }
+    });
+
+    it('checks the user response against the same component the SDK type comes from', () => {
+        const result = validateApiResponse('User', VALID_USER);
+        expect(result.valid).toBe(true);
+        if (result.valid) {
+            assertType<Equals<typeof result.data, User>>(true);
+        }
+        // A document spread straight onto the wire is what this catches.
+        expect(validateApiResponse('User', { ...VALID_USER, _id: 'x' }).valid).toBe(false);
+    });
+
+    it('enforces the date-time format the timestamps claim', () => {
+        // Through the registry rather than the local `compile` helper: the production validator
+        // registers ajv-formats, and a bare Ajv2020 ignores `format` entirely — which is precisely
+        // why the description alone was not enough. A plain string schema accepts 'yesterday'.
+        expect(validateApiResponse('User', { ...VALID_USER, created_at: 'yesterday' }).valid).toBe(false);
+        expect(validateApiResponse('User', { ...VALID_USER, created_at: '2026-07-30' }).valid).toBe(false);
+        expect(validateApiResponse('User', VALID_USER).valid).toBe(true);
+    });
+
+    it('checks every member of the account listing against the same User component', () => {
+        // The gap this closes: `UserArray` items $ref `User`, so publishing the array without
+        // enforcing it would document the contract for each member while checking none of them.
+        expect(validateApiResponse('UserArray', [VALID_USER, VALID_USER]).valid).toBe(true);
+        expect(validateApiResponse('UserArray', []).valid).toBe(true);
+        // A legacy member with no timestamps, which is exactly what the old jsonDocs() could emit.
+        const { created_at: _dropped, ...legacyMember } = VALID_USER;
+        expect(validateApiResponse('UserArray', [VALID_USER, legacyMember]).valid).toBe(false);
+        // And one carrying a null the component cannot publish.
+        expect(validateApiResponse('UserArray', [{ ...VALID_USER, phone: null }]).valid).toBe(false);
+    });
+
+    it('validates the shared DeleteByIdResult that seven other endpoints also publish', () => {
+        expect(validateApiResponse('DeleteByIdResult', { id: 'abc' }).valid).toBe(true);
+        expect(validateApiResponse('DeleteByIdResult', {}).valid).toBe(false);
+    });
+});