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

package/src/access-control-values.ts

@@ -0,0 +1,113 @@
+/**
+ * Access-control values that exist at runtime — the enums and the scope list.
+ *
+ * Split out of `access-control.ts` and `roles/types.ts` for the same reason `account-values.ts` was
+ * split out of `user.ts`: the API schemas need these values (`z.enum(Permission)`,
+ * `z.enum(AbacScopes)`) while those two modules need the types the schemas infer. Keeping them where
+ * they were would make each import a module that imports it back; here, both sides depend on this
+ * module and nothing depends on them.
+ *
+ * Everything is re-exported from its original module, so existing import paths keep working — this
+ * is a move, not a rename.
+ */
+
+export enum Permission {
+    int_read = 'interaction:read',
+    int_write = 'interaction:write',
+    int_delete = 'interaction:delete',
+
+    int_execute = 'interaction:execute',
+    run_read = 'run:read',
+    run_write = 'run:write',
+
+    env_admin = 'environment:admin',
+
+    app_manage = 'app:manage',
+    project_admin = 'project:admin',
+    project_integration_read = 'project:integration_read',
+    project_settings_write = 'project:settings_write',
+
+    api_key_create = 'api_key:create',
+    api_key_read = 'api_key:read',
+    api_key_secret_read = 'api_key:secret_read',
+    api_key_update = 'api_key:update',
+    api_key_delete = 'api_key:delete',
+
+    account_read = 'account:read',
+    account_write = 'account:write',
+    account_admin = 'account:admin',
+    manage_billing = 'account:billing',
+    /** View cost and usage analytics */
+    billing_read = 'billing:read',
+    /** View account and project audit events. */
+    audit_read = 'audit:read',
+    account_member = 'account:member',
+
+    content_read = 'content:read',
+    content_read_all = 'content:read_all',
+    content_write = 'content:write',
+    content_delete = 'content:delete',
+    content_admin = 'content:admin', //manage schemas
+    content_superadmin = 'content:superadmin', // list all objects and collections
+
+    workflow_read = 'workflow:read',
+    workflow_run = 'workflow:run',
+    workflow_admin = 'workflow:admin',
+    workflow_superadmin = 'workflow:superadmin',
+
+    agent_run_read = 'agent_run:read',
+
+    task_read = 'task:read',
+    task_manage = 'task:manage',
+
+    iam_impersonate = 'iam:impersonate',
+
+    /** whether the user has access to Sutdio App. */
+    studio_access = 'studio:access',
+}
+
+export enum AccessControlResourceType {
+    project = 'project',
+    environment = 'environment',
+    account = 'account',
+    interaction = 'interaction',
+    app = 'application',
+    /**
+     * Dynamic resource matching by property conditions at query time. The role
+     * partitions (content, future tasks/etc.) determine which kind of object
+     * the conditions match — selected via `AceConditions.scope`.
+     *
+     * NOTE: the string value remains `'content_set'` for backward compatibility
+     * with stored ACEs and JWTs. The wire/DB rename to `'resource_set'` is a
+     * separate concern (deferred). Until then, code reads
+     * `AccessControlResourceType.resource_set` but the value on the wire stays
+     * `'content_set'`.
+     */
+    resource_set = 'content_set',
+}
+
+export enum AccessControlPrincipalType {
+    user = 'user',
+    group = 'group',
+    apikey = 'apikey',
+    /** Dynamic principal matching by user/group properties at token time. */
+    principal_set = 'principal_set',
+}
+
+/**
+ * Kind of object a ResourceSet's `resource_props` matches at query time. Used
+ * in `AceConditions.scope` (validated at runtime against this list) and as
+ * the prefix in JWT `content_security` keys (e.g. `collection:read`).
+ *
+ * Each scope is owned by exactly one partition. When adding a new partition
+ * (e.g. tasks), extend this list with the new scope(s) AND extend `RoleDomain`
+ * with the new domain.
+ */
+export const AbacScopes = ['document', 'collection', 'task'] as const;
+
+/**
+ * Logical grouping of roles by the service area that owns them. Declared as a
+ * runtime list so the role schemas can publish it as an enum component; the
+ * `RoleDomain` type is inferred from it in `roles/types.ts`.
+ */
+export const RoleDomains = ['system', 'content', 'tasks'] as const;

package/src/access-control.ts

@@ -1,93 +1,25 @@
+import type { z } from 'zod';
 /**
  * @module access-control
  * @description
  * Access control interfaces
  */
 
-import type { AbacScope } from './roles/types.js';
+import type { AccessControlResourceType } from './access-control-values.js';
+import type {
+    ACECreatePayloadSchema,
+    ACEUpdatePayloadSchema,
+    AccessControlEntrySchema,
+    AceConditionsSchema,
+    PropertyConditionsSchema,
+    PropertyConditionValueSchema,
+} from './api-schemas/access-control.js';
 
