@sixb/core 0.1.20 → 0.1.22

package/src/objects/property-clearance.ts

@@ -1,209 +1,228 @@
 import { AuthorizationError } from "../authorization/errors"
-import type { StoredDomainEvent } from "../events/types"
 import type { OntologyDefinitionCatalog } from "../ontology/registry"
+import {
+  type AppliedMarkingsSnapshot,
+  type AppliedSeal,
+  appliedLinkKey,
+  NO_APPLIED_MARKINGS,
+} from "../security/applied-markings-snapshot"
 import { missingClearanceRedactions } from "../security/redactions"
-import type { ExpandedLinkValue, ExpandedObjectRow, ObjectRow } from "../storage"
-import type {
-  ObjectQueryAdmissionState,
-  ObjectQueryPropertyUse,
-  ObjectQuerySemanticAdmission,
-} from "./query/validate"
+import type { Redactions } from "../security/types"
 
 /**
  * The marked properties one reader cannot read, resolved once from its clearances.
  *
  * A property is readable when the reader clears every one of its markings. Unreadable properties
  * are omitted from rows and cannot be used to select, order, or aggregate objects.
+ *
+ * Markings a projection's applied dataset version still carries extend this: its properties keep
+ * them, and an object type or link whose key column carries markings the reader lacks is
+ * unreadable, like a type it has no view grant for.
  */
 export interface PropertyClearance {
-  /** Marked properties of this object type the reader cannot read. */
-  hiddenPropertyIds(objectTypeId: string): ReadonlySet<string>
+  /** What the reader cannot read on this object type; `undefined` when it reads every property. */
+  hiddenProperties(objectTypeId: string): HiddenProperties | undefined
   /** First marking on the property that the reader is not cleared for. */
   missingMarking(objectTypeId: string, propertyId: string): string | undefined
+  /** Why the reader cannot read this object type at all; `undefined` when it can. */
+  unreadableType(objectTypeId: string): Unreadable | undefined
+  /** Why the reader cannot read this link, keyed by its source type; `undefined` when it can. */
+  unreadableLink(objectTypeId: string, linkId: string): Unreadable | undefined
+  /** Every object type and link the reader cannot read, for link queries that name none. */
+  unreadable(): UnreadableTargets
+}
+
+/** A marking the reader lacks on what makes an object type or link unreadable, and why. */
+export interface Unreadable {
+  readonly marking: string
+  readonly message: string
+}
+
+export interface UnreadableTargets {
+  readonly types: ReadonlyMap<string, Unreadable>
+  readonly links: readonly (Unreadable & {
+    readonly objectTypeId: string
+    readonly linkId: string
+    readonly targetObjectTypeId: string
+  })[]
+}
+
+/** The error a read of an unreadable object type or link fails with: a 403. */
+export function unreadableError(unreadable: Unreadable): AuthorizationError {
+  return new AuthorizationError(`clearance:marking:${unreadable.marking}`, unreadable.message)
 }
 
-const NO_PROPERTIES: ReadonlySet<string> = new Set()
+/**
+ * The properties of one object type a clearance set hides. It depends only on the type and the
+ * clearances, so it is computed once and shared by every row and event redacted with it.
+ */
+export interface HiddenProperties {
+  readonly ids: ReadonlySet<string>
+  /**
+   * The `redactions` record of a redacted row or event. It lists every hidden property, whether or
+   * not a row holds a value: listing only present values would reveal which ones are empty.
+   *
+   * Deeply frozen, because every redacted row and event shares it.
+   */
+  readonly redactions: Redactions
+}
 
 // Readers are built per execution, but few distinct clearance sets exist per ontology.
 const clearancesByOntology = new WeakMap<
   OntologyDefinitionCatalog,
   Map<string, PropertyClearance | undefined>
 >()
