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

package/src/json-schema.ts

@@ -4,4 +4,4 @@ export type {
     JSONSchemaObject,
     JSONSchemaType,
     JSONSchemaTypeName,
-} from "@llumiverse/common";
+} from '@llumiverse/common';

package/src/json.ts

@@ -1,4 +1,7 @@
 export type {
-    JSONArray, JSONComposite, JSONObject,
-    JSONPrimitive, JSONValue
-} from "@llumiverse/common";
+    JSONArray,
+    JSONComposite,
+    JSONObject,
+    JSONPrimitive,
+    JSONValue,
+} from '@llumiverse/common';

package/src/meters.ts

@@ -1,5 +1,4 @@
-import { BillingMethod } from "./user.js";
-
+import type { BillingMethod } from './user.js';
 
 export interface MeterAdjustment {
     meter: string;
@@ -7,7 +6,6 @@ export interface MeterAdjustment {
     identifier?: string;
 }
 
-
 export interface AdjustMetersMeterWorkflowParams {
     adjustments: MeterAdjustment[];
 }
@@ -21,10 +19,9 @@ export enum MeterNames {
     task_run = 'task_run',
 }
 
-
 export interface StripeBillingStatusResponse {
-    status: 'enabled' | 'disabled',
-    billing_method: BillingMethod | null,
-    portal_url?: string,
-    reason?: string
-}
+    status: 'enabled' | 'disabled';
+    billing_method: BillingMethod | null;
+    portal_url?: string;
+    reason?: string;
+}

package/src/model_utility.ts

@@ -1 +1 @@
-export { supportsToolUse } from "@llumiverse/common";
+export { supportsToolUse } from '@llumiverse/common';

package/src/oauth-scopes.ts

@@ -0,0 +1,72 @@
+import { Permission } from './access-control.js';
+
+export const OAUTH_SCOPE_OPENID = 'openid';
+export const OAUTH_SCOPE_PROFILE = 'profile';
+export const OAUTH_SCOPE_OFFLINE_ACCESS = 'offline_access';
+
+export const OAUTH_STANDARD_SCOPES = [OAUTH_SCOPE_OPENID, OAUTH_SCOPE_PROFILE, OAUTH_SCOPE_OFFLINE_ACCESS] as const;
+
+export type OAuthStandardScope = (typeof OAUTH_STANDARD_SCOPES)[number];
+
+const NON_OAUTH_PERMISSION_SCOPES = new Set<Permission>([
+    Permission.api_key_secret_read,
+    Permission.manage_billing,
+    Permission.billing_read,
+    Permission.iam_impersonate,
+    Permission.studio_access,
+]);
+const OAUTH_PERMISSION_SCOPES = Object.values(Permission).filter((scope) => !NON_OAUTH_PERMISSION_SCOPES.has(scope));
+const OAUTH_STANDARD_SCOPE_SET = new Set<string>(OAUTH_STANDARD_SCOPES);
+const OAUTH_PERMISSION_SCOPE_SET = new Set<string>(OAUTH_PERMISSION_SCOPES);
+const OBJECT_ID_PATTERN = /^[0-9a-f]{24}$/i;
+const OAUTH_PROJECT_BINDING_SCOPE_PREFIX = 'project:';
+
+export function getOAuthPermissionScopes(): Permission[] {
+    return [...OAUTH_PERMISSION_SCOPES];
+}
+
+export function isOAuthStandardScope(scope: string): scope is OAuthStandardScope {
+    return OAUTH_STANDARD_SCOPE_SET.has(scope);
+}
+
+export function isOAuthPermissionScope(scope: string): scope is Permission {
+    return OAUTH_PERMISSION_SCOPE_SET.has(scope);
+}
+
+export function isOAuthSupportedScope(scope: string): boolean {
+    return isOAuthStandardScope(scope) || isOAuthPermissionScope(scope);
+}
+
+export function isOAuthProjectBindingScope(scope: string): boolean {
+    if (!scope.startsWith(OAUTH_PROJECT_BINDING_SCOPE_PREFIX)) {
+        return false;
+    }
+    return OBJECT_ID_PATTERN.test(scope.slice(OAUTH_PROJECT_BINDING_SCOPE_PREFIX.length));
+}
+
+export function createOAuthProjectBindingScope(projectId: string): string {
+    return `${OAUTH_PROJECT_BINDING_SCOPE_PREFIX}${projectId}`;
+}
+
+export function hasOAuthOpenIdScope(scopes: readonly string[]): boolean {
+    return scopes.includes(OAUTH_SCOPE_OPENID);
+}
+
+export function hasOAuthProfileScope(scopes: readonly string[]): boolean {
+    return scopes.includes(OAUTH_SCOPE_PROFILE);
+}
+
+export function hasOAuthOfflineAccessScope(scopes: readonly string[]): boolean {
+    return scopes.includes(OAUTH_SCOPE_OFFLINE_ACCESS);
+}
+
+export function getOAuthScopesWithProfileDependency(scopes: readonly string[]): string[] {
+    if (!hasOAuthOpenIdScope(scopes)) {
+        return scopes.filter((scope) => scope !== OAUTH_SCOPE_PROFILE);
+    }
+    return [...scopes];
+}
+
+export function extractOAuthPermissionScopes(scopes: readonly string[]): Permission[] {
+    return scopes.filter(isOAuthPermissionScope);
+}