-export enum Permission {
-    int_read = 'interaction:read',
-    int_write = 'interaction:write',
-    int_delete = 'interaction:delete',
-
-    int_execute = 'interaction:execute',
-    run_read = 'run:read',
-    run_write = 'run:write',
-
-    env_admin = 'environment:admin',
-
-    app_manage = 'app:manage',
-    project_admin = 'project:admin',
-    project_integration_read = 'project:integration_read',
-    project_settings_write = 'project:settings_write',
-
-    api_key_create = 'api_key:create',
-    api_key_read = 'api_key:read',
-    api_key_secret_read = 'api_key:secret_read',
-    api_key_update = 'api_key:update',
-    api_key_delete = 'api_key:delete',
-
-    account_read = 'account:read',
-    account_write = 'account:write',
-    account_admin = 'account:admin',
-    manage_billing = 'account:billing',
-    /** View cost and usage analytics */
-    billing_read = 'billing:read',
-    /** View account and project audit events. */
-    audit_read = 'audit:read',
-    account_member = 'account:member',
-
-    content_read = 'content:read',
-    content_read_all = 'content:read_all',
-    content_write = 'content:write',
-    content_delete = 'content:delete',
-    content_admin = 'content:admin', //manage schemas
-    content_superadmin = 'content:superadmin', // list all objects and collections
-
-    workflow_read = 'workflow:read',
-    workflow_run = 'workflow:run',
-    workflow_admin = 'workflow:admin',
-    workflow_superadmin = 'workflow:superadmin',
-
-    agent_run_read = 'agent_run:read',
-
-    task_read = 'task:read',
-    task_manage = 'task:manage',
-
-    iam_impersonate = 'iam:impersonate',
-
-    /** whether the user has access to Sutdio App. */
-    studio_access = 'studio:access',
-}
-
-export enum AccessControlResourceType {
-    project = 'project',
-    environment = 'environment',
-    account = 'account',
-    interaction = 'interaction',
-    app = 'application',
-    /**
-     * Dynamic resource matching by property conditions at query time. The role
-     * partitions (content, future tasks/etc.) determine which kind of object
-     * the conditions match — selected via `AceConditions.scope`.
-     *
-     * NOTE: the string value remains `'content_set'` for backward compatibility
-     * with stored ACEs and JWTs. The wire/DB rename to `'resource_set'` is a
-     * separate concern (deferred). Until then, code reads
-     * `AccessControlResourceType.resource_set` but the value on the wire stays
-     * `'content_set'`.
-     */
-    resource_set = 'content_set',
-}
-
-export enum AccessControlPrincipalType {
-    user = 'user',
-    group = 'group',
-    apikey = 'apikey',
-    /** Dynamic principal matching by user/group properties at token time. */
-    principal_set = 'principal_set',
-}
+/**
+ * The enums live in `./access-control-values.js` so the API schemas can consume them without
+ * importing this module back. Re-exported here so every existing import path keeps working.
+ */
+export * from './access-control-values.js';
 
 /**
  * MongoDB query syntax subset for matching properties.
@@ -104,64 +36,27 @@ export enum AccessControlPrincipalType {
  * { region: { $in: ["us-east", "eu-west"] } }               // set membership (literal)
  * { security_level: { $lte: "$principal.access_level" } }   // cross-reference (resolved at token time)
  */
-/** A single condition value. Resolved and evaluated dynamically by token/content security code. */
-export type PropertyConditionValue = unknown;
-
-export type PropertyConditions = Record<string, PropertyConditionValue>;
+export type PropertyConditionValue = z.infer<typeof PropertyConditionValueSchema>;
+export type PropertyConditions = z.infer<typeof PropertyConditionsSchema>;
 
 /**
- * Conditions attached to an ACE for dynamic matching.
- * - `principal_props`: matched against user/group properties at token time (PrincipalSet).
- * - `resource_props`: matched against object properties at query time (ResourceSet).
+ * The access-control wire types, inferred from the schemas in `./api-schemas/access-control.js` —
+ * which are what OpenAPI publishes and AJV compiles. The field descriptions live there too, since
+ * Zod reads `.meta()` and not TSDoc.
+ *
+ * NOTE `conditions` carries ONLY the three fields it declares. The server stores two more there —
+ * `principal_name` / `resource_name`, see `IAceConditions` in `@dglabs/server-common` — and copies
+ * them into `principal` / `resource` on the way out. They are not part of this contract, and the
+ * response mappers drop them rather than serializing the sub-document.
  */
