@vertesia/common 1.6.0-dev.20260918.115658Z → 1.6.0-dev.20260923.085325Z

package/src/api-schemas/sts.ts

@@ -124,3 +124,19 @@ export const IssueTokenForbiddenResponseSchema = z
 export const IssueTokenUnavailableResponseSchema = z
     .strictObject({ error: z.string(), message: z.string() })
     .meta({ id: 'IssueTokenUnavailableResponse' });
+
+export const AppSessionTokenRequestSchema = z
+    .strictObject({
+        app_name: z.string().min(1),
+        scopes: z.array(z.string()).optional(),
+        ttl_seconds: z.number().int().min(1).max(900).optional(),
+    })
+    .meta({ id: 'AppSessionTokenRequest' });
+
+export const AppSessionTokenResponseSchema = z
+    .strictObject({
+        token: z.string(),
+        token_type: z.literal('Bearer'),
+        expires_in: z.number().int(),
+    })
+    .meta({ id: 'AppSessionTokenResponse' });

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

@@ -1,10 +1,10 @@
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import { describe, expect, it } from 'vitest';
-import type { PrincipalContext, PrincipalIdentity } from '../principal-context.js';
+import type { AbacPrincipalContext, PrincipalIdentity } from '../principal-context.js';
 import type { UpdateUserPayload, User } from '../user.js';
 import type { JsonObject } from './adapter.js';
 import { ApiSchemaComponents, apiComponentRef, validateApiRequest, validateApiResponse } from './registry.js';
-import type { PrincipalContextFromSchema, UserArrayFromSchema } from './user.js';
+import type { AbacPrincipalContextFromSchema, UserArrayFromSchema } from './user.js';
 
 /** Exact type identity — `extends` in both directions is too weak (any/unknown slip through). */
 type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
