@sixb/core 0.1.21 → 0.1.22

package/src/security/grants.ts

@@ -9,10 +9,16 @@
 
 import type { ActionDefinition, ObjectActionDefinition } from "../actions/types"
 import { isObjectActionDefinition } from "../actions/validation"
-import type { AgentReference, AgentUsageReference } from "../agents/types"
+import type {
+  AgentMemoryReference,
+  AgentReference,
+  AgentThreadsReference,
+  AgentUsageReference,
+} from "../agents/types"
 import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets"
-import type { ObjectType } from "../ontology"
+import { resolveWhere } from "../objects/sdk/where"
+import type { ObjectType, ObjectTypeWithPropertyTokens } from "../ontology"
 import type { PipelineDefinition } from "../pipelines"
 import { createShareActionGrant, createShareViewGrant, isShareTarget } from "../shares/builders"
 import type {
@@ -30,17 +36,21 @@ import {
   definitionIdOf,
   isBreadthSelector,
 } from "./every"
+import { project } from "./project"
 import type {
   AgentRunGrant,
   AppendGrant,
   ApplyGrant,
   EditGrant,
   ManageGrant,
+  ModelsRunGrant,
+  ObjectViewGrantBuilder,
   ObserveGrant,
-  ProjectSurfaceReference,
+  ProjectReference,
   RunGrant,
   Selection,
   ShareGrant,
+  UsersViewGrant,
   ViewGrant,
 } from "./types"
 
@@ -156,17 +166,112 @@ function resolveGrant<TDefinition extends { readonly id?: unknown }, TTarget ext
   return { target, selection: { all: false, ids } }
 }
 
+/** `project` itself and the surfaces of it that are not viewed, which `can.view` rejects. */
+const UNVIEWABLE_PROJECT_REFERENCES: ReadonlySet<unknown> = new Set([
+  project,
+  project.logs,
+  project.activity,
+])
+
 function view<const TObjectTypeId extends string>(
   input: ShareTarget<TObjectTypeId>
 ): ShareViewGrantBuilder<TObjectTypeId>
