@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/permissions.js

@@ -0,0 +1,272 @@
+import { GENERATED_UPSERT_PREFIX, toSnakeCase } from "./names.js";
+/**
+ * Permissions are `<entity>:<verb>` strings. The verbs are `read`, the generated `create`, `update`,
+ * `delete`, `link` and `unlink`, and the snake_case name of an authored action. A role may use `*` for
+ * the entity (`*:read`), the verb (`lead:*`) or both (`*:*`); what an action or a read requires never
+ * holds a wildcard. A wildcard entity does not cover the entities in {@link EXPLICIT_GRANT_ENTITIES},
+ * and covers only some verbs of those in {@link WILDCARD_ENTITY_VERBS}.
+ */
+/** Any entity or any verb, in a role's permissions. */
+export const WILDCARD = "*";
+/** The verb of every read: lists, queries, records, history, traversals and `include`. */
+export const READ_VERB = "read";
+/**
+ * Entities only a permission that names them covers: `*:read` or `*:*` grant nothing on them. The
+ * built-in agent chat is in every ontology, and member's default `*:read` would otherwise show anyone
+ * who signs in the workspace's chats and who is in them; `agent_chat:read` or `agent_chat:*` does.
+ * App feedback is a member's own message to the builders: a member reads theirs through a scoped
+ * `app_feedback:read`, and only the builders' roles name it unscoped. The built-in sign-in
+ * identities hold every member's external accounts, such as their Telegram id and username: only a
+ * role that names `user_identity` reads them.
+ */
+export const EXPLICIT_GRANT_ENTITIES = new Set([
+    "agent_chat",
+    "app_feedback",
+    "app_feedback_file",
+    "user_identity",
+]);
+/** The built-in user's entity name in permissions. */
+const USER_ENTITY = "user";
+/**
+ * The verbs of the built-in user's member management: inviting a member, granting and revoking
+ * roles, and deactivating and reactivating a member. Like every other verb on `user` but `read` and
+ * `update`, only `user:<verb>` or `user:*` grants them.
+ */
+export const USER_MEMBER_VERBS = [
+    "invite",
+    "grant_roles",
+    "revoke_roles",
+    "deactivate",
+    "reactivate",
+];
+/**
+ * Entities of which a wildcard entity (`*:*`, `*:<verb>`) covers only the listed verbs; any other
+ * verb needs a permission that names the entity. A role written for business data must not
+ * administer members by accident, and an API key holding `*:*` must not grant itself roles, so
+ * `*:*` reaches `user:read` and `user:update` but none of {@link USER_MEMBER_VERBS} or an authored
+ * action on `user`.
+ */
+export const WILDCARD_ENTITY_VERBS = new Map([
+    [USER_ENTITY, new Set([READ_VERB, "update"])],
+]);
+/** Whether a wildcard entity covers this verb of this entity, both in snake_case. */
+export function wildcardEntityCovers(entity, verb) {
+    if (EXPLICIT_GRANT_ENTITIES.has(entity)) {
+        return false;
+    }
+    const verbs = WILDCARD_ENTITY_VERBS.get(entity);
+    return verbs === undefined || verbs.has(verb);
+}
+/** What the built-in `member` role holds when `defineOntology` does not say: reading everything. */
+export const DEFAULT_MEMBER_PERMISSIONS = [`${WILDCARD}:${READ_VERB}`];
+/** `<entity>:<verb>` with lowercase snake_case entities and lowercase snake_case verbs, or `*` for either. */
+const PERMISSION = /^(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*)$/;
+/** The entity and verb of a permission, or `undefined` when the value is not one. */
+export function parsePermission(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const match = PERMISSION.exec(value);
+    return match === null ? undefined : { entity: match[1], verb: match[2] };
+}
+/** The scope of workflow permissions: `workflow:<workflow>:<verb>`. */
+export const WORKFLOW_PERMISSION_SCOPE = "workflow";
+/** The verbs of a workflow: starting a run and reading its runs. */
+export const WORKFLOW_VERBS = ["start", "read"];
+const WORKFLOW_PERMISSION = /^workflow:(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*):(\*|start|read)$/;
+/**
+ * The workflow and verb of `workflow:<workflow>:<verb>`, or `undefined` when the value is not one.
+ * Workflow permissions are a scope of their own: only a permission that starts with `workflow:`
+ * grants them, so `*:*` and `*:read` cover none.
+ */
+export function parseWorkflowPermission(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const match = WORKFLOW_PERMISSION.exec(value);
+    return match === null ? undefined : { workflow: match[1], verb: match[2] };
+}
+/** `workflow:remind_stale_leads:start`. */
+export function workflowPermission(workflow, verb) {
+    return `${WORKFLOW_PERMISSION_SCOPE}:${workflow}:${verb}`;
+}
+/** `lead:changeStatus`. */
+export function permissionOf(entity, verb) {
+    return `${entity}:${verb}`;
+}
+/**
+ * Whether a granted permission, which may hold wildcards, covers the required one. A wildcard entity
+ * covers every entity but those in {@link EXPLICIT_GRANT_ENTITIES}, and of those in
+ * {@link WILDCARD_ENTITY_VERBS} only the listed verbs.
+ */
+export function grants(granted, required) {
+    const workflow = parseWorkflowPermission(required);
+    if (workflow !== undefined) {
+        const holds = parseWorkflowPermission(granted);
+        return (holds !== undefined &&
+            workflow.workflow !== WILDCARD &&
+            workflow.verb !== WILDCARD &&
+            (holds.workflow === WILDCARD ||
+                toSnakeCase(holds.workflow) === toSnakeCase(workflow.workflow)) &&
+            (holds.verb === WILDCARD || holds.verb === workflow.verb));
+    }
+    const held = parsePermission(granted);
+    const wanted = parsePermission(required);
+    if (held === undefined || wanted === undefined) {
+        return false;
+    }
+    const entity = toSnakeCase(wanted.entity);
+    return ((held.entity === WILDCARD
+        ? wildcardEntityCovers(entity, toSnakeCase(wanted.verb))
+        : toSnakeCase(held.entity) === entity) &&
+        (held.verb === WILDCARD || toSnakeCase(held.verb) === toSnakeCase(wanted.verb)));
+}
+/**
+ * A permission as {@link grants} compares it: entity, workflow and verb names in snake_case,
+ * wildcards kept. Two permissions that grant the same thing normalise to the same string; a value
+ * that is not a permission is returned as it is.
+ */
+export function normalizePermission(value) {
+    const snake = (name) => (name === WILDCARD ? WILDCARD : toSnakeCase(name));
+    const workflow = parseWorkflowPermission(value);
+    if (workflow !== undefined) {
+        return `${WORKFLOW_PERMISSION_SCOPE}:${snake(workflow.workflow)}:${workflow.verb}`;
+    }
+    const parsed = parsePermission(value);
+    return parsed === undefined ? value : permissionOf(snake(parsed.entity), snake(parsed.verb));
+}
+/** Whether a required permission is one only a named `user` permission grants, workloads included. */
+function isUserAdministration(required) {
+    const wanted = parsePermission(required);
+    return (wanted !== undefined &&
+        toSnakeCase(wanted.entity) === USER_ENTITY &&
+        !wildcardEntityCovers(USER_ENTITY, toSnakeCase(wanted.verb)));
+}
+/**
+ * Feedback always needs named grants, including for pipeline workloads. The workspace's own pipeline
+ * code reads sign-in identities, for example to address a member in a chat, but nothing it runs
+ * writes them: only the platform does.
+ */
+function workloadWildcardCovers(required) {
+    const wanted = parsePermission(required);
+    if (wanted !== undefined && toSnakeCase(wanted.entity) === "user_identity") {
+        return wanted.verb === READ_VERB;
+    }
+    return (!isUserAdministration(required) &&
+        (wanted === undefined ||
+            !["app_feedback", "app_feedback_file"].includes(toSnakeCase(wanted.entity))));
+}
+/**
+ * Whether the principal may do what `required` names: one of its permissions equals it, or covers it
+ * through a wildcard. Workload wildcards exclude user administration, feedback and writes of sign-in
+ * identities.
+ */
+export function isAllowed(required, principal) {
+    return (
+    // Exact authored grants are common in large catalogs. Validate the match
+    // with the same matcher: an identical malformed or wildcard workflow name
+    // must not become a grant. No authorization result survives this call.
+    (principal.permissions.includes(required) && grants(required, required)) ||
+        (principal.execution !== undefined &&
+            principal.permissions.includes("*:*") &&
+            workloadWildcardCovers(required)) ||
+        principal.permissions.some((granted) => grants(granted, required)));
+}
+/**
+ * Which records of `required` the principal's grants cover, once {@link isAllowed} said it holds
+ * it: `undefined` when some grant covers it unscoped, wildcards included; otherwise the `where` of
+ * the one scoped grant that names it, or the `or` of several. Without any grant the result is
+ * `{ or: [] }`, which matches no record.
+ */
+export function effectiveScope(required, principal) {
+    const scopes = principal.scopes ?? [];
+    const scoped = new Set(scopes.map((candidate) => normalizePermission(candidate.permission)));
+    if ((principal.execution !== undefined &&
+        principal.permissions.includes("*:*") &&
+        workloadWildcardCovers(required)) ||
+        principal.permissions.some((granted) => !scoped.has(normalizePermission(granted)) && grants(granted, required))) {
+        return undefined;
+    }
+    const wheres = scopes
+        .filter((candidate) => grants(candidate.permission, required))
+        .map((candidate) => candidate.where);
+    return wheres.length === 1 ? wheres[0] : { or: wheres };
+}
+/**
+ * The records of `entity` a holder reads: `undefined` when it holds no scoped permission or reads
+ * the entity unscoped, else the {@link effectiveScope} of `<entity>:read`. A holder without the read
+ * permission gets `undefined` too: whether it may read at all is the permission check's decision.
+ */
+export function readScope(entity, holder) {
+    if (holder.scopes === undefined || holder.scopes.length === 0) {
+        return undefined;
+    }
+    const permission = permissionOf(entity, READ_VERB);
+    return isAllowed(permission, holder) ? effectiveScope(permission, holder) : undefined;
+}
+/** Expand workload authority for permission-only catalog and documentation readers. */
+export function effectivePermissions(principal) {
+    return principal.execution !== undefined && principal.permissions.includes("*:*")
+        ? [...principal.permissions, "agent_chat:*"]
+        : principal.permissions;
+}
+/** The first of the required permissions the principal lacks, or `undefined` when it holds all. */
+export function missingPermission(required, principal) {
+    return required.find((permission) => !isAllowed(permission, principal));
+}
+/**
+ * What a generated action requires: `<entity>:<action>`, except `upsert_by_<property>`, which may
+ * create or update and so requires both `<entity>:create` and `<entity>:update`.
+ */
+export function generatedActionPermissions(entity, action) {
+    return toSnakeCase(action).startsWith(GENERATED_UPSERT_PREFIX)
+        ? [permissionOf(entity, "create"), permissionOf(entity, "update")]
+        : [permissionOf(entity, action)];
+}
+/**
+ * The union of the permissions of the roles a principal holds, in the order the ontology declares
+ * them. A held role the ontology does not declare grants nothing.
+ */
+export function permissionsOf(roles, held) {
+    const permissions = new Set();
+    for (const candidate of roles) {
+        if (held.includes(candidate.name)) {
+            for (const permission of candidate.permissions ?? []) {
+                permissions.add(permission);
+            }
+        }
+    }
+    return [...permissions];
+}
+/**
+ * The scoped entries of the roles a principal holds, in the order the ontology declares them,
+ * without the dead ones: those a held role grants unscoped, by the same permission or through a
+ * wildcard, since an unscoped grant covers every record. With {@link permissionsOf}, what a
+ * principal's `scopes` holds; {@link effectiveScope} stays the authority either way.
+ */
+export function scopesOf(roles, held) {
+    const holding = roles.filter((candidate) => held.includes(candidate.name));
+    const unscoped = [
+        ...new Set(holding.flatMap((candidate) => {
+            const scoped = new Set((candidate.scopes ?? []).map((scope) => normalizePermission(scope.permission)));
+            return (candidate.permissions ?? [])
+                .map(normalizePermission)
+                .filter((permission) => !scoped.has(permission));
+        })),
+    ];
+    return holding.flatMap((candidate) => (candidate.scopes ?? []).filter((scope) => !unscoped.some((permission) => grants(permission, scope.permission))));
+}
+/**
+ * {@link scopesOf} as a principal carries it: absent when no held role scopes a permission, so that
+ * a principal of an ontology without scoped permissions is what it was before them.
+ */
+export function principalScopes(roles, held) {
+    const scopes = scopesOf(roles, held);
+    return scopes.length === 0 ? {} : { scopes };
+}
+/** The roles whose permissions cover `required`, by name. */
+export function rolesGranting(roles, required) {
+    return roles
+        .filter((candidate) => isAllowed(required, { permissions: candidate.permissions ?? [] }))
+        .map((candidate) => candidate.name);
+}

