@sixb/core 0.1.21 → 0.1.22

package/src/execution/object-reader-security.ts

@@ -1,17 +1,25 @@
-import { assertAuthorized, isAllowed } from "../authorization"
+import { assertAuthorized, assertRuntimeAuthorizationBound, isAllowed } from "../authorization"
 import { AuthorizationError } from "../authorization/errors"
 import type { AuthorizationContext } from "../authorization/types"
-import { unreadableError } from "../objects/property-clearance"
+import { type Unreadable, unreadableError } from "../objects/property-clearance"
+import { bindCurrentUserPredicate } from "../objects/query/current-user"
+import type { ObjectQueryPredicate } from "../objects/query/ir"
 import {
   createSelectedObjectQueryAdmission,
   type SelectedObjectQueryAdmission,
 } from "../objects/query/selected-read-admission"
 import type { OntologyRegistry } from "../ontology"
+import type { UserRef } from "../ontology/user-ref"
 import type { AppliedMarkings } from "../security/applied-markings"
-import type { CompiledObjectReadStep, ObjectLinkRow } from "../storage"
+import type {
+  CompiledConditionalObjectReadScope,
+  CompiledObjectReadStep,
+  ObjectLinkRow,
+} from "../storage"
+import { compileConditionalObjectReadScope } from "../storage/objects/read-scope"
 import type { resolveExecutionScopeAuthorization } from "./authorization"
 import { type Clearance, ObjectReaderClearance } from "./object-reader-clearance"
-import type { RuntimeAuthorization } from "./types"
+import type { AuthorizablePrincipal, RuntimeAuthorization } from "./types"
 
 export type ResolvedExecutionAuthority = ReturnType<typeof resolveExecutionScopeAuthorization>
 
