@vertesia/studio-utils 1.4.0-dev.20260615.051508Z → 1.4.0

package/src/conditions/match.ts

@@ -0,0 +1,146 @@
+import type { PropertyConditions } from '@vertesia/common';
+import { getStudioUtilsLogger } from '../logger.js';
+
+/**
+ * Resolve a property path against a context object.
+ *
+ * Supports:
+ *   - `clearance` → obj.clearance
+ *   - `email` → obj.email
+ *   - `properties.department` → obj.properties.department (one nested level under `properties`)
+ *
+ * Returns `undefined` if any segment is missing or non-traversable.
+ */
+export function resolvePath(obj: Record<string, unknown>, path: string): unknown {
+    if (path.startsWith('properties.')) {
+        const properties = obj.properties;
+        return properties && typeof properties === 'object'
+            ? (properties as Record<string, unknown>)[path.slice(11)]
+            : undefined;
+    }
+    return obj[path];
+}
+
+/**
+ * Match a wildcard pattern against a string value.
+ *
+ * Supports `*` as wildcard:
+ *   - `"*@domain.com"` — ends with
+ *   - `"bogdan.*"` — starts with
+ *   - `"bogdan+*@vertesia.com"` — contains
+ *   - `"*"` — match all
+ *
+ * Case-insensitive. Non-string `value` always returns `false`.
+ */
+export function matchLike(value: unknown, pattern: string): boolean {
+    if (typeof value !== 'string') return false;
+    // Convert wildcard pattern to regex: escape regex chars except *, then replace * with .*
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`, 'i').test(value);
+}
+
+function compareOrdered(value: unknown, expected: unknown, op: '$gt' | '$gte' | '$lt' | '$lte'): boolean {
+    if (typeof value !== 'number' && typeof value !== 'string') return false;
+    if (typeof value !== typeof expected) return false;
+    const left = value;
+    const right = expected as typeof left;
+    switch (op) {
+        case '$gt':
+            return left > right;
+        case '$gte':
+            return left >= right;
+        case '$lt':
+            return left < right;
+        case '$lte':
+            return left <= right;
+    }
+}
+
+/**
+ * Evaluate a PropertyConditions object against a set of properties (JS-side, in-memory).
+ *
+ * Supports the MongoDB query syntax subset shared across token-server (principal property
+ * matching at JWT-mint time) and zeno-server (write-path ABAC permission checks against an
+ * in-memory document):
+ *
+ *   - Direct value match (`{ field: literal }`)
+ *   - `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
+ *   - `$in`, `$nin` (against array `expected`)
+ *   - `$exists` (boolean)
+ *   - `$empty` (boolean) — true for undefined/null/empty-string/empty-array
+ *   - `$like` (wildcard string, see {@link matchLike})
+ *
+ * All field-level conditions are AND'd (every field must match). Within a single field, all
+ * operators are AND'd.
+ *
+ * Mirrors the Mongo-side filter built by `conditionsToMongoFilter` (zeno-server utils.ts) and
+ * the ES-side filter built by `conditionsToEsQuery`. Use this when conditions need to be
+ * evaluated against a single hydrated document instead of pushed down as a query.
+ *
+ * Unknown operators emit a warning via the studio-utils logger and return false — surfacing
+ * misconfiguration loudly without breaking the surrounding token mint or permission check.
+ *
+ * `$principal.X` substitutions in conditions are expected to have already been resolved at
+ * JWT-mint time by `resolveConditions` in token-server; values reaching this function are
+ * concrete.
+ */
+export function matchConditions(conditions: PropertyConditions, properties: Record<string, unknown>): boolean {
+    for (const [key, condition] of Object.entries(conditions)) {
+        const value = resolvePath(properties, key);
+
+        if (condition === null || condition === undefined || typeof condition !== 'object') {
+            // Direct value match
+            if (value !== condition) return false;
+        } else {
+            // Operator object
+            const ops = condition as Record<string, unknown>;
+            for (const [op, expected] of Object.entries(ops)) {
+                switch (op) {
+                    case '$eq':
+                        if (value !== expected) return false;
+                        break;
+                    case '$ne':
+                        if (value === expected) return false;
+                        break;
+                    case '$gt':
+                        if (!compareOrdered(value, expected, '$gt')) return false;
+                        break;
+                    case '$gte':
+                        if (!compareOrdered(value, expected, '$gte')) return false;
+                        break;
+                    case '$lt':
+                        if (!compareOrdered(value, expected, '$lt')) return false;
+                        break;
+                    case '$lte':
+                        if (!compareOrdered(value, expected, '$lte')) return false;
+                        break;
+                    case '$in':
+                        if (!Array.isArray(expected) || !expected.includes(value)) return false;
+                        break;
+                    case '$nin':
+                        if (Array.isArray(expected) && expected.includes(value)) return false;
+                        break;
+                    case '$exists':
+                        if (typeof expected !== 'boolean' || (value !== undefined) !== expected) return false;
+                        break;
+                    case '$empty': {
+                        const isEmpty =
+                            value === undefined ||
+                            value === null ||
+                            value === '' ||
+                            (Array.isArray(value) && value.length === 0);
+                        if (typeof expected !== 'boolean' || isEmpty !== expected) return false;
+                        break;
+                    }
+                    case '$like':
+                        if (typeof expected !== 'string' || !matchLike(value, expected)) return false;
+                        break;
+                    default:
+                        getStudioUtilsLogger().warn({ op, key }, 'Unknown operator in PropertyConditions');
+                        return false;
+                }
+            }
+        }
+    }
+    return true;
+}

package/src/index.ts

@@ -17,3 +17,4 @@ export {
     type PromptValidationResult,
     validatePrompt,
 } from './prompts/validate.js';
+export * from './roles/index.js';

package/src/logger.ts

@@ -0,0 +1,25 @@
+export interface StudioUtilsLogger {
+    warn(details: Record<string, unknown>, message: string): void;
+}
+
+// studio-utils deliberately excludes DOM/Node lib globals so browser and Node
+// consumers stay symmetric. Declare the minimal console surface for the fallback logger.
+declare const console: { warn(...args: unknown[]): void };
+
+const consoleLogger: StudioUtilsLogger = {
+    warn: (details, message) => {
+        console.warn(message, details);
+    },
+};
+
+let logger: StudioUtilsLogger = consoleLogger;
+
+export function getStudioUtilsLogger(): StudioUtilsLogger {
+    return logger;
+}
+
+export function installStudioUtilsLogger(customLogger: StudioUtilsLogger): StudioUtilsLogger {
+    const previousLogger = logger;
+    logger = customLogger;
+    return previousLogger;
+}

package/src/roles/classes.ts

@@ -0,0 +1,78 @@
+import type { AbacScope, Permission, RoleDomain } from '@vertesia/common';
+
+/**
+ * Class hierarchy and registry-bound interface for the role system. These
+ * are LOGIC — they have runtime behavior (constructors, instance methods,
+ * subclass dispatch via `instanceof`). They live in `@vertesia/studio-utils`
+ * (not common) per the package-layering contract: only types stay in common.
+ */
+
+/**
+ * A role: a named bundle of permissions that ACEs reference by name.
+ *
+ * Generic over the permission type so subclasses can tighten it:
+ *  - **System roles** declare `extends Role<Permission>` — construction time
+ *    type-checks against the central `Permission` enum.
+ *  - **ABAC roles** (`AbacRole`) declare `extends Role<string>` — permissions
+ *    are bare verbs (`'read'`, `'write'`, `'delete'`, future domain-specific
+ *    verbs) consumed by the JWT generator to form `{scope}:{verb}` keys in
+ *    `content_security`.
+ *
+ * The registry stores `Role` (defaulting to `Role<string>`) — the loose type
+ * is the lowest common denominator. Tight typing is only enforced at
+ * declaration sites of the role subclasses.
+ */
+export class Role<PermissionType extends string = string> {
+    permissions: Set<PermissionType>;
+    constructor(
+        public name: string,
+        permissions: PermissionType[],
+        public domain: RoleDomain,
+    ) {
+        this.permissions = new Set(permissions);
+    }
+
+    hasPermission(permission: PermissionType) {
+        return this.permissions.has(permission);
+    }
+}
+
+/**
+ * Base class for built-in system roles. Hardcodes `domain: 'system'` and
+ * specializes `Role<Permission>` so subclasses get compile-time type-checking
+ * against the central `Permission` enum at construction.
+ */
+export class SystemRole extends Role<Permission> {
+    constructor(name: string, permissions: Permission[]) {
+        super(name, permissions, 'system');
+    }
+}
+
+/**
+ * A role usable in ContentSet ACEs. Adds `applicableScopes` — the kinds of
+ * objects the role can be applied to at the ABAC scope level. Inherits
+ * `Role<string>` because ABAC verbs aren't constrained to the central
+ * `Permission` enum.
+ *
+ * The IAM UI filters via `listAbacRolesForScope` which checks `instanceof AbacRole`.
+ */
+export class AbacRole extends Role<string> {
+    constructor(
+        name: string,
+        permissions: string[],
+        domain: RoleDomain,
+        public applicableScopes: readonly AbacScope[],
+    ) {
+        super(name, permissions, domain);
+    }
+}
+
+/**
+ * A logical bucket of roles owned by a single domain. The registry iterates
+ * partitions in registration order — first match wins. The `system` partition
+ * is registered first so domain partitions cannot shadow built-in system roles.
+ */
+export interface RolePartition {
+    domain: RoleDomain;
+    roles: Map<string, Role>;
+}

package/src/roles/content.ts

@@ -0,0 +1,46 @@
+import type { AbacScope, RoleDomain } from '@vertesia/common';
+import { AbacRole, type Role, type RolePartition } from './classes.js';
+
+const ContentRoleDomain: RoleDomain = 'content';
+
+const APPLICABLE_SCOPES: readonly AbacScope[] = ['document', 'collection'];
+
+/**
+ * Names of roles owned by the `content` domain. Apply to ContentSet ACEs
+ * scoped to either `document` or `collection` — the semantics of "read
+ * content" are the same for both kinds.
+ */
+export enum ContentRoleNames {
+    content_reader = 'content_reader',
+    content_writer = 'content_writer',
+    content_manager = 'content_manager',
+}
+
+class ContentReaderRole extends AbacRole {
+    constructor() {
+        super(ContentRoleNames.content_reader, ['read'], ContentRoleDomain, APPLICABLE_SCOPES);
+    }
+}
+
+class ContentWriterRole extends AbacRole {
+    constructor() {
+        super(ContentRoleNames.content_writer, ['read', 'write'], ContentRoleDomain, APPLICABLE_SCOPES);
+    }
+}
+
+class ContentManagerRole extends AbacRole {
+    constructor() {
+        super(ContentRoleNames.content_manager, ['read', 'write', 'delete'], ContentRoleDomain, APPLICABLE_SCOPES);
+    }
+}
+
+const contentRoles: Record<ContentRoleNames, Role> = {
+    [ContentRoleNames.content_reader]: new ContentReaderRole(),
+    [ContentRoleNames.content_writer]: new ContentWriterRole(),
+    [ContentRoleNames.content_manager]: new ContentManagerRole(),
+};
+
+export const contentPartition: RolePartition = {
+    domain: ContentRoleDomain,
+    roles: new Map(Object.entries(contentRoles)),
+};

package/src/roles/index.test.ts

@@ -0,0 +1,206 @@
+import { Permission, SystemRoles } from '@vertesia/common';
+import { describe, expect, it } from 'vitest';
+import { ContentRoleNames } from './content.js';
+import {
+    AbacRole,
+    getAllRoleNames,
+    getPermissionsForRoles,
+    getRoleByName,
+    listAbacRolesForScope,
+    listRoles,
+    listRolesByDomain,
+    listSystemRoles,
+    Role,
+    RoleList,
+    SystemRole,
+} from './index.js';
+
+describe('getRoleByName', () => {
+    it('returns a system role by name', () => {
+        const role = getRoleByName(SystemRoles.owner);
+        expect(role).toBeInstanceOf(SystemRole);
+        expect(role.name).toBe('owner');
+        expect(role.domain).toBe('system');
+    });
+
+    it('returns an ABAC role by name', () => {
+        const role = getRoleByName(ContentRoleNames.content_reader);
+        expect(role).toBeInstanceOf(AbacRole);
+        expect(role.name).toBe('content_reader');
+        expect(role.domain).toBe('content');
+    });
+
+    it('throws on unknown role', () => {
+        expect(() => getRoleByName('not_a_real_role')).toThrow(/Role not_a_real_role not found/);
+    });
+
+    it('queries partitions in registration order — system first', () => {
+        // System partition is registered before content. Even if a future partition
+        // declared a role named 'owner', the system one would still win.
+        const role = getRoleByName(SystemRoles.owner);
+        expect(role.domain).toBe('system');
+    });
+});
+
+describe('listRoles', () => {
+    it('returns every role across all partitions', () => {
+        const roles = listRoles();
+        // 16 system roles + 3 content roles
+        expect(roles).toHaveLength(19);
+    });
+
+    it('lists system roles before content roles (partition registration order)', () => {
+        const roles = listRoles();
+        const systemCount = roles.filter((r) => r.domain === 'system').length;
+        const contentCount = roles.filter((r) => r.domain === 'content').length;
+        expect(systemCount).toBe(16);
+        expect(contentCount).toBe(3);
+
+        // First 16 are system, next 3 are content
+        for (let i = 0; i < 16; i++) expect(roles[i].domain).toBe('system');
+        for (let i = 16; i < 19; i++) expect(roles[i].domain).toBe('content');
+    });
+});
+
+describe('listRolesByDomain', () => {
+    it('returns only system roles for "system"', () => {
+        const roles = listRolesByDomain('system');
+        expect(roles).toHaveLength(16);
+        expect(roles.every((r) => r.domain === 'system')).toBe(true);
+    });
+
+    it('returns only content roles for "content"', () => {
+        const roles = listRolesByDomain('content');
+        expect(roles).toHaveLength(3);
+        expect(roles.every((r) => r.domain === 'content')).toBe(true);
+    });
+
+    it('returns empty for an unregistered domain', () => {
+        expect(listRolesByDomain('tasks')).toEqual([]);
+    });
+});
+
+describe('listSystemRoles', () => {
+    it('returns SystemRole instances', () => {
+        const roles = listSystemRoles();
+        expect(roles).toHaveLength(16);
+        expect(roles.every((r) => r instanceof SystemRole)).toBe(true);
+    });
+
+    it('excludes ABAC roles', () => {
+        const roles = listSystemRoles();
+        expect(roles.some((r) => r instanceof AbacRole)).toBe(false);
+    });
+});
+
+describe('listAbacRolesForScope', () => {
+    it('returns content roles for "document" scope', () => {
+        const roles = listAbacRolesForScope('document');
+        expect(roles).toHaveLength(3);
+        expect(roles.map((r) => r.name).sort()).toEqual(['content_manager', 'content_reader', 'content_writer']);
+    });
+
+    it('returns content roles for "collection" scope (same roles, applicableScopes covers both)', () => {
+        const roles = listAbacRolesForScope('collection');
+        expect(roles).toHaveLength(3);
+        expect(roles.every((r) => r.applicableScopes.includes('collection'))).toBe(true);
+    });
+
+    it('returns empty for "task" scope (no task partition registered)', () => {
+        expect(listAbacRolesForScope('task')).toEqual([]);
+    });
+
+    it('returns AbacRole instances only — no system roles bleed through', () => {
+        const roles = listAbacRolesForScope('document');
+        expect(roles.every((r) => r instanceof AbacRole)).toBe(true);
+    });
+});
+
+describe('getAllRoleNames', () => {
+    it('returns names of every registered role', () => {
+        const names = getAllRoleNames();
+        expect(names).toHaveLength(19);
+        expect(names).toContain('owner');
+        expect(names).toContain('content_reader');
+    });
+
+    it('produces a flat list suited for mongoose enum constraints', () => {
+        const names = getAllRoleNames();
+        expect(names.every((n) => typeof n === 'string')).toBe(true);
+    });
+});
+
+describe('getPermissionsForRoles', () => {
+    it('merges permissions across multiple roles, deduped', () => {
+        // content_reader: ['read']
+        // content_writer: ['read', 'write']
+        const merged = getPermissionsForRoles([ContentRoleNames.content_reader, ContentRoleNames.content_writer]);
+        expect(merged.sort()).toEqual(['read', 'write']);
+    });
+
+    it('returns system Permission values for system roles', () => {
+        const merged = getPermissionsForRoles([SystemRoles.reader]);
+        // reader role has: int_read, run_read, content_read + account_member (via OrgMemberRole)
+        expect(merged).toContain(Permission.int_read);
+        expect(merged).toContain(Permission.content_read);
+        expect(merged).toContain(Permission.account_member);
+    });
+});
+
+describe('Role instances', () => {
+    it('SystemRole hasPermission for granted Permission', () => {
+        const owner = getRoleByName(SystemRoles.owner);
+        expect(owner.hasPermission(Permission.content_read)).toBe(true);
+        expect(owner.hasPermission(Permission.manage_billing)).toBe(true);
+    });
+
+    it('SystemRole hasPermission false for arbitrary string', () => {
+        const reader = getRoleByName(SystemRoles.reader);
+        expect(reader.hasPermission('not_a_real_perm')).toBe(false);
+    });
+
+    it('AbacRole carries applicableScopes', () => {
+        const reader = getRoleByName(ContentRoleNames.content_reader) as AbacRole;
+        expect(reader.applicableScopes).toEqual(['document', 'collection']);
+    });
+
+    it('AbacRole permissions are bare verbs, not Permission enum values', () => {
+        const manager = getRoleByName(ContentRoleNames.content_manager);
+        expect(Array.from(manager.permissions).sort()).toEqual(['delete', 'read', 'write']);
+    });
+});
+
+describe('SystemRole vs AbacRole discrimination', () => {
+    it('SystemRole instanceof Role', () => {
+        const owner = getRoleByName(SystemRoles.owner);
+        expect(owner).toBeInstanceOf(Role);
+        expect(owner).toBeInstanceOf(SystemRole);
+        expect(owner).not.toBeInstanceOf(AbacRole);
+    });
+
+    it('AbacRole instanceof Role', () => {
+        const reader = getRoleByName(ContentRoleNames.content_reader);
+        expect(reader).toBeInstanceOf(Role);
+        expect(reader).toBeInstanceOf(AbacRole);
+        expect(reader).not.toBeInstanceOf(SystemRole);
+    });
+});
+
+describe('RoleList', () => {
+    it('fromRoleNames composes a list checkable for permissions', () => {
+        const list = RoleList.fromRoleNames([SystemRoles.reader, SystemRoles.executor]);
+        expect(list.hasPermission(Permission.content_read)).toBe(true); // from reader
+        expect(list.hasPermission(Permission.int_execute)).toBe(true); // from executor
+        expect(list.hasPermission(Permission.manage_billing)).toBe(false); // neither has it
+    });
+
+    it('fromRoleName composes a single-role list', () => {
+        const list = RoleList.fromRoleName(SystemRoles.billing);
+        expect(list.hasPermission(Permission.manage_billing)).toBe(true);
+        expect(list.hasPermission(Permission.content_write)).toBe(false);
+    });
+
+    it('throws on unknown role name', () => {
+        expect(() => RoleList.fromRoleNames(['not_real'])).toThrow(/Role not_real not found/);
+    });
+});

package/src/roles/index.ts

@@ -0,0 +1,96 @@
+import type { AbacScope, RoleDomain } from '@vertesia/common';
+import { AbacRole, type Role, type RolePartition, SystemRole } from './classes.js';
+import { contentPartition } from './content.js';
+import { systemPartition } from './system.js';
+
+export { AbacRole, Role, type RolePartition, SystemRole } from './classes.js';
+export { ContentRoleNames } from './content.js';
+
+/**
+ * The ordered partition registry. Partitions are queried in this order — first
+ * match wins. The `system` partition is registered first so domain-specific
+ * partitions (added later) cannot shadow built-in system roles.
+ */
+const partitions: RolePartition[] = [systemPartition, contentPartition];
+
+/** Look up a role by its name across all registered partitions. */
+export function getRoleByName(name: string): Role {
+    for (const partition of partitions) {
+        const role = partition.roles.get(name);
+        if (role) return role;
+    }
+    throw new Error(`Role ${name} not found`);
+}
+
+/** List every role across all partitions, in partition registration order. */
+export function listRoles(): Role[] {
+    const result: Role[] = [];
+    for (const partition of partitions) {
+        for (const role of partition.roles.values()) {
+            result.push(role);
+        }
+    }
+    return result;
+}
+
+/** Roles owned by a specific domain (e.g. `'system'`, `'content'`). */
+export function listRolesByDomain(domain: RoleDomain): Role[] {
+    const partition = partitions.find((p) => p.domain === domain);
+    return partition ? Array.from(partition.roles.values()) : [];
+}
+
+/**
+ * ABAC roles applicable to a given ContentSet scope (e.g. `'document'`,
+ * `'collection'`). System roles are excluded — they don't carry scope semantics.
+ */
+export function listAbacRolesForScope(scope: AbacScope): AbacRole[] {
+    return listRoles().filter((r): r is AbacRole => r instanceof AbacRole && r.applicableScopes.includes(scope));
+}
+
+/** Shortcut for the system partition: returns only `SystemRole` instances. */
+export function listSystemRoles(): SystemRole[] {
+    return listRoles().filter((r): r is SystemRole => r instanceof SystemRole);
+}
+
+/** Names of every registered role across all partitions — suited for mongoose schema enum constraints. */
+export function getAllRoleNames(): string[] {
+    return listRoles().map((r) => r.name);
+}
+
+/**
+ * Merge the permissions granted by a set of roles into a single array.
+ * Intended for the system-role gating path. For ABAC roles, the bare-verb
+ * permissions returned here aren't directly meaningful — use the JWT
+ * `content_security` pathway instead.
+ */
+export function getPermissionsForRoles(roleNames: Iterable<string>): string[] {
+    const permissions = new Set<string>();
+    for (const roleName of roleNames) {
+        const role = getRoleByName(roleName);
+        for (const permission of role.permissions) {
+            permissions.add(permission);
+        }
+    }
+    return Array.from(permissions);
+}
+
+/**
+ * A list of roles with a unified `hasPermission` check across them.
+ */
+export class RoleList {
+    private constructor(public readonly roles: Role[]) {}
+
+    static fromRoleNames(roleNames: string[]): RoleList {
+        const roles = roleNames.map((r) => getRoleByName(r));
+        return new RoleList(roles);
+    }
+
+    static fromRoleName(roleName: string): RoleList {
+        const roles = [getRoleByName(roleName)];
+        return new RoleList(roles);
+    }
+
+    hasPermission(perm: string): boolean {
+        return this.roles.some((role) => role.hasPermission(perm));
+    }
+}