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

package/src/sts-token-types.ts

@@ -2,50 +2,34 @@
  * STS Token Request Types
  * These types define the structure for token requests to the Security Token Service
  */
-import type { SystemRoles } from './project.js';
-
-export type TokenType = 'apikey' | 'user' | 'project' | 'environment' | 'agent' | 'service_account';
-export type SigningAlgorithm = 'ES256' | 'RS256';
-
-interface BaseTokenRequest {
-    type: TokenType;
-    audience?: string;
-    /** Signing algorithm - defaults to ES256. Use RS256 for Azure AD compatibility. */
-    algorithm?: SigningAlgorithm;
-}
+import type { z } from 'zod';
+import type {
+    AgentTokenRequestSchema,
+    ApiKeyTokenRequestSchema,
+    EnvironmentTokenRequestSchema,
+    IssueTokenRequestSchema,
+    IssueTokenResponseSchema,
+    ProjectTokenRequestSchema,
+    ServiceAccountTokenRequestSchema,
+    SigningAlgorithmSchema,
+    TokenTypeSchema,
+    UserTokenRequestSchema,
+} from './api-schemas/sts.js';
+
+export type TokenType = z.infer<typeof TokenTypeSchema>;
+export type SigningAlgorithm = z.infer<typeof SigningAlgorithmSchema>;
 
 // API key doesn't need account/project as it's determined from the key
-export interface ApiKeyTokenRequest extends BaseTokenRequest {
-    type: 'apikey';
-    key: string;
-}
+export type ApiKeyTokenRequest = z.infer<typeof ApiKeyTokenRequestSchema>;
 
 // User token needs optional account/project for scoping
-export interface UserTokenRequest extends BaseTokenRequest {
-    type: 'user';
-    user_id?: string; // Optional - can be determined from auth token
-    account_id?: string; // Optional - for scoping to specific account
-    project_id?: string; // Optional - for scoping to specific project
-    expires_at?: number;
-
-    on_behalf_of?: string; // Optional - user ID when acting on behalf of another user
-}
+export type UserTokenRequest = z.infer<typeof UserTokenRequestSchema>;
 
 // Project token requires project_id and account_id
-export interface ProjectTokenRequest extends BaseTokenRequest {
-    type: 'project';
-    project_id: string;
-    account_id: string;
-}
+export type ProjectTokenRequest = z.infer<typeof ProjectTokenRequestSchema>;
 
 // Environment token requires IDs - names fetched from DB
-export interface EnvironmentTokenRequest extends BaseTokenRequest {
-    type: 'environment';
-    environment_id: string;
-    environment_name: string; // Still required as environments may not be in DB
-    project_id: string; // Will fetch name and verify account
-    account_id: string; // Will fetch name and verify project belongs to it
-}
+export type EnvironmentTokenRequest = z.infer<typeof EnvironmentTokenRequestSchema>;
 
 /**
  * Agent token for a service account to act as agent on behalf of a user.
@@ -56,46 +40,15 @@ export interface EnvironmentTokenRequest extends BaseTokenRequest {
  * - `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 interface AgentTokenRequest extends BaseTokenRequest {
-    type: 'agent';
-    account_id: string;
-    project_id: string; // Will verify it belongs to account
-    name?: string;
-
-    /**
-     * User information.
-     *
-     * The 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.
-     *
-     * @example {JsonWebToken}
-     * @example user:68100a7c9f3c2b7d11a1b2c3
-     */
-    on_behalf_of: string;
-}
+export type AgentTokenRequest = z.infer<typeof AgentTokenRequestSchema>;
 
 // Service account token
-export interface ServiceAccountTokenRequest extends BaseTokenRequest {
-    type: 'service_account';
-    account_id: string;
-    project_id: string; // Will verify it belongs to account
-    roles?: SystemRoles[]; // Optional - roles for the service account token
-    name?: string;
-    email?: string;
-}
+export type ServiceAccountTokenRequest = z.infer<typeof ServiceAccountTokenRequestSchema>;
 
 /**
  * @discriminator type
  */