@@ -30,7 +38,12 @@ export interface ObjectReaderDelegation {
 
 /**
  * Who reads, and what it may read: the exact execution authority, the selection a delegated one
- * carries, and its clearance. It decides whether an object type or a link is viewable.
+ * carries, the conditions a principal reads some types through, and its clearance. It decides
+ * whether an object type or a link is viewable.
+ *
+ * A type a principal views only through a condition is viewable here, and nowhere else: the
+ * reader's storage shows only the objects the condition matches. A check that answers for one
+ * object of such a type reads that object through the same storage.
  */
 export class ObjectReaderSecurity {
   /** The registered authority the reader is bound to. */
@@ -41,6 +54,12 @@ export class ObjectReaderSecurity {
   /** Present for delegated authority only. */
   readonly delegation?: ObjectReaderDelegation
   readonly clearance: ObjectReaderClearance
+  /** The user `currentUser()` stands for in this reader's queries; absent when no user reads. */
+  readonly requestingUser?: UserRef
+  /** What the reader's storage reads through: present when a principal views a type under one. */
+  readonly conditionalScope?: CompiledConditionalObjectReadScope
+  /** The properties each conditioned type's condition reads, which its clearance must show. */
+  readonly #conditionProperties: ReadonlyMap<string, readonly string[]>
 
   constructor(input: {
     readonly authorization: RuntimeAuthorization
@@ -48,10 +67,14 @@ export class ObjectReaderSecurity {
     readonly projectId: string
     readonly ontology: OntologyRegistry
     readonly appliedMarkings?: AppliedMarkings
+    readonly requestedBy: AuthorizablePrincipal | undefined
   }) {
     const authority = input.authority
     this.authorization = input.authorization
     this.authority = authority
+    if (input.requestedBy?.type === "user") {
+      this.requestingUser = Object.freeze({ type: "user", id: input.requestedBy.id })
+    }
     this.runtime = Object.freeze({
       projectId: input.projectId,
       runtimeAuthorization: input.authorization,
@@ -67,6 +90,31 @@ export class ObjectReaderSecurity {
       })
     }
 
+    const conditions = authority.type === "principal" ? authority.context.viewConditions : undefined
+    this.#conditionProperties = new Map(
+      [...(conditions ?? [])].map(([objectTypeId, predicates]) => [
+        objectTypeId,
+        [...new Set(predicates.flatMap(propertiesReadBy))],
+      ])
+    )
+
+    if (authority.type === "principal" && conditions && conditions.size > 0) {
+      // A reader sees an object any of its conditions matches. In a condition, `currentUser()` is
+      // the principal the grant was resolved for, when it is a user: never the user who requested
+      // the execution, which an agent's service account runs for. Otherwise it is no one.
+      const principal = authority.context.principal
+      const grantee: UserRef | undefined =
+        principal.type === "user" ? { type: "user", id: principal.id } : undefined
+
+      this.conditionalScope = compileConditionalObjectReadScope({
+        kind: "conditional",
+        conditions: [...conditions].map(([objectTypeId, predicates]) => ({
+          objectTypeId,
+          predicate: bindCurrentUserPredicate(anyOf(predicates), grantee),
+        })),
+      })
+    }
+
     this.clearance = new ObjectReaderClearance({
       ontology: input.ontology,
       clearances: clearancesForAuthority(authority),
@@ -86,9 +134,7 @@ export class ObjectReaderSecurity {
         )
       }
     } else {
-      for (const objectTypeId of new Set(objectTypeIds)) {
-        assertAuthorized(this.runtime, { kind: "object.view", objectTypeId })
-      }
+      this.assertObjectTypesGranted(objectTypeIds, clearance)
     }
 
     if (!clearance) return
@@ -99,12 +145,45 @@ export class ObjectReaderSecurity {
     }
   }
 
-  isObjectTypeViewable(objectTypeId: string, clearance: Clearance): boolean {
-    if (clearance?.unreadableType(objectTypeId)) return false
+  /**
+   * Refuse a type a principal holds no view grant for, before its clearance is applied to what it
+   * reads. A type viewed through a condition passes while the clearance shows every property the
+   * condition reads.
+   */
+  assertObjectTypesGranted(objectTypeIds: readonly string[], clearance: Clearance): void {
+    for (const objectTypeId of new Set(objectTypeIds)) {
+      if (!this.#conditionProperties.has(objectTypeId)) {
+        assertAuthorized(this.runtime, { kind: "object.view", objectTypeId })
+        continue
+      }
+
+      assertRuntimeAuthorizationBound(this.runtime)
+
+      const unreadable = this.#unreadableCondition(objectTypeId, clearance)
+      if (unreadable) throw unreadableError(unreadable)
+    }
+  }
+
+  /** Whether the principal views this type only through a condition, which decides per object. */
+  viewsThroughCondition(objectTypeId: string): boolean {
+    return this.#conditionProperties.has(objectTypeId)
+  }
+
+  isObjectTypeGranted(objectTypeId: string, clearance: Clearance): boolean {
     if (this.delegation) return this.delegation.objectTypeIds.has(objectTypeId)
+
+    if (this.#conditionProperties.has(objectTypeId)) {
+      return this.#unreadableCondition(objectTypeId, clearance) === undefined
+    }
+
     return isAllowed(this.runtime.authorization, { kind: "object.view", objectTypeId })
   }
 
+  isObjectTypeViewable(objectTypeId: string, clearance: Clearance): boolean {
+    if (clearance?.unreadableType(objectTypeId)) return false
+    return this.isObjectTypeGranted(objectTypeId, clearance)
+  }
+
   isLinkViewable(link: ObjectLinkRow, clearance: Clearance): boolean {
     if (
       !this.isObjectTypeViewable(link.sourceTypeId, clearance) ||
@@ -116,6 +195,51 @@ export class ObjectReaderSecurity {
 
     return this.delegation?.linkDefinitions.has(delegatedLinkDefinitionKey(link)) ?? true
   }
+
+  #unreadableCondition(objectTypeId: string, clearance: Clearance): Unreadable | undefined {
+    const propertyIds = this.#conditionProperties.get(objectTypeId)
+    return propertyIds && unreadableConditionOf(objectTypeId, propertyIds, clearance)
+  }
+}
+
+/**
+ * Which objects match a condition would reveal a property the reader cannot read, so a clearance
+ * that hides one, a marking applied by a dataset version included, hides the whole type.
+ */
+function unreadableConditionOf(
+  objectTypeId: string,
+  propertyIds: readonly string[],
+  clearance: Clearance
+): Unreadable | undefined {
+  for (const propertyId of propertyIds) {
+    const marking = clearance?.missingMarking(objectTypeId, propertyId)
+    if (marking === undefined) continue
+
+    return {
+      marking,
+      message: `[Sixb] Cannot read '${objectTypeId}': the condition it is viewed through reads '${objectTypeId}.${propertyId}', which requires clearance for marking '${marking}'.`,
+    }
+  }
+
+  return undefined
+}
+
+function propertiesReadBy(predicate: ObjectQueryPredicate): readonly string[] {
+  switch (predicate.op) {
+    case "and":
+    case "or":
+      return predicate.items.flatMap(propertiesReadBy)
+    case "not":
+      return propertiesReadBy(predicate.item)
+    case "constant":
+      return []
+    default:
+      return [predicate.propertyId]
+  }
+}
+
+function anyOf(predicates: readonly ObjectQueryPredicate[]): ObjectQueryPredicate {
+  return predicates.length === 1 ? predicates[0]! : { op: "or", items: predicates }
 }
 
 /**

package/src/execution/object-reader-users.ts

@@ -0,0 +1,122 @@
+import type { UserExpansionPlan } from "../objects/query/user-expansions"
+import type { OntologyRegistry } from "../ontology"
+import { isUserRef, isUserRefPropertySchema } from "../ontology/user-ref"
+import type {
+  AuthUserStore,
+  ExpandedLinkValue,
+  ObjectRow,
+  ObjectRowUsers,
+  UserRecord,
+} from "../storage"
+import { toUserProfile } from "../users/execution"
+
+/** Ids read per storage call: one call for a typical page, bounded for the largest. */
+const LOOKUP_BATCH_SIZE = 500
+
+/** One expanded property of one row, and the member ids its value holds, in stored order. */
+interface UserSlot {
+  readonly users: ObjectRowUsers
+  readonly propertyId: string
+  readonly many: boolean
+  readonly ids: readonly string[]
+}
+
+/**
+ * Attach the member profiles a query expands to the rows the reader returns.
+ *
+ * Every row whose type declares an expanded property gets `users`, so reading an entry never
+ * throws. An entry is left out when the reader may not view the directory, and when the reader
+ * cannot read the value: the rows have already lost their hidden values and carry `redactions`,
+ * so a marked value is never looked up. The rows must be the reader's own copies.
+ */
+export async function attachUserProfiles(input: {
+  readonly rows: readonly ObjectRow[]
+  readonly plan: UserExpansionPlan
+  readonly ontology: OntologyRegistry
+  readonly projectId: string
+  readonly canViewUsers: boolean
+  readonly users: AuthUserStore | undefined
+}): Promise<void> {
+  const slots: UserSlot[] = []
+  collectSlots(input.rows, input.plan, input.ontology, slots)
+
+  if (!input.canViewUsers) return
+
+  const records = await readUsers(input, slots)
+
+  for (const slot of slots) {
+    slot.users[slot.propertyId] = expandedValue(slot, records)
+  }
+}
+
+// An array keeps its members in order and skips ids no member has; a single reference to no
+// member, or an empty one, is `null`.
+function expandedValue(slot: UserSlot, records: ReadonlyMap<string, UserRecord>) {
+  const profiles = slot.ids.flatMap((id) => {
+    const record = records.get(id)
+    return record ? [toUserProfile(record)] : []
+  })
+
+  return slot.many ? profiles : (profiles[0] ?? null)
+}
+
+function collectSlots(
+  rows: readonly ObjectRow[],
+  plan: UserExpansionPlan,
+  ontology: OntologyRegistry,
+  into: UserSlot[]
+): void {
+  for (const row of rows) {
+    const properties = ontology.getObjectTypeById(row.objectTypeId)?.properties ?? []
+
+    for (const propertyId of plan.users) {
+      const property = properties.find((candidate) => candidate.id === propertyId)
+      if (!property || !isUserRefPropertySchema(property.schema)) continue
+
+      row.users ??= {}
+      if (row.redactions?.[propertyId]) continue
+
+      into.push({
+        users: row.users,
+        propertyId,
+        many: property.schema !== "userRef",
+        ids: userIdsOf(row.properties[propertyId]),
+      })
+    }
+
+    for (const link of plan.links) {
+      collectSlots(linkedRows(row.links?.[link.linkId]), link.plan, ontology, into)
+    }
+  }
+}
+
+async function readUsers(
+  input: { readonly projectId: string; readonly users: AuthUserStore | undefined },
+  slots: readonly UserSlot[]
+): Promise<ReadonlyMap<string, UserRecord>> {
+  const records = new Map<string, UserRecord>()
+  const ids = [...new Set(slots.flatMap((slot) => slot.ids))]
+  if (!input.users || ids.length === 0) return records
+
+  for (let start = 0; start < ids.length; start += LOOKUP_BATCH_SIZE) {
+    const batch = ids.slice(start, start + LOOKUP_BATCH_SIZE)
+    for (const record of await input.users.getByIds({ projectId: input.projectId, ids: batch })) {
+      records.set(record.id, record)
+    }
+  }
+
+  return records
+}
+
+// A single reference, or the references of an array in order. Anything else holds no member.
+function userIdsOf(value: unknown): string[] {
+  if (isUserRef(value)) return [value.id]
+  if (!Array.isArray(value)) return []
+  return value.filter(isUserRef).map((ref) => ref.id)
+}
+
+function linkedRows(value: ExpandedLinkValue | undefined): readonly ObjectRow[] {
+  if (value === undefined || value === null) return []
+  if (Array.isArray(value)) return value
+  return [value as ObjectRow]
+}

package/src/execution/preparation.ts

@@ -0,0 +1,78 @@
+import { type PreparedActionRequest, prepareActionRequest } from "../actions/request"
+import type { SixbRuntimeContext } from "../runtime/types"
+import { WorkflowValidationError } from "../workflows/errors"
+import { type PreparedWorkflowRequest, prepareWorkflowRequest } from "../workflows/request"
+import type { WorkflowDefinition } from "../workflows/types"
+import type { ExecutionContext } from "./types"
+
+export interface ActionRequestToPrepare {
+  readonly actionId: string
+  readonly subject?: PreparedActionRequest["subject"]
+  readonly params?: Record<string, unknown>
+}
+
+export interface WorkflowRequestToPrepare {
+  readonly workflowId: string
+  readonly input?: Readonly<Record<string, unknown>>
+}
+
+/** Admit a request with a bound SDK's authority, as it would run, without running it. */
+interface RequestPreparation {
+  action(input: ActionRequestToPrepare): Promise<PreparedActionRequest>
+  workflow(input: WorkflowRequestToPrepare): PreparedWorkflowRequest
+}
+
+const preparationKey = Symbol("sixb.requestPreparation")
+
+interface PreparationOwner {
+  readonly [preparationKey]?: RequestPreparation
+}
+
+/** Let infrastructure prepare requests with a bound SDK's authority. */
+export function registerRequestPreparation(
+  owner: object,
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  workflows: { getById(workflowId: string): WorkflowDefinition | null }
+): void {
+  const preparation: RequestPreparation = {
+    action: (input) => prepareActionRequest(runtime, execution, input),
+    workflow: (input) => {
+      const workflow = workflows.getById(input.workflowId)
+      if (!workflow) {
+        throw new WorkflowValidationError(`[Sixb] Unknown workflow '${input.workflowId}'`)
+      }
+      return prepareWorkflowRequest(runtime, execution, workflow, input.input)
+    },
+  }
+  Object.defineProperty(owner, preparationKey, {
+    configurable: false,
+    enumerable: false,
+    value: preparation,
+    writable: false,
+  })
+}
+
+/** Admit an Action request as `sixb.actions.request` would, and return it normalized. */
+export function prepareBoundActionRequest(
+  sixb: object,
+  input: ActionRequestToPrepare
+): Promise<PreparedActionRequest> {
+  return requirePreparation(sixb).action(input)
+}
+
+/** Admit a workflow start as `sixb.workflows.requestById` would, and return its input snapshot. */
+export function prepareBoundWorkflowRequest(
+  sixb: object,
+  input: WorkflowRequestToPrepare
+): PreparedWorkflowRequest {
+  return requirePreparation(sixb).workflow(input)
+}
+
+function requirePreparation(sixb: object): RequestPreparation {
+  const preparation = (sixb as PreparationOwner)[preparationKey]
+  if (!preparation) {
+    throw new Error("[Sixb] Request preparation is not registered for this execution.")
+  }
+  return preparation
+}

package/src/execution/request.ts

@@ -26,6 +26,7 @@ export type {
   ExecutionAgentRequestInput,
   ExecutionAgentRunResult,
   ListExecutionAgentThreadsInput,
+  ObservedAgentThreadsRuntime,
 } from "../agents/execution"
 export type { AgentDescriptor } from "../agents/types"
 export type { AuthorizationContext } from "../authorization"
@@ -62,6 +63,7 @@ export type {
   WorkflowRunView,
   WorkflowsRuntime,
 } from "../workflows/execution"
+export { prepareBoundActionRequest, prepareBoundWorkflowRequest } from "./preparation"
 export type { AuthorizationRef, ExecutionContext } from "./types"
 
 export type RequestExecutionAuthorization =

package/src/execution/unique-lookup.ts

@@ -0,0 +1,55 @@
+import type { OntologyRegistry } from "../ontology"
+import { OntologyValidationError } from "../ontology/errors"
+import type { ObjectType, ValueType } from "../ontology/types"
+import { uniqueValueKey, uniqueValueKind } from "../ontology/unique-values"
+import { normalizeSchemaValue, validateSchemaValue } from "../ontology/validation"
+
+/**
+ * The key a lookup by a unique property compares: the caller's value, validated and normalized as
+ * a write would store it, so a `Date` finds the object a write gave the same date.
+ */
+export function uniqueLookupKey(
+  ontology: OntologyRegistry,
+  input: { readonly objectTypeId: string; readonly propertyId: string; readonly value: unknown }
+): string {
+  return uniqueLookupKeyOf(
+    ontology.resolveObjectType(input.objectTypeId),
+    input.propertyId,
+    input.value,
+    ontology.getValueTypesById()
+  )
+}
+
+/** {@link uniqueLookupKey} against an already resolved object type. */
+export function uniqueLookupKeyOf(
+  objectType: ObjectType,
+  propertyId: string,
+  value: unknown,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): string {
+  const path = `${objectType.id}.${propertyId}`
+
+  const property = objectType.properties.find((candidate) => candidate.id === propertyId)
+  const kind = property?.unique ? uniqueValueKind(property.schema, valueTypesById) : undefined
+  if (!property || !kind) {
+    throw new OntologyValidationError(
+      `[Sixb] Cannot look up '${path}' by value: getBy needs a property declared with unique: true.`
+    )
+  }
+
+  if (value === null || value === undefined) {
+    throw new OntologyValidationError(
+      `[Sixb] Cannot look up '${path}' by ${String(value)}: no object holds a null or missing value.`
+    )
+  }
+
+  validateSchemaValue(property.schema, value, path, valueTypesById)
+  const key = uniqueValueKey(
+    kind,
+    normalizeSchemaValue(property.schema, value, path, valueTypesById)
+  )
+  if (key === null) {
+    throw new OntologyValidationError(`[Sixb] Cannot look up '${path}' by this value.`)
+  }
+  return key
+}

package/src/execution/visible-objects.ts

@@ -0,0 +1,26 @@
+import { type ObjectBatchKey, objectBatchKey } from "../storage"
+import type { AuthorizedObjectReader } from "./authorized-object-reader"
+
+export interface ObjectKey {
+  readonly objectTypeId: string
+  readonly primaryId: string
+}
+
+/**
+ * The objects among these that a reader sees now, by {@link objectBatchKey}: read through the
+ * reader in one call, so its conditions decide. Each object type must be viewable by the reader.
+ */
+export async function visibleObjects(
+  reader: AuthorizedObjectReader,
+  objects: readonly ObjectKey[]
+): Promise<ReadonlySet<ObjectBatchKey>> {
+  const items = new Map<ObjectBatchKey, ObjectKey>()
+  for (const { objectTypeId, primaryId } of objects) {
+    items.set(objectBatchKey(objectTypeId, primaryId), { objectTypeId, primaryId })
+  }
+
+  if (items.size === 0) return new Set()
+
+  const rows = await reader.getByPrimaryIdBatch({ items: [...items.values()] })
+  return new Set(rows.keys())
+}