+function view(input: ProjectReference["users"]): UsersViewGrant
+function view<const TObjectType extends ObjectTypeWithPropertyTokens>(
+  input: TObjectType
+): ObjectViewGrantBuilder<TObjectType>
 function view(input: GrantInput<ObjectType, "object">): ViewGrant<"object">
 function view(input: GrantInput<DatasetDefinition, "dataset">): ViewGrant<"dataset">
 function view(
-  input: ShareTarget | GrantInput<ObjectType | DatasetDefinition, "object" | "dataset">
-): ViewGrant | ShareViewGrantBuilder {
+  input:
+    | ShareTarget
+    | ProjectReference["users"]
+    | GrantInput<ObjectType | DatasetDefinition, "object" | "dataset">
+): ViewGrant | UsersViewGrant | ShareViewGrantBuilder {
   if (isShareTarget(input)) return createShareViewGrant(input)
+
+  if (isUsersReference(input)) {
+    return { kind: "grant", capability: "view", target: "users" }
+  }
+
+  // `project` and its other surfaces would otherwise read as an object type with no id.
+  if (UNVIEWABLE_PROJECT_REFERENCES.has(input)) {
+    throw new SecurityValidationError(
+      "[Sixb] can.view accepts object types, datasets, shares, or project.users."
+    )
+  }
+
   const { target, selection } = resolveGrant(input, "can.view", VIEW_TARGETS)
-  return { kind: "grant", capability: "view", target, selection }
+  const grant: ViewGrant = { kind: "grant", capability: "view", target, selection }
+
+  // Only a grant on one object type takes a condition, since a condition reads that type's
+  // properties. As in `apply`, the cast restores the branch `Array.isArray` cannot narrow.
+  const one: ObjectType | undefined =
+    target !== "object" || Array.isArray(input) || isBreadthSelector(input)
+      ? undefined
+      : (input as ObjectType)
+
+  if (one) {
+    Object.defineProperty(grant, "where", {
+      configurable: false,
+      enumerable: false,
+      writable: false,
+      value: (callback: unknown) => conditionalViewGrant(grant, one, callback),
+    })
+  }
+
+  return grant
+}
+
+/**
+ * The condition is built once, here, with the same builder and the same conversion as an object
+ * query's `.where()`. Startup validates it against the ontology.
+ */
+function conditionalViewGrant(
+  grant: ViewGrant,
+  objectType: ObjectType,
+  callback: unknown
+): ViewGrant<"object"> {
+  const subject = `can.view(${objectType.id}).where(...)`
+
+  if (typeof callback !== "function") {
+    throw new SecurityValidationError(
+      `[Sixb] ${subject} expects a function, such as (object) => object.p.status.eq("open").`
+    )
+  }
+
+  const condition = resolveWhere(callback as Parameters<typeof resolveWhere>[0])
+  if (condition === undefined) {
+    throw new SecurityValidationError(
+      `[Sixb] ${subject} returned no condition. Return a predicate, or drop .where() to grant every object.`
+    )
+  }
+
+  return deepFreeze({
+    kind: "grant",
+    capability: "view",
+    target: "object",
+    selection: structuredClone(grant.selection),
+    condition: structuredClone(condition),
+  })
+}
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value
+
+  for (const child of Object.values(value)) deepFreeze(child)
+  return Object.freeze(value)
+}
+
+function isUsersReference(input: unknown): input is ProjectReference["users"] {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    !Array.isArray(input) &&
+    !isBreadthSelector(input) &&
+    "kind" in input &&
+    input.kind === "users"
+  )
 }
 
 function edit(input: GrantInput<ObjectType, "object">): EditGrant {
@@ -222,17 +327,22 @@ function run(input: GrantInput<WorkflowDefinition, "workflow">): RunGrant<"workf
 function run(input: GrantInput<SyncDefinition, "sync">): RunGrant<"sync">
 function run(input: GrantInput<PipelineDefinition, "pipeline">): RunGrant<"pipeline">
 function run(input: AgentReference): AgentRunGrant
+function run(input: ProjectReference["models"]): ModelsRunGrant
 function run(
   input:
     | AgentReference
+    | ProjectReference["models"]
     | GrantInput<
         WorkflowDefinition | SyncDefinition | PipelineDefinition,
         "workflow" | "sync" | "pipeline"
       >
-): RunGrant | AgentRunGrant {
+): RunGrant | AgentRunGrant | ModelsRunGrant {
   if (isAgentReference(input)) {
     return { kind: "grant", capability: "run", target: "agent" }
   }
+  if (isModelsReference(input)) {
+    return { kind: "grant", capability: "run", target: "models" }
+  }
   const { target, selection } = resolveGrant(input, "can.run", RUN_TARGETS)
   return { kind: "grant", capability: "run", target, selection }
 }
@@ -248,6 +358,17 @@ function isAgentReference(input: unknown): input is AgentReference {
   )
 }
 