-export type IssueTokenRequest =
-    | ApiKeyTokenRequest
-    | UserTokenRequest
-    | ProjectTokenRequest
-    | EnvironmentTokenRequest
-    | AgentTokenRequest
-    | ServiceAccountTokenRequest;
+export type IssueTokenRequest = z.infer<typeof IssueTokenRequestSchema>;
 
 export interface RefreshTokenRequest {
     token: string;
@@ -137,11 +90,7 @@ export interface TokenResponse {
     expires_in?: number;
 }
 
-export interface IssueTokenResponse {
-    token: string;
-    token_type: 'Bearer';
-    expires_in?: number;
-}
+export type IssueTokenResponse = z.infer<typeof IssueTokenResponseSchema>;
 
 export interface ValidateTokenResponse {
     valid: boolean;

package/src/tools.ts

@@ -1,103 +1,24 @@
-import type { MCPToolAnnotations } from './apps.js';
+import type { z } from 'zod';
+import type {
+    AggregatedToolSchema,
+    ListProjectToolsQuerySchema,
+    ToolSourceSchema,
+    ToolValidationResultSchema,
+    ValidateToolNamesPayloadSchema,
+    ValidateToolNamesResponseSchema,
+} from './api-schemas/tools.js';
 
-/**
- * Origin of a tool in the unified project-scoped tool registry.
- *
- * - `builtin`: anything statically registered on the worker — workflow builtins, studio agent tools, and sys skills
- * - `app`: tools contributed by an installed app for the project
- * - `interaction`: a project interaction exposed via `tag=tool` / `is_tool=true` / `is_skill=true`
- *
- * Skill 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 type ToolSource = 'builtin' | 'app' | 'interaction';
+// The unified project-scoped tool registry, inferred from `./api-schemas/tools.js`. The
+// documentation for each member lives on the schema, which is what the OpenAPI document publishes.
 
-/**
- * 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 interface AggregatedTool {
-    /** Name as referenced from `agent_runner_options.tool_names`. For interaction skills this is `learn_<endpoint>`. */
-    name: string;
-    source: ToolSource;
-    description?: string;
-    title?: string;
-    /** Whether the tool is part of the default toolkit when no explicit `tool_names` is provided. */
-    is_default?: boolean;
-    annotations?: MCPToolAnnotations;
-    /** For skills (`learn_*`): tool names this skill unlocks when invoked. */
-    unlocked_tools?: string[];
-    /** Present when `source === 'app'`: the app installation that provides this tool. */
-    app_install_id?: string;
-    /** Present when `source === 'app'`: the app's manifest name (used for `principal.apps` filtering). */
-    app_name?: string;
-    /** Present when `source === 'interaction'`: the interaction document id. */
-    interaction_id?: string;
-    /**
-     * 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.
-     */
-    is_agent?: boolean;
-}
+export type ToolSource = z.infer<typeof ToolSourceSchema>;
 
-/**
- * Optional filters for `GET /tools`.
- *
- * The resolution is `(sources ?? ALL) − exclude`:
- *  - `sources` alone: include only the listed sources
- *  - `exclude` alone: include all sources except the listed ones
- *  - Both: start from `sources`, then remove `exclude`
- *  - Neither: include all sources
- *
- * Sources that are filtered out are not fetched, so passing `exclude=['app']` skips
- * the app round-trips entirely.
- */
-export interface ListProjectToolsQuery {
-    /** Include only these sources. */
-    sources?: ToolSource[];
-    /** Drop these sources from the result (and skip their fetch). Applied after `sources`. */
-    exclude?: ToolSource[];
-}
+export type AggregatedTool = z.infer<typeof AggregatedToolSchema>;
 
-/**
- * Per-name resolution result for `POST /tools/validate`.
- */
-export interface ToolValidationResult {
-    /** The name the caller asked about. */
-    name: string;
-    /** True if the name resolves to exactly one tool in the project's unified registry. */
-    valid: boolean;
-    /** When `valid`: which source the tool came from. */
-    source?: ToolSource;
-    /** When `valid` and `source === 'app'`: the app installation that provides the tool. */
-    app_install_id?: string;
-    /** When `valid` and `source === 'app'`: the app's manifest name. */
-    app_name?: string;
-    /** When `!valid` and a close match exists: the suggested replacement name (Levenshtein-based). */
-    suggestion?: string;
-    /**
-     * 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).
-     */
-    collisions?: Array<{ source: ToolSource; app_install_id?: string }>;
-}
+export type ListProjectToolsQuery = z.infer<typeof ListProjectToolsQuerySchema>;
 
-/**
- * Request payload for `POST /tools/validate`.
- */
-export interface ValidateToolNamesPayload {
-    /** Bare tool names as they appear in `agent_runner_options.tool_names`. `+`/`-` prefixes are stripped before lookup. */
-    names: string[];
-}
+export type ToolValidationResult = z.infer<typeof ToolValidationResultSchema>;
 
-/**
- * Response from `POST /tools/validate`.
- */
-export interface ValidateToolNamesResponse {
-    /** One entry per requested name, in the same order. */
-    results: ToolValidationResult[];
-    /** Convenience count of `results.filter(r => !r.valid).length`. */
-    invalid_count: number;
-}
+export type ValidateToolNamesPayload = z.infer<typeof ValidateToolNamesPayloadSchema>;
+
+export type ValidateToolNamesResponse = z.infer<typeof ValidateToolNamesResponseSchema>;

package/src/transient-tokens-values.ts

@@ -0,0 +1,11 @@
+/**
+ * Transient-token values that exist at runtime.
+ *
+ * Split out of `transient-tokens.ts` so `api-schemas/invites.ts` can read the enum without importing
+ * a module that derives its types from those very schemas. Re-exported from `transient-tokens.ts`.
+ */
+
+export enum TransientTokenType {
+    userInvite = 'user-invite',
+    migration = 'migration',
+}

package/src/transient-tokens.ts

@@ -1,10 +1,12 @@
-import type { ProjectRef, SystemRoles } from './project.js';
-import type { AccountRef, UserRef } from './user.js';
+import type { z } from 'zod';
+import type { UserInviteTokenDataSchema, UserInviteTokenFromSchema } from './api-schemas/invites.js';
+import type { TransientTokenType } from './transient-tokens-values.js';
 
-export enum TransientTokenType {
-    userInvite = 'user-invite',
-    migration = 'migration',
-}
+/**
+ * `TransientTokenType` lives in `./transient-tokens-values.js` so the API schemas can read it
+ * without importing this module back. Re-exported here so import paths keep working.
+ */
+export * from './transient-tokens-values.js';
 
 export interface TransientToken<T> {
     id: string;
@@ -18,10 +20,11 @@ export interface TransientToken<T> {
 
 export interface CreateOrUpdateTransientTokenPayload<T> extends Partial<TransientToken<T>> {}
 
-export interface UserInviteTokenData {
-    email: string;
-    role: SystemRoles;
-    account: AccountRef;
-    project?: ProjectRef;
-    invited_by: UserRef;
-}
+/**
+ * The invite payload as it crosses the wire, inferred from `./api-schemas/invites.js`. Every
+ * reference is populated by the handlers before the response is built.
+ */
+export type UserInviteTokenData = z.infer<typeof UserInviteTokenDataSchema>;
+
+/** One pending invite, as the three invite listings publish it. */
+export type UserInviteToken = UserInviteTokenFromSchema;

package/src/user.ts

@@ -1,51 +1,49 @@
+import type { z } from 'zod';
+import type { AccountBillingSchema, AccountSchema, UpdateAccountPayloadSchema } from './api-schemas/account.js';
+import type {
+    AccountProjectsResponseSchema,
+    AccountRefSchema,
+    InviteAcceptanceResponseSchema,
+    InviteDeclineResponseSchema,
+    InviteUserRequestPayloadSchema,
+    InviteUserResponsePayloadSchema,
+    OnboardingProgressSchema,
+} from './api-schemas/invites.js';
+import type {
+    SignupDataSchema,
+    SignupPayloadSchema,
+    UpdateUserPayloadSchema,
+    UserRefSchema,
+    UserSchema,
+} from './api-schemas/user.js';
 import type { ApiKey } from './apikey.js';
-import type { ProjectRef, SystemRoles } from './project.js';
+
+export * from './account-values.js';
 
 export interface UserWithAccounts extends User {
     accounts: AccountRef[];
 }
 
-export interface User {
-    id: string;
-    externalId?: string;
-    email: string;
-    name: string;
-    username?: string;
-    picture?: string;
-    language?: string;
-    phone?: string;
-    sign_in_provider?: string;
-    last_selected_account?: string;
-    source?: 'firebase' | 'scim';
-    updated_by?: string;
-    /** Custom properties for dynamic permission matching */
-    properties?: Record<string, unknown>;
-    /** BLP clearance level — determines max document sensitivity the user can access */
-    clearance?: number;
-    /** Compartments the user belongs to — restricts access to documents in matching compartments */
-    compartments?: string[];
-    /** Free-form user metadata - restricted to internal use */
-    annotations?: string[];
-}
-
-export interface UpdateUserPayload {
-    name?: string;
-    username?: string;
-    picture?: string;
-    language?: string;
-    phone?: string;
-    last_selected_account?: string;
-    properties?: Record<string, unknown>;
-    clearance?: number;
-    compartments?: string[];
-}
+/**
+ * The user and its update payload as they cross the wire.
+ *
+ * Derived from the schemas in `./api-schemas/user.js`, which are what OpenAPI publishes and AJV
+ * compiles. The descriptions live there too — Zod reads `.meta()`, not TSDoc.
+ *
+ * NOTE for server code: this is the RESPONSE shape, not the stored document. `IUser` in
+ * `@dglabs/server-common` describes what Mongo actually holds (optional email, ObjectId
+ * references, Date timestamps) and is deliberately independent of this type.
+ */
+export type User = z.infer<typeof UserSchema>;
+export type UpdateUserPayload = z.infer<typeof UpdateUserPayloadSchema>;
 
-export interface UserRef {
-    id: string;
-    name: string;
-    email: string;
-    picture?: string;
-}
+/**
+ * The compact user shape embedded in other resources' responses, derived from `UserRefSchema`.
+ *
+ * `UserRefPopulate` is the Mongoose projection that produces it, and the two are meant to stay in
+ * step: a field added here without adding it there yields a response missing the field.
+ */
+export type UserRef = z.infer<typeof UserRefSchema>;
 
 export const UserRefPopulate = 'id name email picture';
 
@@ -63,165 +61,42 @@ export const EARLY_ACCESS_ANNOTATION = 'early-access';
  */
 export const RESTRICTED_ENVIRONMENT_ERROR_CODE = 'restricted_environment';
 
-export enum Datacenters {
-    aws = 'aws',
-    gcp = 'gcp',
-    azure = 'azure',
-}
-
-export enum BillingMethod {
-    stripe = 'stripe',
-    invoice = 'invoice',
-}
-
-export enum AccountType {
-    vertesia = 'vertesia',
-    partner = 'partner',
-    free = 'free',
-    customer = 'customer',
-    prospect = 'prospect',
-    unknown = 'unknown',
-}
-
-export interface AccountBilling {
-    method: BillingMethod;
-    stripe_customer_id?: string;
-}
-
 /**
- * Quota/rate-limit tier assigned to an account. Code-defined tiers live in `@dglabs/quota`
- * (`QUOTA_TIERS`); these names must match its keys.
- * - `standard` — protective baseline limits (the default for most accounts).
- * - `enterprise` — high limits for contracted customers / internal / partners.
+ * The account as it crosses the wire.
  *
- * An account with no explicit `quota_tier` derives its tier from its `account_type`.
- */
-export enum QuotaTier {
-    standard = 'standard',
-    enterprise = 'enterprise',
-}
-
-/**
- * Default tier for an account that has no explicit `quota_tier`, derived from its `account_type`:
- * contracted customers and internal Vertesia accounts get `enterprise`; everyone else (partner,
- * free, prospect, unknown) gets the protective `standard` baseline.
+ * Derived from `AccountSchema`, not written alongside it: the schema is what OpenAPI publishes and
+ * what AJV compiles, so a hand-written twin could only ever drift from the contract actually being
+ * enforced. `import type` erases at compile time, so nothing here pulls zod into a browser or SDK
+ * bundle — runtime consumers reach the schemas through the `@vertesia/common/api-schemas` entry
+ * point instead.
  */
-export function quotaTierForAccountType(accountType: AccountType | undefined | null): QuotaTier {
-    switch (accountType) {
-        case AccountType.customer:
-        case AccountType.vertesia:
-            return QuotaTier.enterprise;
-        default:
-            return QuotaTier.standard;
-    }
-}
-
-export const ACCOUNT_NAMESPACE_MAX_LENGTH = 63;
-export const ACCOUNT_APP_ACCESS_MESSAGE_MAX_LENGTH = 1000;
-export const RESERVED_ACCOUNT_NAMESPACES = [
-    'admin',
-    'api',
-    'apps',
-    'auth',
-    'cdn',
-    'docs',
-    'internal-auth',
-    'mcp',
-    'status',
-    'sts',
-    'www',
-] as const;
-
-const ACCOUNT_NAMESPACE_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
-
-export function normalizeAccountNamespace(namespace: string): string {
-    return namespace.trim().toLowerCase();
-}
-
-export function getAccountNamespaceValidationError(namespace: string): string | undefined {
-    if (!namespace) {
-        return 'Account namespace is required';
-    }
-    if (namespace.length > ACCOUNT_NAMESPACE_MAX_LENGTH || !ACCOUNT_NAMESPACE_PATTERN.test(namespace)) {
-        return 'Account namespace must be a lowercase DNS label containing only letters, numbers, and hyphens';
-    }
-    if ((RESERVED_ACCOUNT_NAMESPACES as readonly string[]).includes(namespace)) {
-        return `Account namespace '${namespace}' is reserved`;
-    }
-    return undefined;
-}
+export type Account = z.infer<typeof AccountSchema>;
+export type AccountBilling = z.infer<typeof AccountBillingSchema>;
+export type UpdateAccountPayload = z.infer<typeof UpdateAccountPayloadSchema>;
 
-export interface Account {
-    id: string;
-    name: string;
-
-    /** Public DNS-label-compatible identifier used by organization app domains. */
-    namespace?: string;
-
-    /**
-     * Plain-text instructions shown when a signed-in user has no application access.
-     * @maxLength 1000
-     */
-    app_access_message?: string;
-
-    email_domains: string[];
-
-    onboarding: {
-        completed: boolean;
-        completed_at: Date;
-    };
-
-    datacenter: string;
-
-    account_type: AccountType;
-
-    billing: AccountBilling;
-
-    /** Quota/rate-limit tier. Unset → the deployment default tier (env `QUOTA_BASE_TIER`). */
-    quota_tier?: QuotaTier;
-
-    created_by: string;
-    updated_by: string;
-    created_at: string;
-    updated_at: string;
-}
-
-export interface UpdateAccountPayload {
-    name?: string;
-    /** @maxLength 1000 */
-    app_access_message?: string;
-    email_domains?: string[];
-    billing?: AccountBilling;
-    quota_tier?: QuotaTier;
-}
-
-export interface AccountRef {
-    id: string;
-    name: string;
-}
+// The compact account reference, derived from the schema in `./api-schemas/invites.js`. It was
+// hand-written for the same reason `ProjectRef` was — `ExecutionRun` and `UserInviteTokenData` still
+// reach it through types the scanner derives — and is an alias now for the same reason: the scanner
+// short-circuits such an alias to the published component rather than failing to expand it.
+export type AccountRef = z.infer<typeof AccountRefSchema>;
 
 export const AccountRefPopulate = 'id name';
 
-export interface InviteUserRequestPayload {
-    email: string;
-    role: SystemRoles;
-}
-
-export interface InviteUserResponsePayload {
-    action: 'invited' | 'added';
-}
-
-export interface InviteAcceptanceResponse {
-    status: 'added';
-}
-
-export interface InviteDeclineResponse {
-    status: 'deleted';
-}
-
-export interface AccountProjectsResponse {
-    data: ProjectRef[];
-}
+/**
+ * The account invite, onboarding and project-listing wire types, derived from
+ * `./api-schemas/invites.js`.
+ *
+ * `AccountRef` above is the one member of this closure that stays hand-written, and only because
+ * `Interaction` and `PromptTemplate` still reference it through the TypeScript scanner, which cannot
+ * expand a `z.infer<>`. Everything here is reachable only from converted slots, so nothing derived
+ * reads it and the alias is safe. `AccountRefSchema` is still the runtime source of truth, and the
+ * `Equals` assertion in `invites.contract.test.ts` is what holds the interface to it.
+ */
+export type InviteUserRequestPayload = z.infer<typeof InviteUserRequestPayloadSchema>;
+export type InviteUserResponsePayload = z.infer<typeof InviteUserResponsePayloadSchema>;
+export type InviteAcceptanceResponse = z.infer<typeof InviteAcceptanceResponseSchema>;
+export type InviteDeclineResponse = z.infer<typeof InviteDeclineResponseSchema>;
+export type AccountProjectsResponse = z.infer<typeof AccountProjectsResponseSchema>;
 
 type UserOrApiKey<T extends User | ApiKey> = T extends User ? User : ApiKey;
 type SessionType<T extends User | ApiKey> = T extends User ? 'user' : 'apikey';
@@ -238,29 +113,14 @@ export interface SessionInfo<T extends User | ApiKey> {
 export interface UserSessionInfo extends SessionInfo<User> {}
 export interface ApiKeySessionInfo extends SessionInfo<ApiKey> {}
 
-export interface OnboardingProgress {
-    interactions: boolean;
-    prompts: boolean;
-    environments: boolean;
-    default_environment_defined: boolean;
-}
+export type OnboardingProgress = z.infer<typeof OnboardingProgressSchema>;
 
 /**
- * Data collected at signup
- * used for onboarding and segments
- **/
-export interface SignupData {
-    accountType: string;
-    companyName?: string;
-    companySize?: number;
-    companyWebsite?: string;
-    maturity?: string;
-}
+ * Data collected at signup, used for onboarding and segments.
+ */
+export type SignupData = z.infer<typeof SignupDataSchema>;
 
 /**
- * Signup Payload: used to create a new user
+ * The `POST /auth/signup` request body.
  */
-export interface SignupPayload {
-    firebaseToken: string;
-    signupData: SignupData;
-}
+export type SignupPayload = z.infer<typeof SignupPayloadSchema>;

package/src/versions.ts

@@ -1,5 +1,29 @@
+/**
+ * The header a caller names an API version in, as `YYYYMMDD` — see {@link ApiVersions}.
+ *
+ * Declared here rather than in the client, because both ends of the negotiation need it: the
+ * servers register it with `withVersionHeader` and read it when deciding how strictly to hold a
+ * request to its published schema, and `@vertesia/client` sets it on every call. It kept the
+ * spelling it has always had on the wire.
+ */
+export const VERSION_HEADER = 'x-api-version';
+
 export enum ApiVersions {
     COMPLETION_RESULT_V1 = 20250925,
     DOWNLOAD_URL_NO_MIME_TYPE_V1 = 20260210,
     MEDIA_BLOB_STORAGE_V1 = 20260319,
+    /**
+     * Request bodies and parameters are rejected when they do not match the published component.
+     *
+     * The endpoints did not change shape at this date — the schemas they had always published
+     * started being enforced. A body carrying an undeclared property against a closed component,
+     * or a query parameter of the wrong type, used to be accepted and silently ignored; from here
+     * it is a 400.
+     *
+     * Unlike the milestones above, this one is not about a route: it gates the enforcement policy
+     * itself, so a caller pinned below it gets the old lenient behaviour on EVERY endpoint while
+     * the mismatch is logged. Sending nothing means the current API, so the strict reading is what
+     * a new caller gets by default and leniency has to be asked for.
+     */
+    REQUEST_CONTRACT_ENFORCEMENT_V1 = 20260803,
 }