@vertesia/common 1.6.0-dev.20260923.085325Z → 1.6.0-dev.20261004.085740Z

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

@@ -1,112 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import type { z } from 'zod';
-import type {
-    AgentTokenRequest,
-    ApiKeyTokenRequest,
-    EnvironmentTokenRequest,
-    IssueTokenForbiddenResponse,
-    IssueTokenRequest,
-    IssueTokenResponse,
-    ProjectTokenRequest,
-    ServiceAccountTokenRequest,
-    SigningAlgorithm,
-    UserTokenRequest,
-} from '../sts-token-types.js';
-import { validateApiRequest, validateApiResponse } from './registry.js';
-import type {
-    AgentTokenRequestSchema,
-    ApiKeyTokenRequestSchema,
-    EnvironmentTokenRequestSchema,
-    IssueTokenForbiddenResponseSchema,
-    IssueTokenRequestSchema,
-    IssueTokenResponseSchema,
-    ProjectTokenRequestSchema,
-    ServiceAccountTokenRequestSchema,
-    SigningAlgorithmSchema,
-    UserTokenRequestSchema,
-} from './sts.js';
-
-type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
-function assertType<T extends true>(_value: T): void {}
-
-describe('STS canonical contracts', () => {
-    it('derives every public component type from its schema', () => {
-        assertType<Equals<SigningAlgorithm, z.infer<typeof SigningAlgorithmSchema>>>(true);
-        assertType<Equals<ApiKeyTokenRequest, z.infer<typeof ApiKeyTokenRequestSchema>>>(true);
-        assertType<Equals<UserTokenRequest, z.infer<typeof UserTokenRequestSchema>>>(true);
-        assertType<Equals<ProjectTokenRequest, z.infer<typeof ProjectTokenRequestSchema>>>(true);
-        assertType<Equals<EnvironmentTokenRequest, z.infer<typeof EnvironmentTokenRequestSchema>>>(true);
-        assertType<Equals<AgentTokenRequest, z.infer<typeof AgentTokenRequestSchema>>>(true);
-        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);
-    });
-
-    it('enforces the discriminated request branch and closed object policy', () => {
-        expect(
-            validateApiRequest('IssueTokenRequest', {
-                type: 'project',
-                account_id: 'acc_1',
-                project_id: 'proj_1',
-            }).valid,
-        ).toBe(true);
-        expect(
-            validateApiRequest('IssueTokenRequest', {
-                type: 'project',
-                account_id: 'acc_1',
-                project_id: 'proj_1',
-                key: 'not-valid-on-this-branch',
-            }).valid,
-        ).toBe(false);
-        expect(validateApiRequest('IssueTokenRequest', { type: 'project', account_id: 'acc_1' }).valid).toBe(false);
-    });
-
-    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',
-                message: 'Token signing temporarily unavailable',
-            }).valid,
-        ).toBe(true);
-        expect(
-            validateApiResponse('IssueTokenUnavailableResponse', {
-                error: 'Service Unavailable',
-                message: 'Token signing temporarily unavailable',
-                retry_after: 5,
-            }).valid,
-        ).toBe(false);
-    });
-});

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

@@ -1,197 +0,0 @@
-import { Ajv2020 } from 'ajv/dist/2020.js';
-import { describe, expect, it } from 'vitest';
-import type { AbacPrincipalContext, 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 { AbacPrincipalContextFromSchema, 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<AbacPrincipalContext, AbacPrincipalContextFromSchema>>(true);
-        expect(true).toBe(true);
-    });
-
-    it('derives the identity fields from the ABAC context rather than restating them', () => {
-        // PrincipalIdentity `extends AbacPrincipalContext`, so composing the schemas is what keeps
-        // the inherited fields from becoming a twin one level down — the failure mode this batch was
-        // scoped to avoid. `kind` and `id` are part of the ABAC context itself (resolvable as
-        // `$principal.*`), not identity-only metadata.
-        assertType<Equals<PrincipalIdentity['kind'], AbacPrincipalContext['kind']>>(true);
-        assertType<Equals<PrincipalIdentity['id'], AbacPrincipalContext['id']>>(true);
-        assertType<Equals<PrincipalIdentity['clearance'], AbacPrincipalContext['clearance']>>(true);
-        assertType<Equals<PrincipalIdentity['compartments'], AbacPrincipalContext['compartments']>>(true);
-        assertType<Equals<PrincipalIdentity['email'], AbacPrincipalContext['email']>>(true);
-        assertType<Equals<PrincipalIdentity['tags'], AbacPrincipalContext['tags']>>(true);
-        assertType<Equals<PrincipalIdentity['properties'], AbacPrincipalContext['properties']>>(true);
-        assertType<Equals<PrincipalIdentity['kind'], 'user' | 'apikey'>>(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 AbacPrincipalContext 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('AbacPrincipalContext');
-        const props = ApiSchemaComponents.PrincipalIdentity.properties as Record<string, JsonObject>;
-        expect(props.kind).toEqual({ type: 'string', enum: ['user', 'apikey'] });
-        expect(props.clearance).toEqual({ type: 'number' });
-        expect(props.id).toEqual({ type: 'string' });
-    });
-
-    it('publishes the composed property order — kind and id first', () => {
-        // `AbacPrincipalContext` lists its discriminators (kind, id) ahead of the merged BLP
-        // attributes; PrincipalIdentity `.extend({})`s it, adding nothing, so the order is the
-        // context's own.
-        const props = ApiSchemaComponents.PrincipalIdentity.properties as JsonObject;
-        expect(Object.keys(props)).toEqual(['kind', 'id', 'clearance', 'compartments', 'email', 'tags', 'properties']);
-    });
-
-    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);
-    });
-});

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