+function isModelsReference(input: unknown): input is ProjectReference["models"] {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    !Array.isArray(input) &&
+    !isBreadthSelector(input) &&
+    "kind" in input &&
+    input.kind === "models"
+  )
+}
+
 function isAgentUsageReference(input: unknown): input is AgentUsageReference {
   return (
     typeof input === "object" &&
@@ -259,16 +380,25 @@ function isAgentUsageReference(input: unknown): input is AgentUsageReference {
   )
 }
 
-type ObservableReference = ProjectSurfaceReference | AgentUsageReference
+/**
+ * Listed member by member: a `project` surface is not observable just by existing.
+ * `project.users` is read with `can.view`.
+ */
+type ObservableReference =
+  | ProjectReference["logs"]
+  | ProjectReference["activity"]
+  | AgentUsageReference
+  | AgentThreadsReference
 
 /**
  * Every reference `can.observe` accepts, keyed by its `kind`, which is also its grant target. The
- * full `Record` is what stops a new `project` member from compiling until it is listed here.
+ * full `Record` is what stops a new observable reference from compiling until it is listed here.
  */
 const OBSERVABLE_REFERENCES: Readonly<Record<ObservableReference["kind"], string>> = {
   logs: "project.logs",
   activity: "project.activity",
   aiUsage: "agent.usage",
+  agentThreads: "agent.threads",
 }
 
 function isObservableReference(input: unknown): input is ObservableReference {
@@ -300,14 +430,29 @@ function observe(input: ObservableReference): ObserveGrant {
   return { kind: "grant", capability: "observe", target: value.kind }
 }
 
+function isAgentMemoryReference(input: unknown): input is AgentMemoryReference {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    !Array.isArray(input) &&
+    !isBreadthSelector(input) &&
+    "kind" in input &&
+    input.kind === "agentMemory"
+  )
+}
+
 function manage(input: GrantInput<ConnectorDefinition, "connector">): ManageGrant<"connector">
 function manage(input: AgentUsageReference): ManageGrant<"aiUsage">
+function manage(input: AgentMemoryReference): ManageGrant<"agentMemory">
 function manage(
-  input: GrantInput<ConnectorDefinition, "connector"> | AgentUsageReference
+  input: GrantInput<ConnectorDefinition, "connector"> | AgentUsageReference | AgentMemoryReference
 ): ManageGrant {
   if (isAgentUsageReference(input)) {
     return { kind: "grant", capability: "manage", target: "aiUsage" }
   }
+  if (isAgentMemoryReference(input)) {
+    return { kind: "grant", capability: "manage", target: "agentMemory" }
+  }
   return {
     kind: "grant",
     capability: "manage",

package/src/security/index.ts

@@ -33,10 +33,11 @@ export type {
   MarkingDefinition,
   MembershipOperation,
   MembershipPolicyDefinition,
+  ModelsRunGrant,
+  ObjectViewGrantBuilder,
   ObserveGrant,
   ObserveGrantTarget,
   ProjectReference,
-  ProjectSurfaceReference,
   RedactionReason,
   Redactions,
   RegisteredSecurityDefinitions,
@@ -45,6 +46,7 @@ export type {
   RunGrantTarget,
   Selection,
   ShareGrant,
+  UsersViewGrant,
   ViewGrant,
   ViewGrantTarget,
 } from "./types"

package/src/security/project.ts

@@ -1,8 +1,13 @@
 import type { ProjectReference } from "./types"
 
-/** Project-wide surfaces used in security grants such as `can.observe(project.logs)`. */
+/**
+ * Project-wide surfaces used in security grants such as `can.observe(project.logs)`,
+ * `can.view(project.users)` and `can.run(project.models)`.
+ */
 export const project: ProjectReference = Object.freeze({
   kind: "project",
   logs: Object.freeze({ kind: "logs" }),
   activity: Object.freeze({ kind: "activity" }),
+  users: Object.freeze({ kind: "users" }),
+  models: Object.freeze({ kind: "models" }),
 })

package/src/security/registry.ts

@@ -1,4 +1,5 @@
-import { type ResolvedRole, resolveRoleGrants } from "../authorization"
+import { type ResolvedRole, resolveRoleGrants, resolveRoleViewConditions } from "../authorization"
+import type { OntologyRegistry } from "../ontology"
 import type {
   GroupDefinition,
   MarkingDefinition,
@@ -6,6 +7,7 @@ import type {
   RoleDefinition,
 } from "./types"
 import { validateSecurityDefinitionsAtStartup } from "./validation"
+import { resolveViewCondition, type ViewCondition } from "./view-conditions"
 
 /** Read-only access to validated security definitions and resolved role grants. */
 export interface SecurityDefinitionCatalog {
@@ -35,6 +37,7 @@ export interface SecurityRegistryOptions {
   readonly connectorIds?: ReadonlySet<string>
   readonly shareIds?: ReadonlySet<string>
   readonly getSubTypes?: (objectTypeId: string) => readonly string[]
+  readonly ontology?: OntologyRegistry
 }
 
 export class SecurityRegistry implements SecurityDefinitionCatalog {
@@ -43,6 +46,7 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
   private readonly rolesById: ReadonlyMap<string, RoleDefinition>
   private readonly membershipPoliciesById: ReadonlyMap<string, MembershipPolicyDefinition>
   private readonly resolvedRoles: readonly ResolvedRole[]
+  private readonly viewConditions: readonly ViewCondition[]
 
   constructor(input: SecurityRegistryOptions) {
     const definitions = validateSecurityDefinitionsAtStartup({
@@ -61,6 +65,12 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
       shareIds: input.shareIds,
     })
 
+    // Conditions are checked here rather than with the other grant rules: those also load in the
+    // browser through `defineGroup`, and a condition needs the object-query validator.
+    this.viewConditions = definitions.roles.flatMap((role) =>
+      role.grants.flatMap((grant) => resolveViewCondition(role.id, grant, input.ontology) ?? [])
+    )
+
     const universe = {
       objectTypeIds: input.objectTypeIds ?? new Set<string>(),
       datasetIds: input.datasetIds ?? new Set<string>(),
@@ -77,12 +87,22 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
     this.groupsById = definitions.groupsById
     this.rolesById = definitions.rolesById
     this.membershipPoliciesById = definitions.membershipPoliciesById
-    this.resolvedRoles = definitions.roles.map((role) => ({
-      id: role.id,
-      grantedToGroupIds: role.grantedToGroupIds,
-      grants: resolveRoleGrants(role, universe),
-      clearances: new Set(role.clearances ?? []),
-    }))
+    this.resolvedRoles = definitions.roles.map((role) => {
+      const grants = resolveRoleGrants(role, universe)
+      const viewConditions = resolveRoleViewConditions(
+        this.viewConditions.filter((condition) => condition.roleId === role.id),
+        grants,
+        universe
+      )
+
+      return {
+        id: role.id,
+        grantedToGroupIds: role.grantedToGroupIds,
+        grants,
+        ...(viewConditions.size > 0 ? { viewConditions } : {}),
+        clearances: new Set(role.clearances ?? []),
+      }
+    })
   }
 
   listMarkings(): readonly MarkingDefinition[] {
@@ -113,6 +133,11 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
     return this.resolvedRoles
   }
 
+  /** Every role's `can.view(Type).where(...)`, validated, in declaration order. */
+  listViewConditions(): readonly ViewCondition[] {
+    return this.viewConditions
+  }
+
   listMembershipPolicies(): readonly MembershipPolicyDefinition[] {
     return [...this.membershipPoliciesById.values()]
   }

package/src/security/types.ts

@@ -1,3 +1,7 @@
+import type { ObjectQueryPredicate } from "../objects/query"
+import type { ObjectTypeWithPropertyTokens } from "../ontology"
+import type { ObjectWhereBuilder, ObjectWhereClause } from "../runtime/types"
+
 export interface GroupDefinition<TId extends string = string> {
   readonly kind: "group"
   readonly id: TId
@@ -53,6 +57,37 @@ export interface ViewGrant<TTarget extends ViewGrantTarget = ViewGrantTarget> {
   readonly capability: "view"
   readonly target: TTarget
   readonly selection: Selection
+  /**
+   * The objects this grant covers, when it covers only some. Built once by
+   * `can.view(Type).where(...)`, and only on a grant for one object type.
+   */
+  readonly condition?: ObjectQueryPredicate
+}
+
+/** `can.view(Type)`: a view grant on one object type, which `.where()` can narrow. */
+export interface ObjectViewGrantBuilder<
+  TObjectType extends ObjectTypeWithPropertyTokens = ObjectTypeWithPropertyTokens,
+> extends ViewGrant<"object"> {
+  /**
+   * Grant only the objects that match, with the builder of an object query's `.where()`. An
+   * array means AND. A reader sees the union of their grants, so an unconditional
+   * `can.view(Type)` from another role still grants every object.
+   */
+  where(
+    condition: (
+      object: ObjectWhereBuilder<TObjectType>
+    ) => ObjectWhereClause<TObjectType> | readonly ObjectWhereClause<TObjectType>[]
+  ): ViewGrant<"object">
+}
+
+/**
+ * Read the project's member directory: names, emails, avatars and status. The directory is one
+ * surface, so there is nothing to select. Kept apart from {@link ViewGrant}, which always selects.
+ */
+export interface UsersViewGrant {
+  readonly kind: "grant"
+  readonly capability: "view"
+  readonly target: "users"
 }
 
 /**
@@ -116,7 +151,14 @@ export interface AgentRunGrant {
   readonly target: "agent"
 }
 
-export type ObserveGrantTarget = "logs" | "aiUsage" | "activity"
+/** Call every model in the project's catalog directly, such as through `sixb models`. */
+export interface ModelsRunGrant {
+  readonly kind: "grant"
+  readonly capability: "run"
+  readonly target: "models"
+}
+
+export type ObserveGrantTarget = "logs" | "aiUsage" | "activity" | "agentThreads"
 
 /**
  * Project-wide surfaces used in security grants such as `can.observe(project.logs)`. Each member's
@@ -128,14 +170,15 @@ export interface ProjectReference {
   readonly logs: { readonly kind: "logs" }
   /** Visits and page views recorded in the project's app. */
   readonly activity: { readonly kind: "activity" }
+  /** The project's member directory: names, emails, avatars and status. */
+  readonly users: { readonly kind: "users" }
+  /** Every model in the project's catalog, for `can.run(project.models)`. */
+  readonly models: { readonly kind: "models" }
 }
 
-/** Any member of `project`, such as `project.logs`. */
-export type ProjectSurfaceReference = ProjectReference[Exclude<keyof ProjectReference, "kind">]
-
 /**
- * Read the project's logs, its AI usage or its app activity. Each is one surface, so there is
- * nothing to select.
+ * Read the project's logs, its AI usage, its app activity or every user's Agent conversations. Each
+ * is one surface, so there is nothing to select.
  */
 export interface ObserveGrant {
   readonly kind: "grant"
@@ -143,11 +186,11 @@ export interface ObserveGrant {
   readonly target: ObserveGrantTarget
 }
 
-export type ManageGrantTarget = "connector" | "aiUsage"
+export type ManageGrantTarget = "connector" | "aiUsage" | "agentMemory"
 
 /**
- * Manage the selected connectors, or the project's AI usage-limit policies. AI usage is one
- * surface, so its grant selects nothing.
+ * Manage the selected connectors, the project's AI usage-limit policies, or the project's shared
+ * Agent memory. AI usage and memory are one surface each, so their grants select nothing.
  */
 export type ManageGrant<TTarget extends ManageGrantTarget = ManageGrantTarget> =
   TTarget extends "connector"
@@ -165,12 +208,14 @@ export type ManageGrant<TTarget extends ManageGrantTarget = ManageGrantTarget> =
 
 export type GrantDefinition =
   | ViewGrant
+  | UsersViewGrant
   | EditGrant
   | AppendGrant
   | ApplyGrant
   | ShareGrant
   | RunGrant
   | AgentRunGrant
+  | ModelsRunGrant
   | ObserveGrant
   | ManageGrant
 

package/src/security/validation.ts

@@ -235,8 +235,13 @@ export function assertGrantDefinition(
     )
   }
 
-  if (value.capability === "view" && value.target !== "object" && value.target !== "dataset") {
-    throw createError(`[Sixb] ${field} view grant target must be 'object' or 'dataset'.`)
+  if (
+    value.capability === "view" &&
+    value.target !== "object" &&
+    value.target !== "dataset" &&
+    value.target !== "users"
+  ) {
+    throw createError(`[Sixb] ${field} view grant target must be 'object', 'dataset', or 'users'.`)
   }
 
   if (
@@ -244,10 +249,11 @@ export function assertGrantDefinition(
     value.target !== "workflow" &&
     value.target !== "sync" &&
     value.target !== "pipeline" &&
-    value.target !== "agent"
+    value.target !== "agent" &&
+    value.target !== "models"
   ) {
     throw createError(
-      `[Sixb] ${field} run grant target must be 'workflow', 'sync', 'pipeline', or 'agent'.`
+      `[Sixb] ${field} run grant target must be 'workflow', 'sync', 'pipeline', 'agent', or 'models'.`
     )
   }
 
@@ -255,19 +261,28 @@ export function assertGrantDefinition(
     value.capability === "observe" &&
     value.target !== "logs" &&
     value.target !== "aiUsage" &&
-    value.target !== "activity"
+    value.target !== "activity" &&
+    value.target !== "agentThreads"
   ) {
     throw createError(
-      `[Sixb] ${field} observe grant target must be 'logs', 'aiUsage', or 'activity'.`
+      `[Sixb] ${field} observe grant target must be 'logs', 'aiUsage', 'activity', or 'agentThreads'.`
     )
   }
 
-  if (value.capability === "manage" && value.target !== "connector" && value.target !== "aiUsage") {
-    throw createError(`[Sixb] ${field} manage grant target must be 'connector' or 'aiUsage'.`)
+  if (
+    value.capability === "manage" &&
+    value.target !== "connector" &&
+    value.target !== "aiUsage" &&
+    value.target !== "agentMemory"
+  ) {
+    throw createError(
+      `[Sixb] ${field} manage grant target must be 'connector', 'aiUsage', or 'agentMemory'.`
+    )
   }
 
-  // The agent, logs, AI usage and activity are one surface each, so their grants select nothing.
-  // The checks above settled the capability and target, so the kind is known.
+  // The member directory, the agent, logs, AI usage, activity, Agent conversations and Agent
+  // memory are one surface each, so their grants select nothing. The checks above settled the
+  // capability and target, so the kind is known.
   if (isSingletonGrantKind(grantKindOf(value as unknown as GrantDefinition))) {
     if (value.selection !== undefined) {
       throw createError(
@@ -501,7 +516,8 @@ function assertGrantReferences(
     }
     return
   }
-  // Logs and AI usage are always there; only targeted grants name ids to check.
+  // The member directory, logs and AI usage are always there; only targeted grants name ids to
+  // check.
   if (!("selection" in grant)) return
   const kind = grantKindOf(grant)
   if (isSingletonGrantKind(kind)) return