package/dist/property.d.ts

@@ -0,0 +1,188 @@
+import { Schema } from "effect";
+import { BlobValue } from "./blob.js";
+/** The closed set of storage types. Each has a known column, JSON Schema, filters and rendering. */
+export declare const PROPERTY_TYPES: readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob", "list"];
+export type PropertyType = (typeof PROPERTY_TYPES)[number];
+/** Schema annotation that carries a property's storage metadata. */
+export declare const PROPERTY_ANNOTATION = "segmentstream/ontology/property";
+/**
+ * Schema annotation that marks a record reference in an action input. It is emitted into the input's
+ * JSON Schema so that consumers can offer a record picker.
+ */
+export declare const REFERENCE_ANNOTATION = "x-ontology-ref";
+/**
+ * An email address: a local part, one `@`, and a domain of dot-separated labels. The labels exclude
+ * the dot that separates them, so no two parts of the pattern can match the same characters and it
+ * runs in linear time on any input.
+ */
+export declare const EMAIL_PATTERN: RegExp;
+/** A described value of a `select` property. */
+export interface SelectOption {
+    readonly value: string;
+    readonly label: string;
+    /** Absent only for options given as plain strings, which `check` rejects. */
+    readonly description?: string;
+}
+/** Storage metadata of a property, kept in the schema's annotations under {@link PROPERTY_ANNOTATION}. */
+export interface PropertyDefinition {
+    readonly column?: string;
+    readonly scope?: ReadonlyArray<string>;
+    readonly type: PropertyType;
+    readonly optional: boolean;
+    readonly unique: boolean;
+    readonly managed: boolean;
+    /** Present only when the property declares a default. */
+    readonly default?: unknown;
+    readonly label?: string;
+    readonly description?: string;
+    readonly renamedFrom?: string;
+    readonly display?: string;
+    readonly min?: number;
+    readonly max?: number;
+    readonly maxLength?: number;
+    readonly options?: ReadonlyArray<SelectOption>;
+    readonly accept?: ReadonlyArray<string>;
+    readonly maxBytes?: number;
+    /** The type of a `list` property's items. */
+    readonly items?: PropertyType;
+}
+/**
+ * A property: an Effect Schema of its value, usable in action inputs, with its storage metadata in
+ * the schema's annotations. The two `~ontology` members exist only in the type. They record whether
+ * the property has a default (which makes it optional in `create`) and whether it is unique (which
+ * makes it a key for `upsertBy`).
+ */
+export interface Property<T, Defaulted extends boolean = boolean, Unique extends boolean = boolean> extends Schema.Codec<T> {
+    readonly "~ontology.defaulted": Defaulted;
+    readonly "~ontology.unique": Unique;
+}
+/** Any property, required or optional, as entity `properties` accept it. */
+export type AnyProperty = Property<unknown, boolean, boolean> | Schema.optionalKey<Property<unknown, boolean, boolean>>;
+export interface PropertyOptions<T> {
+    readonly column?: string;
+    readonly scope?: ReadonlyArray<string>;
+    /** The value may be absent: an optional key in inputs and `null` in records. */
+    readonly optional?: boolean;
+    /** Stored when `create` omits the property. */
+    readonly default?: T;
+    readonly unique?: boolean;
+    readonly label?: string;
+    readonly description?: string;
+    /** The property's previous name, for one deploy, so that the column is renamed instead of replaced. */
+    readonly renamedFrom?: string;
+    /** Excluded from the generated `update` action: it changes only through authored actions. */
+    readonly managed?: boolean;
+    /** A display hint independent of the storage type, for example `multiline` for text. */
+    readonly display?: string;
+}
+export interface TextOptions extends PropertyOptions<string> {
+    readonly maxLength?: number;
+}
+export interface NumberOptions extends PropertyOptions<number> {
+    readonly min?: number;
+    readonly max?: number;
+}
+/** A `select` option: a plain string for quick use, or a described option. */
+export type SelectOptionInput<V extends string> = V | {
+    readonly value: V;
+    readonly label?: string;
+    readonly description: string;
+};
+/**
+ * The options a constructor was given, refusing keys its options do not declare: a `const` type
+ * parameter is not checked for excess properties, so `p.integer({ minimum: 1 })` would pass.
+ */
+type Known<O, T> = O & {
+    readonly [K in Exclude<keyof O, keyof T>]: never;
+};
+type HasDefault<O> = O extends {
+    readonly default: unknown;
+} ? true : false;
+type IsUnique<O> = O extends {
+    readonly unique: true;
+} ? true : false;
+/** The schema type a property constructor returns for the given options. */
+export type PropertyOf<T, O> = O extends {
+    readonly optional: true;
+} ? Schema.optionalKey<Property<T, HasDefault<O>, IsUnique<O>>> : Property<T, HasDefault<O>, IsUnique<O>>;
+/**
+ * The options a property was given that its constructor does not take, such as `minimum` for
+ * `p.integer`, which takes `min`. TypeScript refuses them in a literal; `check` reports them for
+ * code that is evaluated without type checking.
+ */
+export declare function unknownPropertyOptions(value: unknown): ReadonlyArray<string>;
+/** Keeps the unknown options of a property on the schema the SDK rebuilt it as. */
+export declare function inheritUnknownOptions(from: unknown, to: unknown): void;
+/** What a constructor takes, for the message that names an unknown option. */
+export declare function propertyOptionNames(type: PropertyType): ReadonlyArray<string>;
+declare function text<const O extends TextOptions>(options?: Known<O, TextOptions>): PropertyOf<string, O>;
+declare function email<const O extends PropertyOptions<string>>(options?: Known<O, PropertyOptions<string>>): PropertyOf<string, O>;
+declare function url<const O extends PropertyOptions<string>>(options?: Known<O, PropertyOptions<string>>): PropertyOf<string, O>;
+declare function integer<const O extends NumberOptions>(options?: Known<O, NumberOptions>): PropertyOf<number, O>;
+declare function number<const O extends NumberOptions>(options?: Known<O, NumberOptions>): PropertyOf<number, O>;
+declare function boolean<const O extends PropertyOptions<boolean>>(options?: Known<O, PropertyOptions<boolean>>): PropertyOf<boolean, O>;
+/** A calendar date as `YYYY-MM-DD`. */
+declare function date<const O extends PropertyOptions<string>>(options?: Known<O, PropertyOptions<string>>): PropertyOf<string, O>;
+/** An instant as an ISO 8601 string with a time zone, for example `2026-10-04T09:30:00Z`. */
+declare function timestamp<const O extends PropertyOptions<string>>(options?: Known<O, PropertyOptions<string>>): PropertyOf<string, O>;
+/**
+ * One of a closed set of described values. Each option becomes its own JSON Schema branch with its
+ * label as `title` and its description, so that agents see what every value means.
+ */
+declare function select<const V extends string, const O extends PropertyOptions<NoInfer<V>>>(options: ReadonlyArray<SelectOptionInput<V>>, settings?: Known<O, PropertyOptions<NoInfer<V>>>): PropertyOf<V, O>;
+/** Any JSON value. */
+declare function json<const O extends PropertyOptions<Schema.Json>>(options?: Known<O, PropertyOptions<Schema.Json>>): PropertyOf<Schema.Json, O>;
+export interface ReferenceOptions {
+    readonly optional?: boolean;
+    readonly label?: string;
+    readonly description?: string;
+}
+/** The schema type of a record reference: the referenced record's id. */
+export type ReferenceOf<O> = O extends {
+    readonly optional: true;
+} ? Schema.optionalKey<Schema.Codec<string>> : Schema.Codec<string>;
+/**
+ * A reference to a record of an entity, by id, for action inputs. Relationships between entities
+ * are declared with `rel.one` and `rel.many`, not with references.
+ */
+declare function ref<const O extends ReferenceOptions>(target: string | {
+    readonly name: string;
+}, options?: Known<O, ReferenceOptions>): ReferenceOf<O>;
+/** Property constructors. */
+export interface BlobOptions extends Omit<PropertyOptions<BlobValue>, "default" | "unique"> {
+    /** MIME types or ranges such as image/*; omitted means any file. */
+    readonly accept?: ReadonlyArray<string>;
+    readonly maxBytes?: number;
+}
+declare function blob<const O extends BlobOptions>(options?: Known<O, BlobOptions>): PropertyOf<BlobValue, O>;
+export interface ListOptions extends Omit<PropertyOptions<ReadonlyArray<string>>, "column" | "scope" | "optional" | "default" | "unique" | "renamedFrom"> {
+    /** Lists are managed: the platform keeps their values. */
+    readonly managed: true;
+}
+/**
+ * A list of values of one property type, read-only and kept by the platform. Only the built-in
+ * `User` has one, `roles`, which the runtime reads from the role assignments beside the table:
+ * `check` refuses a list on any other entity, so no table has an array column and no action
+ * writes one. Filters take `has` and `hasAny`; a list cannot be sorted on.
+ */
+declare function list<const O extends ListOptions>(item: Property<string, boolean, boolean>, options: Known<O, ListOptions>): Property<ReadonlyArray<string>, false, false>;
+export declare const p: {
+    readonly text: typeof text;
+    readonly email: typeof email;
+    readonly url: typeof url;
+    readonly integer: typeof integer;
+    readonly number: typeof number;
+    readonly boolean: typeof boolean;
+    readonly date: typeof date;
+    readonly timestamp: typeof timestamp;
+    readonly select: typeof select;
+    readonly json: typeof json;
+    readonly blob: typeof blob;
+    readonly list: typeof list;
+    readonly ref: typeof ref;
+};
+/** The storage metadata of a schema built with a `p.*` constructor, or `undefined` for any other value. */
+export declare function propertyDefinition(value: unknown): PropertyDefinition | undefined;
+/** The entity a `p.ref` schema points at, or `undefined` for any other value. */
+export declare function referenceTarget(value: unknown): string | undefined;
+export {};