@@ -27,19 +27,23 @@ const VALID_USER = {
 describe('gate 1 — the schema is the single source of truth for the public IAM types', () => {
     it('publishes the exact schema-derived type, not a hand-written twin', () => {
         assertType<Equals<UserArrayFromSchema, User[]>>(true);
-        assertType<Equals<PrincipalContext, PrincipalContextFromSchema>>(true);
+        assertType<Equals<AbacPrincipalContext, AbacPrincipalContextFromSchema>>(true);
         expect(true).toBe(true);
     });
 
-    it('derives the inherited principal fields rather than restating them', () => {
-        // PrincipalIdentity used to `extends PrincipalContext`, so composing the schemas is what
-        // keeps the five inherited fields from becoming a twin one level down — the failure mode
-        // this batch was scoped to avoid.
-        assertType<Equals<PrincipalIdentity['clearance'], PrincipalContext['clearance']>>(true);
-        assertType<Equals<PrincipalIdentity['compartments'], PrincipalContext['compartments']>>(true);
-        assertType<Equals<PrincipalIdentity['email'], PrincipalContext['email']>>(true);
-        assertType<Equals<PrincipalIdentity['tags'], PrincipalContext['tags']>>(true);
-        assertType<Equals<PrincipalIdentity['properties'], PrincipalContext['properties']>>(true);
+    it('derives the identity fields from the ABAC context rather than restating them', () => {
+        // PrincipalIdentity `extends AbacPrincipalContext`, so composing the schemas is what keeps
+        // the inherited fields from becoming a twin one level down — the failure mode this batch was
+        // scoped to avoid. `kind` and `id` are part of the ABAC context itself (resolvable as
+        // `$principal.*`), not identity-only metadata.
+        assertType<Equals<PrincipalIdentity['kind'], AbacPrincipalContext['kind']>>(true);
+        assertType<Equals<PrincipalIdentity['id'], AbacPrincipalContext['id']>>(true);
+        assertType<Equals<PrincipalIdentity['clearance'], AbacPrincipalContext['clearance']>>(true);
+        assertType<Equals<PrincipalIdentity['compartments'], AbacPrincipalContext['compartments']>>(true);
+        assertType<Equals<PrincipalIdentity['email'], AbacPrincipalContext['email']>>(true);
+        assertType<Equals<PrincipalIdentity['tags'], AbacPrincipalContext['tags']>>(true);
+        assertType<Equals<PrincipalIdentity['properties'], AbacPrincipalContext['properties']>>(true);
+        assertType<Equals<PrincipalIdentity['kind'], 'user' | 'apikey'>>(true);
         assertType<Equals<PrincipalIdentity['id'], string>>(true);
         expect(true).toBe(true);
     });
@@ -80,20 +84,22 @@ describe('gate 1 — the schema is the single source of truth for the public IAM
 });
 
 describe('gate 2 — the published components match the closure the types come from', () => {
-    it('does not hoist PrincipalContext into a component of its own', () => {
+    it('does not hoist AbacPrincipalContext into a component of its own', () => {
         // It is a public TYPE but has never been a published component. Hoisting it would add a
         // $ref to PrincipalIdentity that every generated client would have to follow.
-        expect(Object.keys(ApiSchemaComponents)).not.toContain('PrincipalContext');
+        expect(Object.keys(ApiSchemaComponents)).not.toContain('AbacPrincipalContext');
         const props = ApiSchemaComponents.PrincipalIdentity.properties as Record<string, JsonObject>;
+        expect(props.kind).toEqual({ type: 'string', enum: ['user', 'apikey'] });
         expect(props.clearance).toEqual({ type: 'number' });
         expect(props.id).toEqual({ type: 'string' });
     });
 
-    it('publishes the composed property order, id last', () => {
-        // `.extend()` appends, which is what `interface … extends …` produced and what the document
-        // already carries.
+    it('publishes the composed property order — kind and id first', () => {
+        // `AbacPrincipalContext` lists its discriminators (kind, id) ahead of the merged BLP
+        // attributes; PrincipalIdentity `.extend({})`s it, adding nothing, so the order is the
+        // context's own.
         const props = ApiSchemaComponents.PrincipalIdentity.properties as JsonObject;
-        expect(Object.keys(props)).toEqual(['clearance', 'compartments', 'email', 'tags', 'properties', 'id']);
+        expect(Object.keys(props)).toEqual(['kind', 'id', 'clearance', 'compartments', 'email', 'tags', 'properties']);
     });
 
     it('declares the timestamps the endpoint has always shipped', () => {

package/src/api-schemas/user.ts

@@ -9,15 +9,22 @@ import { z } from 'zod';
  */
 
 /**
- * Not hoisted: no `id` in `.meta()`, so the adapter inlines it into `PrincipalIdentity` instead of
- * emitting a `PrincipalContext` component and a `$ref` the document has never published.
+ * The full principal context resolved at token-issue time — every field a rule can reference through
+ * `$principal.*`: the principal `kind`, its `id`, and the merged BLP attributes. This is the single
+ * source of truth the token server mirrors into the JWT, the shared `buildPrincipalContext`
+ * produces, and the UI condition editor offers. `kind` and `id` are first-class members here, not
+ * identity-only metadata: they are resolvable in ResourceSet/PrincipalSet conditions, so hiding them
+ * (as an earlier split of this schema did) under-declared what the server actually matches against.
  *
- * It still exists as a schema rather than being spelled out inside `PrincipalIdentitySchema`,
- * because `PrincipalContext` is a public type in its own right — consumed by PrincipalSet condition
- * evaluation and client-side ABAC tooling. Composing the two is what keeps the five inherited fields
- * from becoming a hand-written twin of the schema that publishes them.
+ * Not hoisted: no `id` in `.meta()`, so the adapter inlines it into `PrincipalIdentity` instead of
+ * emitting an `AbacPrincipalContext` component and a `$ref` the document has never published. It
+ * still exists as a schema in its own right because it is a public type composed into
+ * `PrincipalIdentitySchema` — composing is what keeps the shared fields from becoming a hand-written
+ * twin of the schema that publishes them.
  */
-export const PrincipalContextSchema = z.object({
+export const AbacPrincipalContextSchema = z.object({
+    kind: z.enum(['user', 'apikey']),
+    id: z.string(),
     clearance: z.number(),
     compartments: z.array(z.string()),
     email: z.string().optional(),
@@ -26,19 +33,18 @@ export const PrincipalContextSchema = z.object({
 });
 
 /**
- * `.extend()` rather than a fresh object literal: it appends `id` after the inherited five, which is
- * both what `interface PrincipalIdentity extends PrincipalContext` produced and the property order
- * the document already publishes.
+ * Response shape of the `/iam/users/identity` endpoint. Extends {@link AbacPrincipalContextSchema}
+ * adding nothing today: the two are kept as distinct names so identity-only fields — ones that must
+ * NOT become resolvable as `$principal.*` — can be added here later without widening the ABAC
+ * surface. Invariant: the ABAC principal context is always a subset of the identity. At this
+ * endpoint `kind` is always `user`.
  */
-export const PrincipalIdentitySchema = PrincipalContextSchema.extend({
-    id: z.string(),
-}).meta({
+export const PrincipalIdentitySchema = AbacPrincipalContextSchema.extend({}).meta({
     id: 'PrincipalIdentity',
     description:
-        "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.',
+        "Response shape of the `/iam/users/identity` endpoint: the current principal's full ABAC " +
+        'context — its `kind` (always `user` here), `id`, and the merged BLP attributes a rule can ' +
+        'reference through `$principal.*`.',
 });
 
 /**
@@ -194,7 +200,7 @@ export const SignupPayloadSchema = z
  * The public IAM types, inferred rather than written. `../principal-context.ts`, `../user.ts` and
  * `../common.ts` re-export these under their public names.
  */
-export type PrincipalContextFromSchema = z.infer<typeof PrincipalContextSchema>;
+export type AbacPrincipalContextFromSchema = z.infer<typeof AbacPrincipalContextSchema>;
 export type PrincipalIdentityFromSchema = z.infer<typeof PrincipalIdentitySchema>;
 export type UserFromSchema = z.infer<typeof UserSchema>;
 export type UserArrayFromSchema = z.infer<typeof UserArraySchema>;

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

@@ -70,19 +70,12 @@ describe('ViewExperienceConfiguration', () => {
         ).toBe(false);
     });
 
-    it('accepts View model options that name no driver, while the shared config still requires one', () => {
-        // The regression: a View's `model_options` are authored in the editor and saved before any
-        // driver is resolved, so they carry no `_option_id`. Validating them against the
-        // `ModelOptions` driver union — every branch of which requires that discriminator — meant a
-        // stored View could not satisfy its own response schema, and `GET /views` logged a contract
-        // violation on every call.
+    it('accepts untagged View options and preserves the shared options schema reference', () => {
+        // View options and shared model options both permit an omitted family ID.
         const authored = { model_options: { temperature: 0.2, max_tokens: 1024 } };
         expect(validateApiResponse('ViewAgenticExecutionConfiguration', authored).valid).toBe(true);
 
-        // The split is the point: agent runs, events and workflow runs record options a driver
-        // already resolved, so the shared component keeps the union. Asserted on the published
-        // schema because `InteractionExecutionConfiguration` is not itself a response slot — if it
-        // ever stops pointing at `ModelOptions`, the relaxation leaked out of Views.
+        // Keep the shared component wired to the canonical options contract.
         const modelOptions = (name: string) =>
             (ApiSchemaComponents[name] as { properties: Record<string, unknown> }).properties.model_options;
         expect(modelOptions('InteractionExecutionConfiguration')).toEqual({

package/src/apps.ts

@@ -51,6 +51,7 @@ import type {
     StartAppDevelopmentTaskRequestSchema,
     StartAppScaffoldRequestSchema,
     StartAppScaffoldResponseSchema,
+    UpdateAppInstallationOAuthApprovalPayloadSchema,
     UpdateAppInstallationToolAllowlistPayloadSchema,
     UpsertAppVersionRequestSchema,
     ValidateUrlRequestSchema,
@@ -752,3 +753,5 @@ export type ValidateUrlResponse = z.infer<typeof ValidateUrlResponseSchema>;
  * already deleted. Deriving the type is what keeps the two from drifting again.
  */
 export type AppDeleteSummary = z.infer<typeof AppDeleteSummarySchema>;
+
+export type UpdateAppInstallationOAuthApprovalPayload = z.infer<typeof UpdateAppInstallationOAuthApprovalPayloadSchema>;

package/src/index.ts

@@ -1,4 +1,11 @@
-export type { VertexAIGeminiOmniVideoOptions, VideoResult } from '@llumiverse/common';
+export type {
+    AudioResult,
+    OpenAiAudioOptions,
+    OpenAiSpeechOptions,
+    OpenAiTranscriptionOptions,
+    VertexAIGeminiOmniVideoOptions,
+    VideoResult,
+} from '@llumiverse/common';
 export * from './access-control.js';
 export * from './analytics.js';
 /**
@@ -8,7 +15,7 @@ export * from './analytics.js';
  */
 export type { UserGroupArrayFromSchema } from './api-schemas/group.js';
 export type {
-    PrincipalContextFromSchema,
+    AbacPrincipalContextFromSchema,
     UserArrayFromSchema,
     UserRefArrayFromSchema,
 } from './api-schemas/user.js';

package/src/oauth-server.ts

@@ -6,6 +6,7 @@ import type {
     CreateOAuthClientPayloadSchema,
     ListOAuthGrantsQuerySchema,
     OAuthAuthorizationDecisionResponseSchema,
+    OAuthAuthorizationRequestGeneratedAppSchema,
     OAuthAuthorizationRequestSchema,
     OAuthAuthorizationRequestStatusSchema,
     OAuthAuthorizationServerMetadataSchema,
@@ -28,6 +29,9 @@ import type {
     OAuthGrantSortOrderSchema,
     OAuthGrantStatusSchema,
     OAuthGrantTypeSchema,
+    OAuthLoginDecisionResponseSchema,
+    OAuthLoginPayloadSchema,
+    OAuthLoginUserNotFoundResponseSchema,
     OAuthProjectBindingModeSchema,
     OAuthRegistrationSourceSchema,
     OAuthResponseTypeSchema,
@@ -92,3 +96,10 @@ export type OAuthAuthorizationDecisionResponse = z.infer<typeof OAuthAuthorizati
 export type OAuthDeviceAuthorizationRequest = z.infer<typeof OAuthDeviceAuthorizationRequestSchema>;
 export type OAuthDeviceAuthorizationResponse = z.infer<typeof OAuthDeviceAuthorizationResponseSchema>;
 export type OAuthTokenResponse = z.infer<typeof OAuthTokenResponseSchema>;
+
+export type OAuthAuthorizationRequestGeneratedApp = z.infer<typeof OAuthAuthorizationRequestGeneratedAppSchema>;
+
+export type OAuthLoginPayload = z.infer<typeof OAuthLoginPayloadSchema>;
+export type OAuthLoginDecisionResponse = z.infer<typeof OAuthLoginDecisionResponseSchema>;
+
+export type OAuthLoginUserNotFoundResponse = z.infer<typeof OAuthLoginUserNotFoundResponseSchema>;

package/src/principal-context.ts

@@ -1,23 +1,33 @@
 import type { z } from 'zod';
-import type { PrincipalContextFromSchema, PrincipalIdentitySchema } from './api-schemas/user.js';
+import type { AbacPrincipalContextFromSchema, PrincipalIdentitySchema } from './api-schemas/user.js';
 
 /**
- * Resolved per-user context consumed by PrincipalSet condition evaluation
- * (`matchConditions` / `resolveConditions`) and by ABAC client-side tooling.
+ * The resolved principal context matched by ResourceSet/PrincipalSet condition evaluation
+ * (`resolveConditions` / `matchConditions`) and offered by the UI condition editor. Every field is
+ * referenceable in a rule as `$principal.<field>`: the principal `kind`, its `id`, and the merged
+ * BLP attributes (clearance, compartments, email, tags, properties).
  *
- * 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.
+ * This is the single shape the token server writes into the JWT for `$principal.*` resolution at
+ * issue time, and the shared `buildPrincipalContext` in @vertesia/studio-utils produces — with the
+ * defaults that keep condition operators well-defined for absent values (clearance = 0,
+ * compartments = [], tags = [], properties = {}, id = '', email = '').
  *
- * Derived from `PrincipalContextSchema`, which is composed into `PrincipalIdentitySchema` rather
- * than published as a component of its own — the document has never carried a `PrincipalContext`
+ * Derived from `AbacPrincipalContextSchema`, which is composed into `PrincipalIdentitySchema` rather
+ * than published as a component of its own — the document has never carried an `AbacPrincipalContext`
  * schema, and inventing one would add a `$ref` to every generated client.
  */
-export type PrincipalContext = PrincipalContextFromSchema;
+export type AbacPrincipalContext = AbacPrincipalContextFromSchema;
 
 /**
- * Response shape of the `/iam/users/identity` endpoint. Derived from `PrincipalIdentitySchema`,
- * where its published description lives — Zod reads `.meta()`, not TSDoc.
+ * The principal subject kind. A resolvable field of {@link AbacPrincipalContext}, so rules may match
+ * on `$principal.kind`.
+ */
+export type PrincipalKind = AbacPrincipalContext['kind'];
+
+/**
+ * Response shape of the `/iam/users/identity` endpoint. Extends {@link AbacPrincipalContext} with
+ * identity-only fields (none today) — the invariant is that the ABAC context is always a subset of
+ * the identity, so a field added here never widens the `$principal.*` surface. Derived from
+ * `PrincipalIdentitySchema`, where its published description lives — Zod reads `.meta()`, not TSDoc.
  */
 export type PrincipalIdentity = z.infer<typeof PrincipalIdentitySchema>;

package/src/project.ts

@@ -118,6 +118,16 @@ export const SYSTEM_INTERACTION_CATEGORIES: Record<string, SystemInteractionCate
     ContentSearchAgent: SystemInteractionCategory.analysis,
     ContentSearchReranker: SystemInteractionCategory.analysis,
     StudioAssistant: SystemInteractionCategory.agent,
+    // App development runs as an orchestrator plus five specialist sub-agents. Categorising them
+    // lets `defaults.system.agent` apply: an in-code sub-agent is launched without an environment
+    // or model of its own, so without a category it resolves to the project BASE default rather
+    // than the agent default, and a task started on a chosen model ran its sub-agents on another.
+    AppDevelopmentOrchestrator: SystemInteractionCategory.agent,
+    AppSolutionArchitect: SystemInteractionCategory.agent,
+    AppDesigner: SystemInteractionCategory.agent,
+    AppDeveloper: SystemInteractionCategory.agent,
+    AppReviewer: SystemInteractionCategory.agent,
+    AppTester: SystemInteractionCategory.agent,
 };
 
 /**