@@ -1,112 +0,0 @@
-import { assertType, describe, expect, it } from 'vitest';
-import type { z } from 'zod';
-import { type ViewExperienceConfiguration, viewExperienceRoute } from '../views.js';
-import { ApiSchemaComponents, validateApiRequest, validateApiResponse } from './registry.js';
-import type { ViewExperienceConfigurationSchema } from './view-execution.js';
-
-type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
-
-/**
- * Lives here rather than next to the JSON Schema artifact that consumes it. Both subjects are
- * declarations of THIS package — the public TypeScript type and the Zod schema it must mirror — and
- * asserting it from the consuming package would have made that package depend on Zod, which it must
- * not: it is loaded in the browser.
- */
-describe('ViewExperienceConfiguration', () => {
-    it('keeps the temporary named TypeScript bridge identical to the runtime schema', () => {
-        assertType<Equals<ViewExperienceConfiguration, z.infer<typeof ViewExperienceConfigurationSchema>>>(true);
-    });
-
-    it('publishes selection, app actions, upload drops, generated presentation mode, and reranking', () => {
-        expect(Object.keys(ApiSchemaComponents)).toEqual(
-            expect.arrayContaining([
-                'AgenticViewRerankConfiguration',
-                'ViewActionConfiguration',
-                'ViewActionsConfiguration',
-                'ViewDropConfiguration',
-                'ViewExecutionRerankResult',
-                'ViewSelectionConfiguration',
-            ]),
-        );
-
-        expect(
-            validateApiRequest('PreviewViewExperienceRequest', {
-                configuration: {
-                    name: 'Orders',
-                    search: {
-                        mode: 'agentic',
-                        agentic: {
-                            mode: 'query_and_view',
-                            rerank: { max_candidates: 24, include_why_match: true, timeout_ms: 30_000 },
-                        },
-                    },
-                    results: {
-                        default_display: 'table',
-                        displays: [{ id: 'table', label: 'Orders', type: 'table', columns: [] }],
-                        selection: { mode: 'multiple', select_all: 'page' },
-                        actions: {
-                            include_defaults: true,
-                            items: [{ id: 'approve', label: 'Approve', handler: 'approve-orders' }],
-                        },
-                        drop: { handler: 'upload', accept: ['files'], params: { type_id: 'sales-order' } },
-                    },
-                },
-            }).valid,
-        ).toBe(true);
-    });
-
-    it('keeps executable custom drop handlers out of the persisted wire contract', () => {
-        expect(
-            validateApiRequest('PreviewViewExperienceRequest', {
-                configuration: {
-                    name: 'Orders',
-                    results: {
-                        default_display: 'table',
-                        displays: [{ id: 'table', label: 'Orders', type: 'table', columns: [] }],
-                        drop: { handler: 'custom-drop' },
-                    },
-                },
-            }).valid,
-        ).toBe(false);
-    });
-
-    it('accepts untagged View options and preserves the shared options schema reference', () => {
-        // View options and shared model options both permit an omitted family ID.
-        const authored = { model_options: { temperature: 0.2, max_tokens: 1024 } };
-        expect(validateApiResponse('ViewAgenticExecutionConfiguration', authored).valid).toBe(true);
-
-        // Keep the shared component wired to the canonical options contract.
-        const modelOptions = (name: string) =>
-            (ApiSchemaComponents[name] as { properties: Record<string, unknown> }).properties.model_options;
-        expect(modelOptions('InteractionExecutionConfiguration')).toEqual({
-            $ref: '#/components/schemas/ModelOptions',
-        });
-        expect(modelOptions('ViewAgenticExecutionConfiguration')).toMatchObject({
-            type: 'object',
-            additionalProperties: true,
-        });
-    });
-
-    it('keeps the View config otherwise identical to the shared execution configuration', () => {
-        // Only `model_options` may differ. Anything else diverging means the two drifted apart
-        // rather than the union being deliberately relaxed for authored options.
-        const properties = (name: string) =>
-            (ApiSchemaComponents[name] as { properties: Record<string, unknown> }).properties;
-        const view = properties('ViewAgenticExecutionConfiguration');
-        const shared = properties('InteractionExecutionConfiguration');
-
-        expect(Object.keys(view)).toEqual(Object.keys(shared));
-        for (const key of Object.keys(shared)) {
-            if (key === 'model_options') continue;
-            expect(JSON.stringify(view[key]), `${key} drifted from the shared configuration`).toBe(
-                JSON.stringify(shared[key]),
-            );
-        }
-    });
-
-    it('builds generic routes for system and app-contributed Views without exposing path material', () => {
-        expect(viewExperienceRoute('app:content:document-library')).toBe('/view/app%3Acontent%3Adocument-library');
-        expect(viewExperienceRoute('sys:AgenticDocumentExplorer')).toBe('/view/sys%3AAgenticDocumentExplorer');
-        expect(viewExperienceRoute('unsafe/id')).toBe('/view/unsafe%2Fid');
-    });
-});