+// Applied markings change rarely, and a snapshot is replaced only when its content changes.
+const appliedClearancesByOntology = new WeakMap<
+  OntologyDefinitionCatalog,
+  WeakMap<AppliedMarkingsSnapshot, Map<string, PropertyClearance | undefined>>
+>()
+
+const NO_UNREADABLE_TARGETS: UnreadableTargets = Object.freeze({
+  types: new Map(),
+  links: Object.freeze([]),
+})
 
 /**
  * Resolve what a reader with these clearances cannot read. Returns `undefined` when it can read
  * every property, so callers skip redaction entirely.
+ *
+ * A reader cleared for every marking the applied versions add receives the clearance of the code
+ * alone, the same object whatever the snapshot.
  */
 export function resolvePropertyClearance(
   ontology: OntologyDefinitionCatalog,
-  clearances: ReadonlySet<string>
+  clearances: ReadonlySet<string>,
+  applied: AppliedMarkingsSnapshot = NO_APPLIED_MARKINGS
 ): PropertyClearance | undefined {
-  let resolved = clearancesByOntology.get(ontology)
+  const key = JSON.stringify([...clearances].sort())
+
+  if (applied === NO_APPLIED_MARKINGS || clearsEvery(clearances, applied.markings)) {
+    let resolved = clearancesByOntology.get(ontology)
+    if (!resolved) {
+      resolved = new Map()
+      clearancesByOntology.set(ontology, resolved)
+    }
+
+    if (!resolved.has(key)) resolved.set(key, createPropertyClearance(ontology, clearances))
+    return resolved.get(key)
+  }
+
+  let bySnapshot = appliedClearancesByOntology.get(ontology)
+  if (!bySnapshot) {
+    bySnapshot = new WeakMap()
+    appliedClearancesByOntology.set(ontology, bySnapshot)
+  }
+
+  let resolved = bySnapshot.get(applied)
   if (!resolved) {
     resolved = new Map()
-    clearancesByOntology.set(ontology, resolved)
+    bySnapshot.set(applied, resolved)
+  }
+
+  if (!resolved.has(key)) {
+    resolved.set(key, createPropertyClearance(ontology, clearances, applied))
   }
-  const key = JSON.stringify([...clearances].sort())
-  if (!resolved.has(key)) resolved.set(key, createPropertyClearance(ontology, clearances))
   return resolved.get(key)
 }
 
+function clearsEvery(clearances: ReadonlySet<string>, markings: ReadonlySet<string>): boolean {
+  for (const markingId of markings) if (!clearances.has(markingId)) return false
+  return true
+}
+
 function createPropertyClearance(
   ontology: OntologyDefinitionCatalog,
-  clearances: ReadonlySet<string>
+  clearances: ReadonlySet<string>,
+  applied: AppliedMarkingsSnapshot = NO_APPLIED_MARKINGS
 ): PropertyClearance | undefined {
   const missingByType = new Map<string, ReadonlyMap<string, string>>()
+  const hiddenByType = new Map<string, HiddenProperties>()
   for (const objectType of ontology.listObjectTypes()) {
+    const surplus = applied.properties.get(objectType.id)
     const missing = new Map<string, string>()
     for (const property of objectType.properties) {
-      const marking = property.markings?.find((markingId) => !clearances.has(markingId))
+      const marking =
+        property.markings?.find((markingId) => !clearances.has(markingId)) ??
+        firstMissing(surplus?.get(property.id), clearances)
       if (marking !== undefined) missing.set(property.id, marking)
     }
-    if (missing.size > 0) missingByType.set(objectType.id, missing)
-  }
-  if (missingByType.size === 0) return undefined
 
-  const hiddenByType = new Map(
-    [...missingByType].map(([objectTypeId, missing]) => [objectTypeId, new Set(missing.keys())])
-  )
-  return Object.freeze({
-    hiddenPropertyIds: (objectTypeId: string) => hiddenByType.get(objectTypeId) ?? NO_PROPERTIES,
-    missingMarking: (objectTypeId: string, propertyId: string) =>
-      missingByType.get(objectTypeId)?.get(propertyId),
-  })
-}
+    if (missing.size === 0) continue
 