-export interface AceConditions {
-    /** Property conditions matched against user/group properties at token time (PrincipalSet). */
-    principal_props?: PropertyConditions;
-    /** Property conditions matched against object properties at query time (ResourceSet). */
-    resource_props?: PropertyConditions;
-    /**
-     * Kind of object the `resource_props` matches. Used to disambiguate which
-     * partition's roles apply (e.g. content roles vs task roles) and to form
-     * the JWT `content_security` key prefix (`{scope}:{verb}`). Absent →
-     * `'document'` (default; emits bare `read`/`write`/`delete` keys for
-     * backward compatibility).
-     */
-    scope?: AbacScope;
-}
-
-export interface AccessControlEntry {
-    /**
-     * Role name. Typed as `string` because role names now span multiple
-     * partitions: `SystemRoles` enum values for system-domain roles, and bare
-     * strings for ABAC-domain roles (e.g. `'content:reader'`,
-     * `'content:writer'`, `'content:manager'`). Mongoose schema validates the
-     * value against the registered role catalog via `getAllRoleNames()`.
-     */
-    role: string;
-    resource_type: AccessControlResourceType;
-    resource: string; //objectId
-    principal_type: AccessControlPrincipalType;
-    principal: string; //objectId
-    /** Account scope — required for principal_set/content_set ACEs. */
-    account?: string;
-    /** Project scope — narrows a principal_set/content_set ACE to a single project. */
-    project?: string;
-    /** Dynamic matching conditions for principal_set/content_set ACEs. */
-    conditions?: AceConditions;
-    tags?: string[];
-    expires_at?: string;
-    created_at?: string;
-    updated_at?: string;
-    id: string;
-}
-
-export interface ACECreatePayload extends Omit<AccessControlEntry, 'created_at' | 'updated_at' | 'id'> {}
-
-export interface ACEUpdatePayload extends Partial<ACECreatePayload> {}
-
-// RoleDefinition + SystemRoleDefinition now live in `./roles/types.js` to
-// avoid a circular import with `RoleDomain`. They remain re-exported via
-// the package's index.ts so consumers see no path change.
+export type AceConditions = z.infer<typeof AceConditionsSchema>;
+export type AccessControlEntry = z.infer<typeof AccessControlEntrySchema>;
+export type ACECreatePayload = z.infer<typeof ACECreatePayloadSchema>;
+export type ACEUpdatePayload = z.infer<typeof ACEUpdatePayloadSchema>;
+
+// RoleDefinition + SystemRoleDefinition now live in `./roles/types.js`, and are likewise inferred
+// from `./api-schemas/access-control.js`. They remain re-exported via the package's index.ts so
+// consumers see no path change.
 
 // ============================================================================
 // BLP Security Levels

package/src/account-values.ts

@@ -0,0 +1,95 @@
+/**
+ * Account values that exist at runtime — enums, constants, and the pure helpers over them.
+ *
+ * Split out of `user.ts` so the dependency direction can run one way. The API schemas need these
+ * values (`z.enum(BillingMethod)`, `.max(ACCOUNT_APP_ACCESS_MESSAGE_MAX_LENGTH)`), and `user.ts`
+ * needs the types the schemas infer. Both living in `user.ts` would make it import from a module
+ * that imports it back; here, `user.ts` and `api-schemas/account.ts` both depend on this module and
+ * nothing depends on them.
+ *
+ * Everything here is re-exported from `user.ts`, so existing import paths keep working — this is a
+ * move, not a rename.
+ */
+
+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',
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+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;
+}

