@vertesia/common 1.3.0 → 1.4.0-dev.20260615.042033Z

package/src/environment.ts

@@ -1,22 +1,18 @@
-import type {
-    AIModel,
-    ProviderParams,
-    TextFallbackOptions
-} from "@llumiverse/common";
-import { ProviderList, Providers } from "@llumiverse/common";
+import type { AIModel, ProviderParams, TextFallbackOptions } from '@llumiverse/common';
+import { ProviderList, Providers } from '@llumiverse/common';
 
 // Virtual providers from studio
 export enum CustomProviders {
     virtual_lb = 'virtual_lb',
     virtual_mediator = 'virtual_mediator',
-    test = 'test'
+    test = 'test',
 }
 
 export type SupportedProviders = Providers | CustomProviders;
 
 export const SupportedProviders = {
     ...Providers,
-    ...CustomProviders
+    ...CustomProviders,
 } as const;
 
 export interface SupportedProviderParams extends Omit<ProviderParams, 'id'> {
@@ -24,25 +20,23 @@ export interface SupportedProviderParams extends Omit<ProviderParams, 'id'> {
 }
 
 export const CustomProvidersList: Record<CustomProviders, SupportedProviderParams> = {
-    virtual_lb:
-    {
+    virtual_lb: {
         id: CustomProviders.virtual_lb,
-        name: "Virtual - Load Balancer",
+        name: 'Virtual - Load Balancer',
         requiresApiKey: false,
         requiresEndpointUrl: false,
         supportSearch: false,
     },
-    virtual_mediator:
-    {
+    virtual_mediator: {
         id: CustomProviders.virtual_mediator,
-        name: "Virtual - Mediator",
+        name: 'Virtual - Mediator',
         requiresApiKey: false,
         requiresEndpointUrl: false,
         supportSearch: false,
     },
     test: {
         id: CustomProviders.test,
-        name: "Test LLM",
+        name: 'Test LLM',
         requiresApiKey: false,
         requiresEndpointUrl: false,
         supportSearch: false,
@@ -51,10 +45,9 @@ export const CustomProvidersList: Record<CustomProviders, SupportedProviderParam
 
 export const SupportedProvidersList: Record<SupportedProviders, SupportedProviderParams> = {
     ...ProviderList,
-    ...CustomProvidersList
+    ...CustomProvidersList,
 } as const;
 
-
 export interface VirtualEnvEntry {
     model: string;
 }
@@ -84,6 +77,24 @@ export interface MediatorEnvConfig {
     model_options?: TextFallbackOptions;
 }
 
+export interface ExecutionEnvironmentSettings {
+    [key: string]: unknown;
+    bucket_access_principal?: string;
+}
+
+/**
+ * Returns the configured Vertex AI bucket access principal for an environment, or undefined.
+ * Only Vertex AI environments expose this setting; the value is trimmed and empty strings
+ * are treated as unset so callers get a single, normalized representation.
+ */
+export function getVertexBucketAccessPrincipal(
+    env: { provider?: SupportedProviders; settings?: ExecutionEnvironmentSettings } | undefined,
+): string | undefined {
+    if (!env || env.provider !== SupportedProviders.vertexai) return undefined;
+    const principal = env.settings?.bucket_access_principal;
+    return typeof principal === 'string' && principal.trim().length > 0 ? principal.trim() : undefined;
+}
+
 export interface ExecutionEnvironment {
     id: string;
     name: string;
@@ -98,16 +109,16 @@ export interface ExecutionEnvironment {
      * Stored alongside the encrypted key so the UI can display which key is configured.
      */
     apikey_hint?: string;
-    config?: any;
+    config?: unknown;
     /**
      * Additional provider-specific settings passed through to the driver.
      * For example, custom headers for Apigee-proxied endpoints.
      */
-    settings?: Record<string, unknown>;
+    settings?: ExecutionEnvironmentSettings;
     account: string;
     allowed_projects?: string[];
-    created_by: string,
-    updated_by: string,
+    created_by: string;
+    updated_by: string;
     created_at: string;
     updated_at: string;
 }
@@ -127,10 +138,18 @@ export interface ExecutionEnvironmentRef {
     updated_at: string;
 }
 
-export const ExecutionEnvironmentRefPopulate = "id name provider enabled_models default_model endpoint_url allowed_projects account created_at updated_at";
-
-export interface ExecutionEnvironmentCreatePayload extends Omit<ExecutionEnvironment, 'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project' | 'apikey_hint'> { }
-export interface ExecutionEnvironmentUpdatePayload extends Partial<Omit<ExecutionEnvironment, 'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'apikey_hint'>> { }
+export interface ExecutionEnvironmentCreatePayload
+    extends Omit<
+        ExecutionEnvironment,
+        'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project' | 'apikey_hint'
+    > {}
+export interface ExecutionEnvironmentUpdatePayload
+    extends Partial<
+        Omit<
+            ExecutionEnvironment,
+            'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'apikey_hint'
+        >
+    > {}
 export interface ExecutionEnvironmentConfigUpdatePayload {
     enabled_models?: AIModel[];
     config?: MediatorEnvConfig | LoadBalancingEnvConfig;

package/src/facets.ts

@@ -1,27 +1,25 @@
-
 // this is the mongo definition of a facet. see https://www.mongodb.com/docs/atlas/atlas-search/facet/
 export interface StringFacet {
-    type: "string",
-    path: string,
-    numBuckets?: number,
+    type: 'string';
+    path: string;
+    numBuckets?: number;
 }
 
 export interface NumericFacet {
-    type: "number",
-    path: string,
-    boundaries: number[],
-    default?: string
+    type: 'number';
+    path: string;
+    boundaries: number[];
+    default?: string;
 }
 
-export interface DateFacet<T extends (Date | string) = string> {
-    type: "date",
-    path: string,
-    boundaries: T[], // array of dates
-    default?: string
+export interface DateFacet<T extends Date | string = string> {
+    type: 'date';
+    path: string;
+    boundaries: T[]; // array of dates
+    default?: string;
 }
 
-export type Facet<DateT extends (Date | string) = string> = StringFacet | NumericFacet | DateFacet<DateT>;
-
+export type Facet<DateT extends Date | string = string> = StringFacet | NumericFacet | DateFacet<DateT>;
 
 export interface FacetSpec {
     name: string;
@@ -29,18 +27,18 @@ export interface FacetSpec {
 }
 
 export interface FacetBucket {
-    _id: string,
-    count: number,
+    _id: string;
+    count: number;
 }
 
 export interface FacetNameBucket {
-    name: string,
-    _id: string,
-    count: number,
+    name: string;
+    _id: string;
+    count: number;
 }
 
 export interface FacetResult {
-    buckets: FacetBucket[]
+    buckets: FacetBucket[];
 }
 
 export interface ComputedFacetBucket {

package/src/group.ts

@@ -1,5 +1,4 @@
-import { UserRef } from "./user.js";
-
+import type { UserRef } from './user.js';
 
 export interface UserGroup {
     id: string;
@@ -12,7 +11,7 @@ export interface UserGroup {
     created_by?: string;
     updated_by?: string;
     /** Custom properties for dynamic permission matching */
-    properties?: Record<string, any>;
+    properties?: Record<string, unknown>;
     /** BLP clearance level — merged with user clearance using max() */
     clearance?: number;
     /** Compartments — merged with user compartments using array union */
@@ -33,7 +32,7 @@ export interface UpdateUserGroupPayload {
     name: string;
     description?: string;
     tags?: string[];
-    properties?: Record<string, any>;
+    properties?: Record<string, unknown>;
     clearance?: number;
     compartments?: string[];
 }
@@ -42,7 +41,7 @@ export interface UserGroupRef {
     id: string;
     name: string;
     tags?: string[];
-    properties?: Record<string, any>;
+    properties?: Record<string, unknown>;
     clearance?: number;
     compartments?: string[];
 }

package/src/host-utils.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import {
+    hostFromUrl,
+    hostMatchesAny,
+    isLocalhostOrVertesiaHost,
+    isLocalhostOrVertesiaUrl,
+    normalizeHost,
+    normalizeHostList,
+    urlMatchesAnyHost,
+} from './host-utils.js';
+
+describe('host-utils', () => {
+    it('normalizes hosts, URLs, wildcards, ports, and IPv6 brackets', () => {
+        expect(normalizeHost(' HTTPS://App.Example.COM:443/login ')).toBe('app.example.com');
+        expect(normalizeHost('*.example.com')).toBe('example.com');
+        expect(normalizeHost('https://*.example.com/login')).toBe('example.com');
+        expect(normalizeHost('localhost:3000')).toBe('localhost');
+        expect(normalizeHost('::1')).toBe('::1');
+        expect(normalizeHost('[::1]:3000')).toBe('::1');
+    });
+
+    it('rejects empty and malformed hosts', () => {
+        expect(normalizeHost('')).toBeUndefined();
+        expect(normalizeHost('bad host')).toBeUndefined();
+        expect(normalizeHost('example.com:bad')).toBeUndefined();
+    });
+
+    it('extracts hosts only from absolute URLs', () => {
+        expect(hostFromUrl('https://science.nasa.gov/exoplanets')).toBe('science.nasa.gov');
+        expect(hostFromUrl('science.nasa.gov/exoplanets')).toBeUndefined();
+        expect(hostFromUrl('/exoplanets', 'https://science.nasa.gov/search')).toBe('science.nasa.gov');
+    });
+
+    it('deduplicates normalized host lists', () => {
+        expect(normalizeHostList(['example.com', 'https://example.com/login', 'bad host'])).toEqual(['example.com']);
+    });
+
+    it('matches exact hosts and subdomains but fails closed for malformed hosts', () => {
+        expect(hostMatchesAny('login.example.com', ['example.com'])).toBe(true);
+        expect(hostMatchesAny('example.com', ['example.com'])).toBe(true);
+        expect(hostMatchesAny('evil-example.com', ['example.com'])).toBe(false);
+        expect(hostMatchesAny('bad host', ['example.com'])).toBe(false);
+        expect(hostMatchesAny('bad host', [])).toBe(true);
+    });
+
+    it('matches URLs against host allowlists', () => {
+        expect(urlMatchesAnyHost('https://login.example.com/path', ['example.com'])).toBe(true);
+        expect(urlMatchesAnyHost('/settings', ['example.com'], 'https://login.example.com/home')).toBe(true);
+        expect(urlMatchesAnyHost('http://[::1]:3000/app', ['::1'])).toBe(true);
+        expect(urlMatchesAnyHost('not a url', ['example.com'])).toBe(false);
+    });
+
+    it('identifies localhost and Vertesia hosts for browser auth', () => {
+        expect(isLocalhostOrVertesiaHost('localhost')).toBe(true);
+        expect(isLocalhostOrVertesiaHost('[::1]')).toBe(true);
+        expect(isLocalhostOrVertesiaUrl('http://[::1]:3000/app')).toBe(true);
+        expect(isLocalhostOrVertesiaUrl('https://studio.vertesia.io')).toBe(true);
+        expect(isLocalhostOrVertesiaUrl('https://evilvertesia.io')).toBe(false);
+        expect(isLocalhostOrVertesiaUrl('not a url')).toBe(false);
+    });
+});

package/src/host-utils.ts

@@ -0,0 +1,93 @@
+function stripLeadingWildcard(host: string): string {
+    return host.startsWith('*.') ? host.slice(2) : host;
+}
+
+function stripIPv6Brackets(host: string): string {
+    return host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+}
+
+function looksLikeBareIpv6(host: string): boolean {
+    const firstColon = host.indexOf(':');
+    return firstColon >= 0 && host.indexOf(':', firstColon + 1) >= 0 && !host.startsWith('[');
+}
+
+function hasWhitespace(host: string): boolean {
+    return (
+        host.includes(' ') ||
+        host.includes('\t') ||
+        host.includes('\n') ||
+        host.includes('\r') ||
+        host.includes('\f') ||
+        host.includes('\v')
+    );
+}
+
+export function normalizeHost(value: unknown): string | undefined {
+    if (typeof value !== 'string') return undefined;
+    let input = value.trim().toLowerCase();
+    if (!input) return undefined;
+    input = stripLeadingWildcard(input);
+    input = input.endsWith('.') ? input.slice(0, -1) : input;
+
+    if (!input.includes('://')) {
+        input = looksLikeBareIpv6(input) ? `https://[${input}]` : `https://${input}`;
+    }
+
+    try {
+        const url = new URL(input);
+        let host = stripLeadingWildcard(stripIPv6Brackets(url.hostname.toLowerCase()));
+        host = host.endsWith('.') ? host.slice(0, -1) : host;
+        return host && !hasWhitespace(host) ? host : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+export function hostFromUrl(value: string, baseUrl?: string): string | undefined {
+    try {
+        const url = baseUrl ? new URL(value, baseUrl) : new URL(value);
+        return normalizeHost(url.hostname);
+    } catch {
+        return undefined;
+    }
+}
+
+export function normalizeHostList(value: unknown): string[] {
+    if (!Array.isArray(value)) return [];
+    return Array.from(new Set(value.map((entry) => normalizeHost(entry)).filter((entry): entry is string => !!entry)));
+}
+
+export function hostMatchesAny(host: string, allowlist: readonly string[] | undefined): boolean {
+    if (!allowlist || allowlist.length === 0) return true;
+    const normalizedHost = normalizeHost(host);
+    if (!normalizedHost) return false;
+    return allowlist.some((entry) => {
+        const normalizedEntry = normalizeHost(entry);
+        return (
+            !!normalizedEntry && (normalizedHost === normalizedEntry || normalizedHost.endsWith(`.${normalizedEntry}`))
+        );
+    });
+}
+
+export function urlMatchesAnyHost(url: string, allowlist: readonly string[] | undefined, baseUrl?: string): boolean {
+    if (!allowlist || allowlist.length === 0) return true;
+    const host = hostFromUrl(url, baseUrl);
+    return !!host && hostMatchesAny(host, allowlist);
+}
+
+export function isLocalhostOrVertesiaHost(value: string | undefined): boolean {
+    const host = normalizeHost(value);
+    return (
+        !!host &&
+        (host === 'localhost' ||
+            host === '127.0.0.1' ||
+            host === '::1' ||
+            host === 'vertesia.io' ||
+            host.endsWith('.vertesia.io'))
+    );
+}
+
+export function isLocalhostOrVertesiaUrl(value: string): boolean {
+    const host = hostFromUrl(value);
+    return isLocalhostOrVertesiaHost(host);
+}

package/src/index.ts

@@ -1,40 +1,48 @@
 export * from './access-control.js';
+export * from './agent-request-template.js';
 export * from './analytics.js';
-export * from './audit-trail.js';
-export * from './cost-analytics.js';
 export * from './apikey.js';
 export * from './apps.js';
 export * from './ask-user.js';
+export * from './audit-trail.js';
+export * from './browser-credentials.js';
 export * from './channels.js';
 export * from './common.js';
+export * from './cost-analytics.js';
 export * from './data-platform.js';
+export * from './embeddings.js';
 export * from './environment.js';
-export * from "./facets.js";
+export * from './facets.js';
 export * from './group.js';
+export * from './host-utils.js';
 export * from './integrations.js';
 export * from './interaction.js';
-export * from './pending-asks.js';
-export * from './json-schema.js';
 export * from './json.js';
+export * from './json-schema.js';
 export * from './meters.js';
-export * from './oauth-server.js';
 export * from './model_utility.js';
-export * from './openapi.js';
 export * from './oauth.js';
+export * from './oauth-scopes.js';
+export * from './oauth-server.js';
+export * from './Progress.js';
 export * from './payload.js';
-export * from "./Progress.js";
+export * from './pending-asks.js';
+export * from './principal-context.js';
 export * from './project.js';
 export * from './prompt.js';
 export * from './query.js';
 export * from './rate-limiter.js';
 export * from './refs.js';
+export * from './roles.js';
 export * from './runs.js';
+export * from './secrets.js';
 export * from './skill.js';
-export * from "./store/index.js";
+export * from './store/index.js';
 export * from './sts-token-types.js';
 export * from './tenant.js';
 export * from './tool-execution.js';
-export * from "./training.js";
+export * from './tools.js';
+export * from './training.js';
 export * from './transient-tokens.js';
 export * from './user.js';
 export * from './utils/auth.js';