package/src/oauth-server.ts

@@ -1,4 +1,4 @@
-import type { AuthTokenPayload } from './apikey.js';
+import type { AuthTokenPayload, PrincipalType } from './apikey.js';
 import type { ProjectRef } from './project.js';
 
 export type OAuthClientType = 'public' | 'confidential';
@@ -6,12 +6,25 @@ export type OAuthClientStatus = 'active' | 'disabled';
 export type OAuthRegistrationSource = 'admin' | 'dynamic';
 export type OAuthProjectBindingMode = 'user_select' | 'fixed';
 export type OAuthTokenEndpointAuthMethod = 'none' | 'client_secret_post' | 'client_secret_basic';
-export type OAuthGrantType = 'authorization_code' | 'refresh_token';
+export type OAuthGrantType = 'authorization_code' | 'refresh_token' | 'urn:ietf:params:oauth:grant-type:device_code';
 export type OAuthResponseType = 'code';
 export type OAuthAuthorizationRequestStatus = 'pending' | 'denied' | 'consumed';
 export type OAuthClientRegistrationMode = 'registered' | 'client_id_metadata_document';
+/**
+ * How Vertesia identified itself to a *remote* authorization server when connecting
+ * out as an OAuth client. Distinct from {@link OAuthClientRegistrationMode}, which
+ * describes how inbound clients identified themselves to Vertesia's own AS.
+ */
+export type RemoteOAuthRegistrationMode = 'dynamic_client_registration' | 'client_id_metadata_document';
 export type OAuthGrantStatus = 'active' | 'revoked' | 'expired';