-/**
- * Omit unreadable properties from a row and the objects expanded under it.
- *
- * Every hidden property of the type is listed in `redactions`, whether or not the row holds a
- * value: listing only present values would reveal which hidden properties are empty.
- */
-export function redactObjectRow<TRow extends ObjectRow>(
-  row: TRow,
-  clearance: PropertyClearance
-): TRow {
-  const hidden = clearance.hiddenPropertyIds(row.objectTypeId)
-  const links = row.links
-  if (hidden.size === 0 && links === undefined) return row
-
-  const redacted: TRow = { ...row }
-  if (hidden.size > 0) {
-    redacted.properties = withoutKeys(row.properties, hidden)
-    redacted.redactions = missingClearanceRedactions(hidden)
-  }
-  if (links !== undefined) {
-    redacted.links = Object.fromEntries(
-      Object.entries(links).map(([linkId, value]) => [linkId, redactLinkValue(value, clearance)])
+    missingByType.set(objectType.id, missing)
+    hiddenByType.set(
+      objectType.id,
+      Object.freeze({
+        ids: new Set(missing.keys()),
+        redactions: missingClearanceRedactions(missing.keys()),
+      })
     )
   }
-  return redacted
-}
 
-function redactLinkValue(
-  value: ExpandedLinkValue,
-  clearance: PropertyClearance
-): ExpandedLinkValue {
-  if (value === null) return null
-  if (Array.isArray(value)) return value.map((row) => redactObjectRow(row, clearance))
-  // Array.isArray does not narrow a readonly[] away, so assert the single-object case.
-  return redactObjectRow(value as ExpandedObjectRow, clearance)
-}
-
-/**
- * Omit unreadable properties from an object event, under the same contract as rows. Other events
- * carry no markable value: link properties and telemetry properties cannot be marked.
- */
-export function redactDomainEvent(
-  event: StoredDomainEvent,
-  clearance: PropertyClearance
-): StoredDomainEvent {
-  if (event.topic !== "objects") return event
-  const hidden = clearance.hiddenPropertyIds(event.payload.objectTypeId)
-  if (hidden.size === 0) return event
-
-  const payload = {
-    ...event.payload,
-    propertyChanges: withoutKeys(event.payload.propertyChanges, hidden),
-    redactions: missingClearanceRedactions(hidden),
+  const types = new Map<string, Unreadable>()
+  for (const [objectTypeId, seals] of applied.types) {
+    const unreadable = unreadableBy(seals, clearances, `'${objectTypeId}'`)
+    if (unreadable) types.set(objectTypeId, unreadable)
   }
-  if (event.type === "object.deleted") return { ...event, payload }
-  return {
-    ...event,
-    payload: { ...payload, properties: withoutKeys(event.payload.properties, hidden) },
-  }
-}
 
-function withoutKeys<TValue>(
-  record: Readonly<Record<string, TValue>>,
-  hidden: ReadonlySet<string>
-): Record<string, TValue> {
-  const kept: Record<string, TValue> = {}
-  for (const [key, value] of Object.entries(record)) {
-    if (!hidden.has(key)) kept[key] = value
+  const links: UnreadableTargets["links"][number][] = []
+  const linksByKey = new Map<string, Unreadable>()
+  for (const [key, link] of applied.links) {
+    const name = `link '${link.objectTypeId}.${link.linkId}'`
+    const unreadable = unreadableBy(link.seals, clearances, name)
+    if (!unreadable) continue
+
+    linksByKey.set(key, unreadable)
+    links.push(
+      Object.freeze({
+        ...unreadable,
+        objectTypeId: link.objectTypeId,
+        linkId: link.linkId,
+        targetObjectTypeId: link.targetObjectTypeId,
+      })
+    )
   }
-  return kept
+
+  if (hiddenByType.size === 0 && types.size === 0 && links.length === 0) return undefined
+
+  const unreadable: UnreadableTargets =
+    types.size === 0 && links.length === 0
+      ? NO_UNREADABLE_TARGETS
+      : Object.freeze({ types, links: Object.freeze(links) })
+  return Object.freeze({
+    hiddenProperties: (objectTypeId: string) => hiddenByType.get(objectTypeId),
+    missingMarking: (objectTypeId: string, propertyId: string) =>
+      missingByType.get(objectTypeId)?.get(propertyId),
+    unreadableType: (objectTypeId: string) => types.get(objectTypeId),
+    unreadableLink: (objectTypeId: string, linkId: string) =>
+      linksByKey.get(appliedLinkKey(objectTypeId, linkId)),
+    unreadable: () => unreadable,
+  })
 }
 
-/**
- * Reject every query use of a property the reader cannot read, except projection.
- *
- * Filtering, ordering, searching, or faceting by a hidden value would reveal it through which
- * objects match and in what order. Projection only shapes the output, which is redacted anyway.
- */
-export function createClearanceQueryAdmission(
-  clearance: PropertyClearance
-): ObjectQuerySemanticAdmission {
-  // Each state stands for the object types a query has reached so far. A property without an
-  // explicit type is checked against all of them.
-  const reachedTypes = new WeakMap<ObjectQueryAdmissionState, readonly string[]>()
-  const state = (objectTypeIds: readonly string[]): ObjectQueryAdmissionState => {
-    const created = Object.freeze({})
-    reachedTypes.set(created, Object.freeze([...objectTypeIds]))
-    return created
-  }
-  const reached = (input: ObjectQueryAdmissionState): readonly string[] => {
-    const objectTypeIds = reachedTypes.get(input)
-    if (!objectTypeIds) {
-      throw new Error("[Sixb] Clearance query admission received a state it did not create.")
-    }
-    return objectTypeIds
-  }
-  const empty = state([])
-
-  const admission: ObjectQuerySemanticAdmission = {
-    empty: () => empty,
-    source: (input) => ({ state: state(input.result.objectTypeIds) }),
-    edge: (input) => ({ state: state(input.result.objectTypeIds) }),
-    // A difference only returns objects of its first input.
-    set: (input) =>
-      input.op === "subtract"
-        ? (input.states[0] ?? empty)
-        : state([...new Set(input.states.flatMap(reached))]),
-    property: (input) => {
-      if (input.use === "project") return undefined
-      const objectTypeIds =
-        input.objectTypeId === undefined ? reached(input.state) : [input.objectTypeId]
-      for (const objectTypeId of objectTypeIds) {
-        const marking = clearance.missingMarking(objectTypeId, input.propertyId)
-        if (marking === undefined) continue
-        return new AuthorizationError(
-          `clearance:marking:${marking}`,
-          `[Sixb] Cannot ${PROPERTY_USE_VERBS[input.use]} '${objectTypeId}.${input.propertyId}' at '${input.path}': it requires clearance for marking '${marking}'.`
-        )
-      }
-      return undefined
-    },
-  }
-  return Object.freeze(admission)
+function firstMissing(
+  markings: ReadonlySet<string> | undefined,
+  clearances: ReadonlySet<string>
+): string | undefined {
+  if (!markings) return undefined
+  for (const markingId of [...markings].sort()) if (!clearances.has(markingId)) return markingId
+  return undefined
 }
 
-const PROPERTY_USE_VERBS: Readonly<Record<ObjectQueryPropertyUse, string>> = {
-  filter: "filter by",
-  text: "search",
-  vector: "run a vector search over",
-  sort: "sort by",
-  project: "project",
-  "expand.orderBy": "order expanded objects by",
-  facet: "facet by",
+/** The first seal the reader lacks a marking for, as the message a denied read returns. */
+function unreadableBy(
+  seals: readonly AppliedSeal[],
+  clearances: ReadonlySet<string>,
+  name: string
+): Unreadable | undefined {
+  for (const seal of seals) {
+    const marking = firstMissing(seal.markings, clearances)
+    if (marking === undefined) continue
+    return Object.freeze({
+      marking,
+      message: `[Sixb] Cannot read ${name} until projection '${seal.projectionId}' applies a compliant version: ${seal.reason} carries marking '${marking}'.`,
+    })
+  }
+  return undefined
 }

package/src/objects/query/clearance-admission.ts

@@ -0,0 +1,112 @@
+import { AuthorizationError } from "../../authorization/errors"
+import { type PropertyClearance, type Unreadable, unreadableError } from "../property-clearance"
+import type {
+  ObjectQueryAdmissionState,
+  ObjectQueryPropertyUse,
+  ObjectQuerySemanticAdmission,
+} from "./validate"
+
+/**
+ * Reject every query use of a property the reader cannot read, except projection.
+ *
+ * Filtering, ordering, searching, or faceting by a hidden value would reveal it through which
+ * objects match and in what order. Projection only shapes the output, which is redacted anyway.
+ */
+export function createClearanceQueryAdmission(
+  clearance: PropertyClearance
+): ObjectQuerySemanticAdmission {
+  // Each state stands for the object types a query has reached so far. A property without an
+  // explicit type is checked against all of them.
+  const reachedTypes = new WeakMap<ObjectQueryAdmissionState, readonly string[]>()
+  const state = (objectTypeIds: readonly string[]): ObjectQueryAdmissionState => {
+    const created = Object.freeze({})
+    reachedTypes.set(created, Object.freeze([...objectTypeIds]))
+    return created
+  }
+
+  const reached = (input: ObjectQueryAdmissionState): readonly string[] => {
+    const objectTypeIds = reachedTypes.get(input)
+    if (!objectTypeIds) {
+      throw new Error("[Sixb] Clearance query admission received a state it did not create.")
+    }
+    return objectTypeIds
+  }
+
+  const empty = state([])
+
+  const admission: ObjectQuerySemanticAdmission = {
+    empty: () => empty,
+    // An object type or link the reader cannot read is denied like one it has no view grant for.
+    source: (input) => ({
+      state: state(input.result.objectTypeIds),
+      ...denied(unreadableTypeAmong(clearance, input.result.objectTypeIds)),
+    }),
+    edge: (input) => {
+      // A link is keyed by its source type: the reached types going out, the result coming in.
+      const sourceTypeIds =
+        input.direction === "outgoing"
+          ? reached(input.state)
+          : [
+              ...input.result.objectTypeIds,
+              ...(input.sourceObjectTypeId ? [input.sourceObjectTypeId] : []),
+            ]
+
+      const link = sourceTypeIds
+        .map((objectTypeId) => clearance.unreadableLink(objectTypeId, input.linkId))
+        .find((unreadable) => unreadable !== undefined)
+
+      return {
+        state: state(input.result.objectTypeIds),
+        ...denied(link ?? unreadableTypeAmong(clearance, input.result.objectTypeIds)),
+      }
+    },
+    // A difference only returns objects of its first input.
+    set: (input) =>
+      input.op === "subtract"
+        ? (input.states[0] ?? empty)
+        : state([...new Set(input.states.flatMap(reached))]),
+    property: (input) => {
+      if (input.use === "project") return undefined
+
+      const objectTypeIds =
+        input.objectTypeId === undefined ? reached(input.state) : [input.objectTypeId]
+      for (const objectTypeId of objectTypeIds) {
+        const marking = clearance.missingMarking(objectTypeId, input.propertyId)
+        if (marking === undefined) continue
+        return new AuthorizationError(
+          `clearance:marking:${marking}`,
+          `[Sixb] Cannot ${PROPERTY_USE_VERBS[input.use]} '${objectTypeId}.${input.propertyId}' at '${input.path}': it requires clearance for marking '${marking}'.`
+        )
+      }
+
+      return undefined
+    },
+  }
+
+  return Object.freeze(admission)
+}
+
+function unreadableTypeAmong(
+  clearance: PropertyClearance,
+  objectTypeIds: readonly string[]
+): Unreadable | undefined {
+  for (const objectTypeId of objectTypeIds) {
+    const unreadable = clearance.unreadableType(objectTypeId)
+    if (unreadable) return unreadable
+  }
+  return undefined
+}
+
+function denied(unreadable: Unreadable | undefined): { readonly denial?: Error } {
+  return unreadable ? { denial: unreadableError(unreadable) } : {}
+}
+
+const PROPERTY_USE_VERBS: Readonly<Record<ObjectQueryPropertyUse, string>> = {
+  filter: "filter by",
+  text: "search",
+  vector: "run a vector search over",
+  sort: "sort by",
+  project: "project",
+  "expand.orderBy": "order expanded objects by",
+  facet: "facet by",
+}

package/src/objects/query/current-user.ts

@@ -0,0 +1,76 @@
+import { isCurrentUser, type UserRef } from "../../ontology/user-ref"
+import type { ObjectQuery, ObjectQueryPredicate } from "./ir"
+
+/**
+ * Replace every `currentUser()` of a validated query with the reader's user reference.
+ *
+ * Validation admits the placeholder only where a predicate compares user references, so storage
+ * never receives it. Without a user, as for a service account, a schedule, or a share, `eq`, `in`
+ * and `contains` become a constant that matches nothing, and `neq` one that matches every row: it
+ * stays the complement of `eq`.
+ *
+ * The bound query is valid again and holds no placeholder: the executor validates parts of it
+ * once more, and binding it twice changes nothing.
+ */
+export function bindCurrentUser(query: ObjectQuery, user: UserRef | undefined): ObjectQuery {
+  switch (query.kind) {
+    case "start":
+    case "refs":
+      return query
+    case "filter":
+      return {
+        ...query,
+        input: bindCurrentUser(query.input, user),
+        predicate: bindCurrentUserPredicate(query.predicate, user),
+      }
+    case "set":
+      return { ...query, inputs: query.inputs.map((input) => bindCurrentUser(input, user)) }
+    default:
+      return { ...query, input: bindCurrentUser(query.input, user) }
+  }
+}
+
+/** Replace every `currentUser()` of a validated predicate, with the rules of {@link bindCurrentUser}. */
+export function bindCurrentUserPredicate(
+  predicate: ObjectQueryPredicate,
+  user: UserRef | undefined
+): ObjectQueryPredicate {
+  switch (predicate.op) {
+    case "and":
+    case "or":
+      return {
+        ...predicate,
+        items: predicate.items.map((item) => bindCurrentUserPredicate(item, user)),
+      }
+    case "not":
+      return { ...predicate, item: bindCurrentUserPredicate(predicate.item, user) }
+    case "exists":
+    case "constant":
+      return predicate
+    case "in": {
+      if (!predicate.values.some(isCurrentUser)) return predicate
+
+      const values = predicate.values.flatMap((value) =>
+        isCurrentUser(value) ? (user ? [user] : []) : [value]
+      )
+      return values.length > 0 ? { ...predicate, values } : NO_ROW
+    }
+    case "contains": {
+      if (!isCurrentUser(predicate.value)) return predicate
+      if (user) return { ...predicate, value: user }
+
+      return NO_ROW
+    }
+    default: {
+      if (!isCurrentUser(predicate.value)) return predicate
+      if (user) return { ...predicate, value: user }
+
+      return predicate.op === "neq" ? EVERY_ROW : NO_ROW
+    }
+  }
+}
+
+// A constant rather than a comparison with a reserved user id: auth strategies choose user ids, so
+// any id could one day name a real user.
+const NO_ROW: ObjectQueryPredicate = Object.freeze({ op: "constant", value: false })
+const EVERY_ROW: ObjectQueryPredicate = Object.freeze({ op: "constant", value: true })