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

package/src/api-schemas/oauth-server.ts

@@ -0,0 +1,219 @@
+import { z } from 'zod';
+
+/**
+ * The contracts for Vertesia's OWN OAuth server: the clients registered against it and the grants
+ * their users have approved. Vertesia acting as a client of someone else's authorization server is
+ * `./oauth.js`.
+ *
+ * Only the three resources backed by the studio API have slots here. The token server's own surface
+ * — authorize, token, device code, consent — is still TypeScript-derived and has not been converted,
+ * so the types it uses stay declared in `../oauth-server.ts` rather than moving here.
+ */
+
+export const OAuthClientTypeSchema = z.enum(['public', 'confidential']).meta({ id: 'OAuthClientType' });
+
+export const OAuthClientStatusSchema = z.enum(['active', 'disabled']).meta({ id: 'OAuthClientStatus' });
+
+export const OAuthRegistrationSourceSchema = z.enum(['admin', 'dynamic']).meta({ id: 'OAuthRegistrationSource' });
+
+export const OAuthProjectBindingModeSchema = z.enum(['user_select', 'fixed']).meta({ id: 'OAuthProjectBindingMode' });
+
+export const OAuthTokenEndpointAuthMethodSchema = z
+    .enum(['none', 'client_secret_post', 'client_secret_basic'])
+    .meta({ id: 'OAuthTokenEndpointAuthMethod' });
+
+export const OAuthGrantTypeSchema = z
+    .enum(['authorization_code', 'refresh_token', 'urn:ietf:params:oauth:grant-type:device_code'])
+    .meta({ id: 'OAuthGrantType' });
+
+export const OAuthResponseTypeSchema = z.literal('code').meta({ id: 'OAuthResponseType' });
+
+export const OAuthGrantStatusSchema = z.enum(['active', 'revoked', 'expired']).meta({ id: 'OAuthGrantStatus' });
+
+export const OAuthGrantSortFieldSchema = z
+    .enum(['granted_at', 'client_name', 'user_name', 'resource', 'last_used_at', 'expires_at', 'status'])
+    .meta({ id: 'OAuthGrantSortField' });
+
+export const OAuthGrantSortOrderSchema = z.enum(['asc', 'desc']).meta({ id: 'OAuthGrantSortOrder' });
+
+/**
+ * A client's registration, without its issued id.
+ *
+ * Split from {@link OAuthClientSchema} because `OAuthClient extends OAuthClientData` in the published
+ * types and both names are exported. No `id` in its meta, so it is never a component: the document
+ * publishes these properties inline under `OAuthClient`, with `client_id` last.
+ */
+export const OAuthClientDataSchema = z.strictObject({
+    client_name: z.string(),
+    client_type: OAuthClientTypeSchema,
+    redirect_uris: z.array(z.string()),
+    grant_types: z.array(OAuthGrantTypeSchema),
+    response_types: z.array(OAuthResponseTypeSchema),
+    token_endpoint_auth_method: OAuthTokenEndpointAuthMethodSchema,
+    allowed_scopes: z.array(z.string()),
+    default_scopes: z.array(z.string()).optional(),
+    registration_source: OAuthRegistrationSourceSchema,
+    status: OAuthClientStatusSchema,
+    project_binding_mode: OAuthProjectBindingModeSchema,
+    fixed_project_id: z.string().optional(),
+    restrict_to_owner_account: z
+        .boolean()
+        .meta({
+            description:
+                'When true (the default for new clients), the client may only be authorized for projects in its owning account/organization. Set to false to allow authorization for any project the approving user can access, regardless of account — required for OAuth/MCP clients used across organizations. The owning account itself is internal and not exposed here.',
+        })
+        .optional(),
+    metadata: z.looseObject({}).optional(),
+    created_by: z.string().optional(),
+    client_secret_configured: z.boolean().optional(),
+    created_at: z.string(),
+    updated_at: z.string(),
+});
+
+export const OAuthClientSchema = OAuthClientDataSchema.extend({
+    client_id: z.string(),
+}).meta({ id: 'OAuthClient' });
+
+export const OAuthClientArraySchema = z.array(OAuthClientSchema).meta({ id: 'OAuthClientArray' });
+
+/**
+ * The create response, which is the read shape plus the one field that is never readable again.
+ *
+ * `client_secret` is returned exactly once, by the call that generates it; every later read of the
+ * same client publishes `client_secret_configured` instead. Two components rather than one optional
+ * field on `OAuthClient` is what keeps that one-time disclosure visible in the document.
+ */
+export const OAuthClientCreateResponseSchema = OAuthClientSchema.extend({
+    client_secret: z.string().optional(),
+}).meta({ id: 'OAuthClientCreateResponse' });
+
+export const OAuthClientScopeMetadataSchema = z
+    .strictObject({
+        supported_scopes: z.array(z.string()),
+    })
+    .meta({ id: 'OAuthClientScopeMetadata' });
+
+export const CreateOAuthClientPayloadSchema = z
+    .strictObject({
+        client_name: z.string(),
+        client_type: OAuthClientTypeSchema.optional(),
+        redirect_uris: z.array(z.string()),
+        grant_types: z.array(OAuthGrantTypeSchema).optional(),
+        response_types: z.array(OAuthResponseTypeSchema).optional(),
+        token_endpoint_auth_method: OAuthTokenEndpointAuthMethodSchema.optional(),
+        allowed_scopes: z.array(z.string()).optional(),
+        default_scopes: z.array(z.string()).optional(),
+        project_binding_mode: OAuthProjectBindingModeSchema.optional(),
+        fixed_project_id: z.string().optional(),
+        restrict_to_owner_account: z.boolean().optional(),
+        client_secret: z.string().optional(),
+        metadata: z.looseObject({}).optional(),
+    })
+    .meta({ id: 'CreateOAuthClientPayload' });
+
+/**
+ * Not `.partial()` of the create payload, and the difference is deliberate rather than an oversight
+ * to tidy up: an update accepts `status`, which a create does not (a new client is always `active`),
+ * and cannot accept `client_type`, which is fixed at registration because the auth method and secret
+ * are decided from it. Deriving one from the other would publish both of those wrong.
+ */
+export const UpdateOAuthClientPayloadSchema = z
+    .strictObject({
+        client_name: z.string().optional(),
+        redirect_uris: z.array(z.string()).optional(),
+        grant_types: z.array(OAuthGrantTypeSchema).optional(),
+        response_types: z.array(OAuthResponseTypeSchema).optional(),
+        token_endpoint_auth_method: OAuthTokenEndpointAuthMethodSchema.optional(),
+        allowed_scopes: z.array(z.string()).optional(),
+        default_scopes: z.array(z.string()).optional(),
+        status: OAuthClientStatusSchema.optional(),
+        project_binding_mode: OAuthProjectBindingModeSchema.optional(),
+        fixed_project_id: z.string().optional(),
+        restrict_to_owner_account: z.boolean().optional(),
+        client_secret: z.string().optional(),
+        metadata: z.looseObject({}).optional(),
+    })
+    .meta({ id: 'UpdateOAuthClientPayload' });
+
+export const OAuthGrantSchema = z
+    .strictObject({
+        grant_id: z.string(),
+        client_id: z.string(),
+        client_name: z.string(),
+        user_id: z.string(),
+        user_name: z.string().optional(),
+        user_email: z.string().optional(),
+        account_id: z.string(),
+        project_id: z.string(),
+        resource: z.string(),
+        scope: z.array(z.string()),
+        status: OAuthGrantStatusSchema,
+        token_count: z.number(),
+        granted_at: z.string(),
+        created_at: z.string(),
+        last_used_at: z.string().optional(),
+        expires_at: z.string().optional(),
+    })
+    .meta({ id: 'OAuthGrant' });
+
+/**
+ * What `?status=` accepts: every {@link OAuthGrantStatusSchema} member, plus `all` for "do not filter".
+ *
+ * Written out rather than composed from the status enum, because the two are published differently
+ * and have to be: a query parameter is expanded inline, so a union would reach the document as an
+ * `anyOf` of a `$ref` and a `const` — a shape no generator turns into a usable enum, and one this
+ * parameter has never had. `oauth-grant-status-filter.test.ts` pins the members to the status enum
+ * plus the sentinel so the two cannot drift apart silently.
+ */
+const OAuthGrantStatusFilterSchema = z.enum(['active', 'revoked', 'expired', 'all']);
+
+/**
+ * The listing filters, shared with the bulk revoke body because `BulkRevokeOAuthGrantsPayload
+ * extends ListOAuthGrantsQuery` — selecting grants to revoke is selecting grants to list, and two
+ * copies of ten filters would be two chances for the selection to mean something different from the
+ * preview the caller looked at.
+ */
+const oauthGrantFilterFields = {
+    account_id: z.string().optional(),
+    project_id: z.string().optional(),
+    user_id: z.string().optional(),
+    client_id: z.string().optional(),
+    resource: z.string().optional(),
+    status: OAuthGrantStatusFilterSchema.optional(),
+    limit: z.number().optional(),
+    offset: z.number().optional(),
+    sort_by: OAuthGrantSortFieldSchema.optional(),
+    sort_order: OAuthGrantSortOrderSchema.optional(),
+};
+
+export const ListOAuthGrantsQuerySchema = z.strictObject(oauthGrantFilterFields).meta({ id: 'ListOAuthGrantsQuery' });
+
+export const RevokeOAuthGrantQuerySchema = z
+    .strictObject({
+        include_consent: z.boolean().optional(),
+    })
+    .meta({ id: 'RevokeOAuthGrantQuery' });
+
+export const BulkRevokeOAuthGrantsPayloadSchema = z
+    .strictObject({
+        ...oauthGrantFilterFields,
+        grant_ids: z.array(z.string()).optional(),
+        include_consent: z.boolean().optional(),
+    })
+    .meta({ id: 'BulkRevokeOAuthGrantsPayload' });
+
+export const OAuthGrantListResponseSchema = z
+    .strictObject({
+        grants: z.array(OAuthGrantSchema),
+        total_count: z.number(),
+        limit: z.number(),
+        offset: z.number(),
+    })
+    .meta({ id: 'OAuthGrantListResponse' });
+
+export const OAuthGrantRevokeResponseSchema = z
+    .strictObject({
+        revoked_tokens: z.number(),
+        revoked_consents: z.number(),
+    })
+    .meta({ id: 'OAuthGrantRevokeResponse' });

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

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import { OAuthGrantStatusSchema } from './oauth-server.js';
+import { ApiSchemaComponents, validateApiRequest, validateApiResponse } from './registry.js';
+
+/**
+ * The OAuth contracts, pinned where converting them changed what the document says or where the
+ * conversion had a choice to make.
+ *
+ * The provider/client/grant closure is 31 components and almost all of it re-emits byte-identically;
+ * what is asserted here is the handful of places it does not, plus the request/response secret split
+ * that is the reason these components are shaped the way they are.
+ */
+
+describe('the OAuth grant status filter', () => {
+    /**
+     * `?status=` takes the grant statuses plus `all`, and the query schema spells all four out rather
+     * than composing them, because a union would reach the document as an `anyOf` of a `$ref` and a
+     * `const` once the parameter is expanded. That leaves two lists that have to agree, so this is
+     * the assertion that they do: adding a fourth grant status without adding it to the filter would
+     * publish a status the caller cannot filter for.
+     */
+    it('offers every grant status, plus the all sentinel', () => {
+        expect(statusEnumOf('ListOAuthGrantsQuery')).toEqual([...OAuthGrantStatusSchema.options, 'all']);
+    });
+
+    it('is the same list on the bulk revoke body as on the listing query', () => {
+        // Revoking in bulk selects grants exactly the way listing them does — a filter that meant
+        // something different from the preview the caller looked at is the failure mode here.
+        expect(statusEnumOf('BulkRevokeOAuthGrantsPayload')).toEqual(statusEnumOf('ListOAuthGrantsQuery'));
+    });
+
+    it('rejects a status that is neither, rather than listing everything', () => {
+        expect(validateApiRequest('BulkRevokeOAuthGrantsPayload', { status: 'pending' }).valid).toBe(false);
+        expect(validateApiRequest('BulkRevokeOAuthGrantsPayload', { status: 'all' }).valid).toBe(true);
+    });
+});
+
+describe('the OAuth provider secret boundary', () => {
+    it('accepts a client secret on create', () => {
+        expect(
+            validateApiRequest('CreateOAuthProviderPayload', {
+                name: 'acme',
+                display_name: 'Acme',
+                client_id: 'client-123',
+                client_secret: 'shhh',
+            }),
+        ).toMatchObject({ valid: true });
+    });
+
+    it('refuses to publish one on the way back out', () => {
+        // The read shape says whether a secret exists and nothing more. `additionalProperties: false`
+        // is what turns a mapper that spread the document into a failed response instead of a leak.
+        const response = {
+            id: '68b1779130afe5403a1589ba',
+            name: 'acme',
+            display_name: 'Acme',
+            project: '69d4762f24d3048c99149d0b',
+            client_id: 'client-123',
+            has_client_secret: true,
+            use_pkce: true,
+            created_at: '2026-01-01T00:00:00.000Z',
+            updated_at: '2026-01-01T00:00:00.000Z',
+        };
+
+        expect(validateApiResponse('OAuthProvider', response)).toMatchObject({ valid: true });
+        expect(validateApiResponse('OAuthProvider', { ...response, client_secret: 'shhh' }).valid).toBe(false);
+    });
+
+    it('publishes the client secret on the create response only', () => {
+        // The one call that generates it returns it once; every later read of the same client gets
+        // `client_secret_configured`. Two components rather than one optional field is what keeps
+        // that visible in the document.
+        const client = {
+            client_id: 'vts_abc',
+            client_name: 'Acme CLI',
+            client_type: 'public',
+            redirect_uris: ['https://acme.example/callback'],
+            grant_types: ['authorization_code'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+            allowed_scopes: ['openid'],
+            registration_source: 'admin',
+            status: 'active',
+            project_binding_mode: 'user_select',
+            created_at: '2026-01-01T00:00:00.000Z',
+            updated_at: '2026-01-01T00:00:00.000Z',
+        };
+
+        expect(validateApiResponse('OAuthClientCreateResponse', { ...client, client_secret: 'vss_x' })).toMatchObject({
+            valid: true,
+        });
+        expect(validateApiResponse('OAuthClient', { ...client, client_secret: 'vss_x' }).valid).toBe(false);
+    });
+});
+
+describe('UpdateOAuthProviderPayload', () => {
+    it('accepts an empty body and a single-field body, and still rejects a typo', () => {
+        expect(validateApiRequest('UpdateOAuthProviderPayload', {}).valid).toBe(true);
+        expect(validateApiRequest('UpdateOAuthProviderPayload', { display_name: 'Acme' }).valid).toBe(true);
+        expect(validateApiRequest('UpdateOAuthProviderPayload', { displayName: 'Acme' }).valid).toBe(false);
+    });
+});
+
+/**
+ * A component's `status` enum, as the registry emits it.
+ *
+ * Read off the component rather than off a generated document: generating one needs the scanner,
+ * which is a package this one does not depend on. The expansion of a query component into parameters
+ * inlines exactly this, and has its own tests in `parameters.test.ts`.
+ */
+function statusEnumOf(component: 'ListOAuthGrantsQuery' | 'BulkRevokeOAuthGrantsPayload'): string[] {
+    const emitted = ApiSchemaComponents[component] as { properties?: Record<string, { enum?: unknown }> } | undefined;
+    const status = emitted?.properties?.status;
+    if (!Array.isArray(status?.enum)) {
+        throw new Error(`${component} does not publish status as an inline enum`);
+    }
+    return status.enum as string[];
+}

package/src/api-schemas/oauth.ts

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+
+/**
+ * The OAuth *provider* contracts: Vertesia acting as an OAuth CLIENT against a third-party
+ * authorization server.
+ *
+ * The other direction — clients registered against Vertesia's own OAuth server, and the grants they
+ * hold — is `./oauth-server.js`. The split mirrors the one the TypeScript declarations already had,
+ * so each schema sits in the module its type came from and the canonical-alias map stays readable.
+ */
+
+/**
+ * The success acknowledgement four provider endpoints and the client delete return.
+ *
+ * Here rather than in a module of its own because these five slots are its only callers, which is
+ * the same reason `DeleteOperationResult` lives in `./apikey.js`. `common.ts` aliases the type so
+ * `SuccessResponse` keeps being imported from where it always was.
+ *
+ * `z.boolean()`, not `z.literal(true)`, and that is what the document has always published: the
+ * scanner widened the declared `success: true` to `type: boolean` on the way out. Publishing the
+ * literal would newly forbid `{ success: false }` for every existing client, while the handlers
+ * return `true` either way.
+ */
+export const SuccessResponseSchema = z
+    .strictObject({
+        success: z.boolean(),
+    })
+    .meta({ id: 'SuccessResponse' });
+
+/**
+ * A provider's stored configuration, without its id.
+ *
+ * Split from {@link OAuthProviderSchema} because `OAuthProvider extends OAuthProviderData` in the
+ * published types and both names are exported from the package. It carries no `id` in its meta, so
+ * it is never a component of its own: the document has only ever published `OAuthProvider`, with
+ * these properties inline and `id` last.
+ */
+export const OAuthProviderDataSchema = z.strictObject({
+    name: z.string().meta({ description: 'Unique name within the project (kebab-case identifier).' }),
+    display_name: z.string().meta({ description: 'Human-readable display name.' }),
+    project: z.string().meta({ description: 'The project this OAuth provider belongs to.' }),
+    grant_type: z
+        .enum(['authorization_code', 'client_credentials'])
+        .meta({
+            description:
+                "The OAuth 2.0 grant type to use.\n- 'authorization_code': 3-legged flow requiring user authorization (default).\n- 'client_credentials': 2-legged server-to-server flow using client_id + client_secret.",
+        })
+        .optional(),
+    authorization_endpoint: z
+        .string()
+        .meta({
+            description:
+                'The OAuth 2.0 authorization endpoint URL. Only used for authorization_code flow. Optional when endpoints are discovered via .well-known (e.g. MCP servers).',
+        })
+        .optional(),
+    token_endpoint: z
+        .string()
+        .meta({
+            description:
+                'The OAuth 2.0 token endpoint URL. Optional when endpoints are discovered via .well-known (e.g. MCP servers).',
+        })
+        .optional(),
+    client_id: z.string().meta({ description: 'The OAuth client ID (always required).' }),
+    has_client_secret: z
+        .boolean()
+        .meta({ description: 'Whether a client_secret is configured (never exposes the actual secret).' })
+        .optional(),
+    default_scopes: z
+        .array(z.string())
+        .meta({ description: 'Default scopes to request during authorization.' })
+        .optional(),
+    use_pkce: z.boolean().meta({
+        description:
+            'Whether to use PKCE (Proof Key for Code Exchange) in the authorization flow. Only applies to authorization_code flow. Defaults to true.',
+    }),
+    revocation_endpoint: z.string().meta({ description: 'Optional OAuth 2.0 revocation endpoint URL.' }).optional(),
+    created_at: z.string(),
+    updated_at: z.string(),
+});
+
+export const OAuthProviderSchema = OAuthProviderDataSchema.extend({
+    id: z.string(),
+}).meta({ id: 'OAuthProvider', description: 'OAuth Provider as returned by the API (with id).' });
+
+export const OAuthProviderArraySchema = z.array(OAuthProviderSchema).meta({ id: 'OAuthProviderArray' });
+
+/**
+ * What a create accepts, which is deliberately not what a read returns.
+ *
+ * `client_secret` goes IN and never comes back out: the read shape carries `has_client_secret`
+ * instead. That request/response split is the rule for any component holding a credential, and
+ * keeping the two schemas separate is what makes it structural rather than a convention the next
+ * handler has to remember.
+ */
+export const CreateOAuthProviderPayloadSchema = z
+    .strictObject({
+        name: z.string(),
+        display_name: z.string(),
+        grant_type: z.enum(['authorization_code', 'client_credentials']).optional(),
+        authorization_endpoint: z.string().optional(),
+        token_endpoint: z.string().optional(),
+        client_id: z.string(),
+        client_secret: z
+            .string()
+            .meta({
+                description:
+                    'Optional client secret for confidential clients. Will be encrypted at rest and never returned in API responses.',
+            })
+            .optional(),
+        default_scopes: z.array(z.string()).optional(),
+        use_pkce: z.boolean().optional(),
+        revocation_endpoint: z.string().optional(),
+    })
+    .meta({
+        id: 'CreateOAuthProviderPayload',
+        description:
+            'Payload for creating an OAuth Provider. The client_secret is accepted as plaintext on create and stored encrypted.',
+    });
+
+/**
+ * The update contract shares the create fields but makes each optional; the handler writes only the
+ * fields present in the request.
+ */
+export const UpdateOAuthProviderPayloadSchema = CreateOAuthProviderPayloadSchema.partial().meta({
+    id: 'UpdateOAuthProviderPayload',
+    description:
+        'Payload for updating an OAuth Provider. All fields are optional — only provided fields are updated. To clear the client_secret, set it to an empty string.',
+});
+
+export const OAuthProviderAuthStatusSchema = z
+    .strictObject({
+        oauth_provider_id: z.string(),
+        oauth_provider_name: z.string(),
+        authenticated: z.boolean(),
+        expires_at: z.string().optional(),
+        scope: z.string().optional(),
+    })
+    .meta({
+        id: 'OAuthProviderAuthStatus',
+        description: 'OAuth authentication status for a user against an OAuth Provider.',
+    });
+
+export const OAuthProviderAuthorizeResponseSchema = z
+    .strictObject({
+        authorization_url: z.string().optional(),
+        state: z.string().optional(),
+        connected: z.boolean().optional(),
+    })
+    .meta({
+        id: 'OAuthProviderAuthorizeResponse',
+        description:
+            'Response from the OAuth authorize endpoint. For authorization_code flow: contains authorization_url and state for browser redirect. For client_credentials flow: contains connected=true (token was fetched server-side, no redirect needed).',
+    });
+
+export const OAuthProviderAccessTokenResponseSchema = z
+    .strictObject({
+        access_token: z.string(),
+    })
+    .meta({ id: 'OAuthProviderAccessTokenResponse' });
+
+export const OAuthProviderExchangePayloadSchema = z
+    .strictObject({
+        code: z.string(),
+        state: z.string(),
+    })
+    .meta({ id: 'OAuthProviderExchangePayload' });