package/src/agent-resources.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import { type AgentResourceReference, getResourcesFromToolResult, normalizeAgentResources } from './interaction.js';
+import { AgentMessageType, getResourcesFromMessage } from './store/workflow.js';
+
+const validRef: AgentResourceReference = {
+    type: 'document',
+    id: 'doc-1',
+    label: 'My Document',
+    action: 'created',
+};
+
+describe('normalizeAgentResources', () => {
+    it('returns an empty array for non-array input', () => {
+        expect(normalizeAgentResources(undefined)).toEqual([]);
+        expect(normalizeAgentResources(null)).toEqual([]);
+        expect(normalizeAgentResources('nope')).toEqual([]);
+        expect(normalizeAgentResources({})).toEqual([]);
+    });
+
+    it('keeps a well-formed reference', () => {
+        expect(normalizeAgentResources([validRef])).toEqual([validRef]);
+    });
+
+    it('preserves revision_id when present and non-empty', () => {
+        const ref = { ...validRef, revision_id: 'rev-9' };
+        expect(normalizeAgentResources([ref])).toEqual([ref]);
+    });
+
+    it('drops an empty revision_id rather than keeping it', () => {
+        const result = normalizeAgentResources([{ ...validRef, revision_id: '' }]);
+        expect(result[0]).not.toHaveProperty('revision_id');
+    });
+
+    it('falls back to the id when the label is missing or empty', () => {
+        const result = normalizeAgentResources([{ type: 'collection', id: 'col-1', action: 'updated' }]);
+        expect(result).toEqual([{ type: 'collection', id: 'col-1', label: 'col-1', action: 'updated' }]);
+    });
+
+    it('drops entries with an unknown type or action', () => {
+        const result = normalizeAgentResources([
+            { type: 'artifact', id: 'a', label: 'a', action: 'created' },
+            { type: 'document', id: 'd', label: 'd', action: 'viewed' },
+            { type: 'document', id: '', label: 'd', action: 'created' },
+            validRef,
+        ]);
+        expect(result).toEqual([validRef]);
+    });
+
+    it('accepts every supported resource type', () => {
+        const types = [
+            'document',
+            'collection',
+            'content_type',
+            'interaction',
+            'prompt',
+            'agent',
+            'workflow',
+            'process',
+            'process_run',
+            'interaction_run',
+            'view',
+        ] as const;
+        const input = types.map((type, i) => ({ type, id: `id-${i}`, label: `L${i}`, action: 'created' }));
+        expect(normalizeAgentResources(input)).toHaveLength(types.length);
+    });
+});
+
+describe('getResourcesFromToolResult', () => {
+    it('reads resources from result meta', () => {
+        expect(getResourcesFromToolResult({ meta: { resources: [validRef] } })).toEqual([validRef]);
+    });
+
+    it('returns an empty array when meta or resources are absent', () => {
+        expect(getResourcesFromToolResult({})).toEqual([]);
+        expect(getResourcesFromToolResult({ meta: {} })).toEqual([]);
+    });
+});
+
+describe('getResourcesFromMessage', () => {
+    it('reads resources from message details', () => {
+        const msg = {
+            timestamp: 0,
+            workflow_run_id: 'run-1',
+            type: AgentMessageType.THOUGHT,
+            message: '',
+            details: { event_class: 'activity', resources: [validRef] },
+        };
+        expect(getResourcesFromMessage(msg)).toEqual([validRef]);
+    });
+
+    it('returns an empty array when details or resources are absent', () => {
+        const msg = {
+            timestamp: 0,
+            workflow_run_id: 'run-1',
+            type: AgentMessageType.COMPLETE,
+            message: '',
+        };
+        expect(getResourcesFromMessage(msg)).toEqual([]);
+    });
+});

package/src/analytics.ts

@@ -1,50 +1,26 @@
-export interface AnalyticsAxis {
-    environment?: string;
-    project?: string;
-    interactions?: string[];
-    models?: string[];
-    status?: string[];
-    tags?: string[];
-    selectedOnly?: boolean;
-}
-
-export interface RunAnalyticsQuery {
-    /** filters to apply to the query */
-    filterBy: AnalyticsAxis;
-
-    /** The field to group by */
-    groupBy?: RunAnalyticsGroupBy;
-
-    /** The start date of the query in EPOCH format */
-    from?: number;
-    /** The end date of the query in EPOCH format */
-    to?: number;
+import type { z } from 'zod';
+import type {
+    AnalyticsAxisSchema,
+    RunAnalyticsGroupBySchema,
+    RunAnalyticsQuerySchema,
+    RunAnalyticsResultSchema,
+    TimeResolutionSchema,
+} from './api-schemas/analytics.js';
 
-    /** The time resolution unit of the analytics query */
-    resolution?: TimeResolution;
+/**
+ * The five run-analytics contract types, inferred from `./api-schemas/analytics.js`. Their
+ * documentation moved with them — a doc comment here would be published on TOP of the schema's
+ * `description` and the two would drift.
+ */
+export type AnalyticsAxis = z.infer<typeof AnalyticsAxisSchema>;
 
-    /** The step size for the resolution (e.g., 4 with resolution='hour' means 4-hour intervals). Defaults to 1. */
-    resolutionStep?: number;
+export type RunAnalyticsQuery = z.infer<typeof RunAnalyticsQuerySchema>;
 
-    /** The field to sort by */
-    virtual?: boolean;
-}
-
-export type RunAnalyticsGroupBy = 'interaction' | 'modelId' | 'project' | 'status' | 'tags' | 'environment';
+export type RunAnalyticsGroupBy = z.infer<typeof RunAnalyticsGroupBySchema>;
 
-export type TimeResolution = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
+export type TimeResolution = z.infer<typeof TimeResolutionSchema>;
 
-export interface RunAnalyticsResult {
-    date: string;
-    timestamp: string;
-    group: string;
-    count: number;
-    execution_time: {
-        avg: number;
-        min: number;
-        max: number;
-    };
-}
+export type RunAnalyticsResult = z.infer<typeof RunAnalyticsResultSchema>;
 
 /** Entity with status breakdown */
 export interface EntityStatusCounts {