-export type OAuthGrantSortField = 'granted_at' | 'client_name' | 'user_name' | 'resource' | 'last_used_at' | 'expires_at' | 'status';
+export type OAuthGrantSortField =
+    | 'granted_at'
+    | 'client_name'
+    | 'user_name'
+    | 'resource'
+    | 'last_used_at'
+    | 'expires_at'
+    | 'status';
 export type OAuthGrantSortOrder = 'asc' | 'desc';
 
 export interface OAuthClientData {
@@ -22,6 +35,7 @@ export interface OAuthClientData {
     response_types: OAuthResponseType[];
     token_endpoint_auth_method: OAuthTokenEndpointAuthMethod;
     allowed_scopes: string[];
+    default_scopes?: string[];
     registration_source: OAuthRegistrationSource;
     status: OAuthClientStatus;
     project_binding_mode: OAuthProjectBindingMode;
@@ -41,6 +55,10 @@ export interface OAuthClientCreateResponse extends OAuthClient {
     client_secret?: string;
 }
 
+export interface OAuthClientScopeMetadata {
+    supported_scopes: string[];
+}
+
 export interface OAuthGrant {
     grant_id: string;
     client_id: string;
@@ -98,6 +116,7 @@ export interface CreateOAuthClientPayload {
     response_types?: OAuthResponseType[];
     token_endpoint_auth_method?: OAuthTokenEndpointAuthMethod;
     allowed_scopes?: string[];
+    default_scopes?: string[];
     project_binding_mode?: OAuthProjectBindingMode;
     fixed_project_id?: string;
     client_secret?: string;
@@ -111,6 +130,7 @@ export interface UpdateOAuthClientPayload {
     response_types?: OAuthResponseType[];
     token_endpoint_auth_method?: OAuthTokenEndpointAuthMethod;
     allowed_scopes?: string[];
+    default_scopes?: string[];
     status?: OAuthClientStatus;
     project_binding_mode?: OAuthProjectBindingMode;
     fixed_project_id?: string;
@@ -131,6 +151,7 @@ export interface OAuthAuthorizationServerMetadata {
     token_endpoint_auth_methods_supported: string[];
     scopes_supported: string[];
     client_id_metadata_document_supported?: boolean;
+    device_authorization_endpoint?: string;
 }
 
 export interface OAuthClientMetadataDocument {
@@ -178,6 +199,7 @@ export interface OAuthAuthorizationRequest {
     redirect_origin: string;
     resource?: string;
     requested_scopes: string[];
+    optional_scopes?: string[];
     requested_project_id?: string;
     project_binding_mode: OAuthProjectBindingMode;
     fixed_project_id?: string;
@@ -188,12 +210,36 @@ export interface OAuthAuthorizationRequest {
 
 export interface ApproveOAuthAuthorizationRequestPayload {
     project_id?: string;
+    granted_scopes: string[];
+}
+
+export interface OAuthGrantableScopesResponse {
+    project_id: string;
+    requested_permission_scopes: string[];
+    grantable_permission_scopes: string[];
+    unavailable_permission_scopes: string[];
 }
 
 export interface OAuthAuthorizationDecisionResponse {
     redirect_url: string;
 }
 
+export interface OAuthDeviceAuthorizationRequest {
+    client_id: string;
+    resource?: string;
+    scope?: string;
+    project_id?: string;
+}
+
+export interface OAuthDeviceAuthorizationResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+
 export interface OAuthTokenRequestAuthorizationCode {
     grant_type: 'authorization_code';
     code: string;
@@ -209,10 +255,21 @@ export interface OAuthTokenRequestRefreshToken {
     refresh_token: string;
     client_id: string;
     resource?: string;
+    project_id?: string;
+    client_secret?: string;
+}
+
+export interface OAuthTokenRequestDeviceCode {
+    grant_type: 'urn:ietf:params:oauth:grant-type:device_code';
+    device_code: string;
+    client_id: string;
     client_secret?: string;
 }
 
-export type OAuthTokenRequest = OAuthTokenRequestAuthorizationCode | OAuthTokenRequestRefreshToken;
+export type OAuthTokenRequest =
+    | OAuthTokenRequestAuthorizationCode
+    | OAuthTokenRequestRefreshToken
+    | OAuthTokenRequestDeviceCode;
 
 export interface OAuthTokenResponse {
     access_token: string;
@@ -248,7 +305,7 @@ export interface OAuthConsentRecord {
 }
 
 export interface OAuthAccessTokenPayload extends Omit<AuthTokenPayload, 'type' | 'project'> {
-    type: 'oauth_access';
+    type: PrincipalType.OAuthAccess;
     client_id: string;
     scope: string;
     user_id: string;
@@ -260,13 +317,13 @@ export interface OAuthAccessTokenPayload extends Omit<AuthTokenPayload, 'type' |
 export interface OAuthIdTokenPayload {
     sub: string;
     user_id: string;
-    name: string;
+    name?: string;
     email?: string;
     picture?: string;
     type: 'oauth_id';
     client_id: string;
-    account: AuthTokenPayload['account'];
-    accounts: AuthTokenPayload['accounts'];
+    account?: AuthTokenPayload['account'];
+    accounts?: AuthTokenPayload['accounts'];
     project?: ProjectRef;
     /** User groups */
     groups?: AuthTokenPayload['groups'];

package/src/payload.ts

@@ -1,5 +1,5 @@
-import { FacetSpec } from "./facets.js";
-import {
+import type { FacetSpec } from './facets.js';
+import type {
     ComplexCollectionSearchQuery,
     ComplexSearchQuery,
     InteractionSearchQuery,
@@ -7,9 +7,9 @@ import {
     ObjectTypeSearchQuery,
     PromptSearchQuery,
     RunSearchQuery,
-    SimpleSearchQuery
-} from "./query.js";
-import { ColumnLayout } from "./store/store.js";
+    SimpleSearchQuery,
+} from './query.js';
+import type { ColumnLayout } from './store/store.js';
 
 export type SortOrder = 'asc' | 'desc';
 
@@ -94,5 +94,5 @@ export interface ExportPropertiesPayload {
 export interface ExportPropertiesResponse {
     type: string;
     name: string;
-    data: Blob;
+    data: string;
 }

package/src/pending-asks.ts

@@ -3,7 +3,8 @@
  * Used to notify external systems when agents are waiting for user input.
  */
 
-import { UserChannel } from "./email.js";
+import type { UserChannel } from './email.js';
+import type { TaskField } from './store/task.js';
 
 // ================= Pending Ask Data ====================
 
@@ -42,6 +43,8 @@ export interface PendingAskData {
     expiresAt: number;
     /** Current status of the ask */
     status: PendingAskStatus;
+    /** Durable task created for this ask_user request. */
+    taskId?: string;
     /** Timestamp when resolved (ms since epoch) */
     resolvedAt?: number;
     /** User's response (after resolution) */
@@ -104,3 +107,7 @@ export interface AskUserWebhookEvent {
 export interface ListPendingAsksResponse {
     asks: PendingAskData[];
 }
+
+export interface AskUserTaskMetadata {
+    taskFields?: TaskField[];
+}

package/src/principal-context.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolved per-user context consumed by PrincipalSet condition evaluation
+ * (`matchConditions` / `resolveConditions`) and by ABAC client-side tooling.
+ *
+ * Mirrors what the token server builds for `$principal.*` resolution at JWT
+ * issue time, with the same defaults (clearance = 0, compartments = [],
+ * tags = [], properties = {}). Lives in @vertesia/common so both server-side
+ * builders and client-side consumers share the exact same shape.
+ */
+export interface PrincipalContext {
+    clearance: number;
+    compartments: string[];
+    email?: string;
+    tags: string[];
+    properties: Record<string, unknown>;
+}
+
+/**
+ * Response shape of the `/iam/users/identity` endpoint: the current principal's
+ * {@link PrincipalContext} plus its id. Distinct from `PrincipalContext` itself
+ * because the id is identity metadata, not a merged BLP field — adding it to
+ * `PrincipalContext` would unintentionally expose `$principal.id` to
+ * PrincipalSet rule evaluation.
+ */
+export interface PrincipalIdentity extends PrincipalContext {
+    id: string;
+}