@sixb/core 0.1.21 → 0.1.22

package/src/artifacts/publish/publish.ts

@@ -9,11 +9,13 @@ import type {
   ArtifactVersionRecord,
   PublishedArtifactVersion,
 } from "../../storage/artifacts/types"
+import { type ArtifactAccess, assertUpdatable } from "../access"
 import { ArtifactRequestError } from "../errors"
 import { createArtifactId } from "../ids"
 import type { ArtifactKind } from "../kinds"
 import { ARTIFACT_LIMITS } from "../limits"
 import type { ArtifactOutline } from "../outline"
+import type { CheckedArtifactQuery } from "../queries"
 import { ARTIFACT_THEME_FILE, parseArtifactTheme } from "../theme"
 import type { ArtifactWarning } from "../warnings"
 import {
@@ -22,9 +24,17 @@ import {
   invalidArtifact,
   readArtifactText,
 } from "./files"
-import { brokenDependents, type FoundReference, resolveReferences } from "./references"
+import { type ArtifactQueryChecker, checkArtifactQueries } from "./queries"
+import {
+  brokenDependents,
+  type FoundReference,
+  ownArtifacts,
+  resolveReferences,
+} from "./references"
+import { validateCanvas } from "./validate/canvas"
 import { validateDocument } from "./validate/document"
 import { validateFileArtifact } from "./validate/file"
+import { validatePage } from "./validate/page"
 import { validateSheet } from "./validate/sheet"
 import { validateSlides } from "./validate/slides"
 
@@ -40,11 +50,32 @@ export interface PublishArtifactInput {
   readonly kind: ArtifactKind
   readonly title: string
   readonly files: readonly ArtifactFile[]
-  /** Publishes the version, and owns the artifact when this creates it. */
+  /** Publishes the version, and owns the artifact when this creates it unless `owner` says. */
   readonly author: Principal
+  /** Owns the artifact when this creates it: a conversation's owner, for an Agent turn in it. */
+  readonly owner?: Principal
+  /**
+   * Whether an address in the version may name this artifact: one the author can read. Defaults to
+   * the author's own artifacts.
+   */
+  readonly readable?: (artifact: ArtifactRecord) => Promise<boolean>
+  /**
+   * Checks each of the version's queries as the author, so none reads what they cannot. Without
+   * it, a version that holds a query is refused.
+   */
+  readonly checkQuery?: ArtifactQueryChecker
   readonly origin?: ArtifactOrigin
+  /** The version this one was made from: publishing fails with `artifact_moved` past it. */
+  readonly baseVersion?: number
 }
 
+/**
+ * What the author may do with the artifact a version is published to, as the access rule's
+ * `publishAccess` answers it from where the version is stored: a transaction's storage, for a
+ * caller that stores in one. Storing refuses `none` with `not_shared` and `read` with `read_only`.
+ */
+export type PublishAccess = (artifact: ArtifactRecord) => Promise<ArtifactAccess>
+
 export interface PublishedArtifact {
   readonly artifact: ArtifactRecord
   readonly version: ArtifactVersionRecord
@@ -56,9 +87,14 @@ const CREATE_ATTEMPTS = 3
 /** A version checked against its kind and with its addresses resolved, ready to store. */
 export interface PreparedArtifactVersion {
   readonly artifactId?: string
+  readonly baseVersion?: number
   readonly kind: ArtifactKind
-  readonly author: Principal
+  /** Owns the artifact when this version creates it. */
+  readonly owner: Principal
+  readonly readable: (artifact: ArtifactRecord) => Promise<boolean>
   readonly version: ArtifactVersionInput
+  /** What its kind's check found worth fixing in a version it accepts. */
+  readonly warnings: readonly ArtifactWarning[]
 }
 
 /**
@@ -67,17 +103,19 @@ export interface PreparedArtifactVersion {
  */
 export async function publishArtifact(
   context: PublishArtifactContext,
-  input: PublishArtifactInput
+  input: PublishArtifactInput,
+  access: PublishAccess
 ): Promise<PublishedArtifact> {
   const prepared = await prepareArtifactVersion(context, input)
-  const stored = await storeArtifactVersion(context, prepared)
+  const stored = await storeArtifactVersion(context, prepared, access)
   return { ...stored, warnings: await artifactVersionWarnings(context, prepared, stored) }
 }
 
 /**
- * Everything publishing checks before it stores: the title, the files, the theme, the kind's own
- * format, and every address, resolved against what the author can read. It reads the files back
- * and parses them, so a caller that stores inside a transaction prepares outside it.
+ * Everything publishing checks before it stores: the title, the files, the theme, every query, run
+ * once as the author, the kind's own format, and every address, resolved against what the author
+ * can read. It reads the files back and parses them, so a caller that stores inside a
+ * transaction prepares outside it.
  */
 export async function prepareArtifactVersion(
   context: PublishArtifactContext,
@@ -86,15 +124,29 @@ export async function prepareArtifactVersion(
   const title = checkTitle(input.title)
   await checkArtifactFiles(context.blobStorage, input.files)
   if (input.kind !== "file") await checkTheme(context.blobStorage, input.files)
-  const validated = await validateKind(context.blobStorage, input.kind, input.files)
+
+  // The queries first: a live sheet's columns are checked against what its query returns.
+  const queries = await checkArtifactQueries(
+    context.blobStorage,
+    input.kind,
+    input.files,
+    input.checkQuery
+  )
+  const validated = await validateKind(context.blobStorage, input.kind, input.files, queries)
+
+  const readable = input.readable ?? ownArtifacts(input.author)
   const references = await resolveReferences(
-    referenceContext(context, input),
+    referenceContext(context, { readable, artifactId: input.artifactId }),
     validated.references ?? []
   )
+
   return {
     ...(input.artifactId ? { artifactId: input.artifactId } : {}),
+    ...(input.baseVersion === undefined ? {} : { baseVersion: input.baseVersion }),
     kind: input.kind,
-    author: input.author,
+    owner: input.owner ?? input.author,
+    readable,
+    warnings: validated.warnings ?? [],
     version: {
       title,
       entry: validated.entry,
@@ -108,50 +160,68 @@ export async function prepareArtifactVersion(
   }
 }
 
-/** Stores a prepared version: the next one of its artifact, or the first of a new one. */
+/**
+ * Stores a prepared version: the next one of its artifact, or the first of a new one. The next
+ * version is refused unless `access` says its author may update the artifact: a caller that stores
+ * inside a transaction answers it from there, so the check and the write see the same artifact.
+ */
 export async function storeArtifactVersion(
   context: PublishArtifactContext,
-  prepared: PreparedArtifactVersion
+  prepared: PreparedArtifactVersion,
+  access: PublishAccess
 ): Promise<PublishedArtifactVersion> {
-  return prepared.artifactId
-    ? publishVersion(context, prepared.artifactId, prepared.kind, prepared.version)
-    : createArtifact(context, prepared.kind, prepared.author, prepared.version)
+  const { artifactId } = prepared
+  if (!artifactId) {
+    return createArtifact(context, prepared.kind, prepared.owner, prepared.version)
+  }
+
+  const artifact = await context.storage.get({ projectId: context.projectId, id: artifactId })
+  if (!artifact) throw notFound(artifactId)
+  assertUpdatable(artifactId, await access(artifact))
+
+  return publishVersion(context, artifactId, prepared)
 }
 
 /**
- * What a stored version breaks in other artifacts that show it. A first version breaks nothing:
- * no other artifact could name it yet. The version is stored by now, so a failed check only loses
- * the warnings.
+ * What is worth fixing in a stored version: what its kind's check found, then what it breaks in
+ * other artifacts that show it. A first version breaks nothing: no other artifact could name it
+ * yet. The version is stored by now, so a failed check only loses those warnings.
  */
 export async function artifactVersionWarnings(
   context: PublishArtifactContext,
   prepared: PreparedArtifactVersion,
   stored: PublishedArtifactVersion
 ): Promise<readonly ArtifactWarning[]> {
-  if (!prepared.artifactId) return []
+  if (!prepared.artifactId) return prepared.warnings
   try {
-    return await brokenDependents(
-      referenceContext(context, prepared),
-      stored.artifact,
-      stored.version
-    )
+    return [
+      ...prepared.warnings,
+      ...(await brokenDependents(
+        referenceContext(context, prepared),
+        stored.artifact,
+        stored.version
+      )),
+    ]
   } catch (error) {
     console.warn(
       `[Sixb] Could not check which artifacts version ${stored.version.version} of '${stored.artifact.id}' breaks:`,
       error
     )
-    return []
+    return prepared.warnings
   }
 }
 
 function referenceContext(
   context: PublishArtifactContext,
-  input: { readonly author: Principal; readonly artifactId?: string }
+  input: {
+    readonly readable: (artifact: ArtifactRecord) => Promise<boolean>
+    readonly artifactId?: string
+  }
 ) {
   return {
     projectId: context.projectId,
     storage: context.storage,
-    author: input.author,
+    readable: input.readable,
     ...(input.artifactId ? { artifactId: input.artifactId } : {}),
   }
 }
@@ -159,11 +229,13 @@ function referenceContext(
 async function validateKind(
   blobStorage: ArtifactBlobStorage,
   kind: ArtifactKind,
-  files: readonly ArtifactFile[]
+  files: readonly ArtifactFile[],
+  queries: ReadonlyMap<string, CheckedArtifactQuery>
 ): Promise<{
   readonly entry: string
   readonly outline: ArtifactOutline
   readonly references?: readonly FoundReference[]
+  readonly warnings?: readonly ArtifactWarning[]
 }> {
   switch (kind) {
     case "document":
@@ -171,9 +243,13 @@ async function validateKind(
     case "file":
       return validateFileArtifact(files)
     case "sheet":
-      return validateSheet(blobStorage, files)
+      return validateSheet(blobStorage, files, queries)
     case "slides":
       return validateSlides(blobStorage, files)
+    case "page":
+      return validatePage(blobStorage, files)
+    case "canvas":
+      return validateCanvas(blobStorage, files)
     default:
       // A caller past the API's schema, such as a script on the SDK, can name any kind.
       throw invalidArtifact(`'${kind satisfies never}' is not a kind of artifact.`)
@@ -206,15 +282,15 @@ function checkTitle(value: string): string {
 async function publishVersion(
   context: PublishArtifactContext,
   artifactId: string,
-  kind: ArtifactKind,
-  version: ArtifactVersionInput
+  prepared: PreparedArtifactVersion
 ): Promise<PublishedArtifactVersion> {
   try {
     return await context.storage.publish({
       projectId: context.projectId,
       artifactId,
-      kind,
-      version,
+      kind: prepared.kind,
+      version: prepared.version,
+      ...(prepared.baseVersion === undefined ? {} : { baseVersion: prepared.baseVersion }),
     })
   } catch (error) {
     if (error instanceof ArtifactStorageError && error.code === "artifact_not_found") {
@@ -223,10 +299,20 @@ async function publishVersion(
     if (error instanceof ArtifactStorageError && error.code === "artifact_kind_mismatch") {
       throw new ArtifactRequestError("artifact_kind_mismatch", error.message)
     }
+    if (error instanceof ArtifactStorageError && error.code === "artifact_moved") {
+      throw new ArtifactRequestError("artifact_moved", error.message, error.latest)
+    }
     throw error
   }
 }
 
+function notFound(artifactId: string): ArtifactRequestError {
+  return new ArtifactRequestError(
+    "artifact_not_found",
+    `[Sixb] Artifact '${artifactId}' was not found.`
+  )
+}
+
 async function createArtifact(
   context: PublishArtifactContext,
   kind: ArtifactKind,

package/src/artifacts/publish/queries.ts

@@ -0,0 +1,336 @@
+import { isRuntimeAllowed } from "../../authorization"
+import { AuthorizationError } from "../../authorization/errors"
+import { readerClearance } from "../../execution/authorized-object-reader"
+import type { PropertyClearance } from "../../objects/property-clearance"
+import {
+  ObjectQueryExecutionError,
+  ObjectQueryPlanningError,
+  ObjectQueryValidationError,
+} from "../../objects/query/errors"
+import type { ObjectExpansion, ObjectQuery } from "../../objects/query/ir"
+import { normalizeObjectQuery } from "../../objects/query/normalize"
+import {
+  type ObjectQuerySemanticAdmission,
+  validateObjectQueryWithAdmission,
+} from "../../objects/query/validate"
+import type { OntologyRegistry } from "../../ontology"
+import type { SixbRuntimeContext } from "../../runtime/types"
+import type { ArtifactFile } from "../../storage/artifacts/types"
+import type { ArtifactKind } from "../kinds"
+import { ARTIFACT_LIMITS } from "../limits"
+import {
+  ARTIFACT_QUERIES_DIRECTORY,
+  ARTIFACT_QUERY_KINDS,
+  type ArtifactQuery,
+  artifactQueryName,
+  type CheckedArtifactQuery,
+  parseArtifactQuery,
+} from "../queries"
+import { describeArtifactQuery } from "../run-query"
+import { type ArtifactBlobStorage, invalidArtifact, readArtifactText } from "./files"
+
+/**
+ * Admits a query as the version's author: it throws what running it as them would throw, and
+ * refuses one that would return what they cannot read; it returns what the query returns and what
+ * its rows hold as they see them. A version is refused when its author could not run one of its
+ * queries, so a query never reads what whoever wrote it cannot. Each reader still runs it with
+ * their own rights.
+ */
+export type ArtifactQueryChecker = (query: ArtifactQuery) => Promise<CheckedArtifactQuery>
+
+/**
+ * The checker for the runtime's caller. Running the query once, as cheaply as its kind allows,
+ * is the check: validation against the ontology, `can.view` on every type it reads, clearance for
+ * every marked property it filters, sorts or facets on, and the caller's share scope all apply
+ * there, as they do when it is read.
+ *
+ * What the rows carry is checked after: a read leaves out a marked property its reader is not
+ * cleared for, and the member profiles of a reader who may not view them, so running the query
+ * admits one that returns them. A reader's rows reach the page's code, which its author wrote, so
+ * the query may return only what the author can read. Facets return counts, never a property.
+ */
+export function createArtifactQueryChecker(
+  runtime: Pick<
+    SixbRuntimeContext,
+    "objectReader" | "ontology" | "projectId" | "runtimeAuthorization" | "authorization"
+  >
+): ArtifactQueryChecker {
+  return async (query) => {
+    const shape = describeArtifactQuery(runtime, query)
+
+    if (query.kind === "facets") {
+      await runtime.objectReader.facet({ query: query.query, facets: query.facets })
+      return { kind: query.kind, ...shape }
+    }
+
+    await runtime.objectReader.exists({ query: query.query })
+
+    const clearance = await readerClearance(runtime.objectReader)
+    if (clearance) assertReturnsReadable(query.query, runtime.ontology, clearance)
+
+    // The reader attaches profiles only for an authority that may view the directory.
+    if (!isRuntimeAllowed(runtime, { kind: "users.view" })) assertExpandsNoUsers(query.query)
+
+    return { kind: query.kind, ...shape }
+  }
+}
+
+/** A query that would return what its author cannot read, at `at` in the query. */
+class UnreadableReturnError extends AuthorizationError {
+  constructor(
+    grantKey: string,
+    readonly at: string,
+    message: string
+  ) {
+    super(grantKey, message)
+  }
+}
+
+/**
+ * Refuses a query whose rows would carry a property its author cannot read: one of the result's,
+ * those the outermost `project` lists or every one without it, or one of an object an `expand`
+ * attaches, which no projection narrows.
+ *
+ * A `project` counts only under nothing but expansions, sorts and limits. Under a filter, a
+ * traversal or a set operand it may not shape the rows, so the query then returns every property.
+ */
+function assertReturnsReadable(
+  query: ObjectQuery,
+  ontology: OntologyRegistry,
+  clearance: PropertyClearance
+): void {
+  const { normalized, resultObjectTypeIds, expansions } = returnedShape(query, ontology)
+  const project = outermostProject(normalized)
+
+  for (const objectTypeId of resultObjectTypeIds) {
+    const propertyIds = project?.properties ?? propertiesOf(ontology, objectTypeId)
+    const unreadable = firstUnreadable(clearance, objectTypeId, propertyIds)
+    if (!unreadable) continue
+
+    const returns = `returns '${unreadable.propertyId}' on '${objectTypeId}', which you are not cleared to read`
+    throw project
+      ? new UnreadableReturnError(
+          `clearance:marking:${unreadable.marking}`,
+          `${project.at}.properties[${unreadable.index}]`,
+          `[Sixb] ${returns}: list only the properties you can read.`
+        )
+      : new UnreadableReturnError(
+          `clearance:marking:${unreadable.marking}`,
+          "$",
+          `[Sixb] ${returns}: add a "project" node that lists only the properties you can read.`
+        )
+  }
+
+  for (const expansion of expansions) {
+    for (const objectTypeId of expansion.objectTypeIds) {
+      const unreadable = firstUnreadable(
+        clearance,
+        objectTypeId,
+        propertiesOf(ontology, objectTypeId)
+      )
+      if (!unreadable) continue
+
+      throw new UnreadableReturnError(
+        `clearance:marking:${unreadable.marking}`,
+        expansion.at,
+        `[Sixb] expands '${expansion.linkId}' to '${objectTypeId}', whose '${unreadable.propertyId}' you are not cleared to read: an expansion returns every property, so leave it out, or read '${objectTypeId}' in a query of its own with a "project" node.`
+      )
+    }
+  }
+}
+
+/**
+ * Refuses a query that expands member profiles, for an author who may not view them. Only the
+ * outermost expand names them, at its rows or under its expansions, once normalized.
+ */
+function assertExpandsNoUsers(query: ObjectQuery): void {
+  const normalized = normalizeObjectQuery(query)
+  if (normalized.kind !== "expand") return
+
+  const expanded = firstUserExpansion(normalized.users, normalized.expansions, "$")
+  if (!expanded) return
+
+  throw new UnreadableReturnError(
+    "view:users",
+    expanded.at,
+    `[Sixb] returns the member profiles '${expanded.propertyId}' refers to, which you are not allowed to view: leave '${expanded.propertyId}' out of "users".`
+  )
+}
+
+function firstUserExpansion(
+  users: readonly string[] | undefined,
+  expansions: readonly ObjectExpansion[],
+  at: string
+): { readonly propertyId: string; readonly at: string } | undefined {
+  const [propertyId] = users ?? []
+  if (propertyId !== undefined) return { propertyId, at: `${at}.users[0]` }
+
+  for (const [index, expansion] of expansions.entries()) {
+    const path = at === "$" ? `$.expansions[${index}]` : `${at}.expand[${index}]`
+    const found = firstUserExpansion(expansion.users, expansion.expand ?? [], path)
+    if (found) return found
+  }
+
+  return undefined
+}
+
+function propertiesOf(ontology: OntologyRegistry, objectTypeId: string): readonly string[] {
+  return ontology.resolveObjectType(objectTypeId).properties.map((property) => property.id)
+}
+
+function firstUnreadable(
+  clearance: PropertyClearance,
+  objectTypeId: string,
+  propertyIds: readonly string[]
+): { readonly propertyId: string; readonly index: number; readonly marking: string } | undefined {
+  for (const [index, propertyId] of propertyIds.entries()) {
+    const marking = clearance.missingMarking(objectTypeId, propertyId)
+    if (marking !== undefined) return { propertyId, index, marking }
+  }
+
+  return undefined
+}
+
+/**
+ * The query as it runs, the object types it returns, and those each expansion attaches, at any
+ * depth. Validation resolves an expansion's targets, so a recording admission reads them there:
+ * a set operand's expansions are among them too.
+ */
+function returnedShape(query: ObjectQuery, ontology: OntologyRegistry) {
+  const expansions: { readonly at: string; readonly linkId: string; objectTypeIds: string[] }[] = []
+
+  const state = Object.freeze({})
+  const recorder: ObjectQuerySemanticAdmission = {
+    empty: () => state,
+    source: () => ({ state }),
+    property: () => undefined,
+    edge: (input) => {
+      if (input.use === "expand") {
+        expansions.push({
+          at: input.path,
+          linkId: input.linkId,
+          objectTypeIds: [...input.result.objectTypeIds],
+        })
+      }
+      return { state }
+    },
+    set: () => state,
+  }
+
+  const validated = validateObjectQueryWithAdmission(query, { ontology }, recorder)
+  return {
+    normalized: validated.query,
+    resultObjectTypeIds: validated.result.objectTypeIds,
+    expansions,
+  }
+}
+
+/** The `project` that shapes the rows, through the nodes that keep them as they are. */
+function outermostProject(
+  query: ObjectQuery,
+  at = "$"
+): { readonly properties: readonly string[]; readonly at: string } | undefined {
+  switch (query.kind) {
+    case "project":
+      return query.properties ? { properties: query.properties, at } : undefined
+    case "expand":
+    case "limit":
+    case "sort":
+      return outermostProject(query.input, `${at}.input`)
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Checks the `queries/` files of a version: their names and number, their shape, then each one as
+ * its author through `checker`, and returns what each check learned by query name, for the kind's
+ * own check. Fails closed: a version that holds a query is refused without one. A file artifact is
+ * delivered as it is, so its one file is never read as a query.
+ */
+export async function checkArtifactQueries(
+  blobStorage: ArtifactBlobStorage,
+  kind: ArtifactKind,
+  files: readonly ArtifactFile[],
+  checker: ArtifactQueryChecker | undefined
+): Promise<ReadonlyMap<string, CheckedArtifactQuery>> {
+  const checked = new Map<string, CheckedArtifactQuery>()
+  if (kind === "file") return checked
+
+  const queries = files.filter((file) => file.path.startsWith(ARTIFACT_QUERIES_DIRECTORY))
+  const [first] = queries
+  if (!first) return checked
+
+  if (!ARTIFACT_QUERY_KINDS.includes(kind)) {
+    throw invalidArtifact(
+      `'${first.path}': a ${kind} runs no query. A document shows a live sheet instead.`
+    )
+  }
+
+  if (queries.length > ARTIFACT_LIMITS.maxQueries) {
+    throw invalidArtifact(
+      `A version holds at most ${ARTIFACT_LIMITS.maxQueries} queries; this one has ${queries.length}.`
+    )
+  }
+
+  if (!checker) {
+    throw invalidArtifact(
+      `'${first.path}' is a query, and this publish has no way to check it as its author.`
+    )
+  }
+
+  // One at a time, so the same version is always refused for the same query.
+  for (const file of queries) {
+    const name = artifactQueryName(file.path)
+    if (!name) {
+      throw invalidArtifact(
+        `'${file.path}' is not a query: name it queries/<name>.json, with lowercase letters, digits and hyphens, at most 64 characters.`
+      )
+    }
+
+    const text = await readArtifactText(blobStorage, file, ARTIFACT_LIMITS.maxQueryBytes)
+    const parsed = parseArtifactQuery(file.path, text)
+    if ("error" in parsed) throw invalidArtifact(parsed.error)
+
+    try {
+      checked.set(name, await checker(parsed.query))
+    } catch (error) {
+      throw refusal(file.path, parsed, error)
+    }
+  }
+
+  return checked
+}
+
+/**
+ * Why the author cannot run the query, naming the file and, for a problem in the query, where it
+ * is in the file. A query's own paths start at the query, which a request holds under `query`;
+ * a facet's paths are the file's already.
+ */
+function refusal(
+  path: string,
+  parsed: { readonly query: ArtifactQuery; readonly at: "$" | "$.query" },
+  error: unknown
+): unknown {
+  const inFile = (issuePath: string) =>
+    parsed.query.kind === "facets" && issuePath.startsWith("$.facets")
+      ? issuePath
+      : `${parsed.at}${issuePath.slice(1)}`
+
+  if (error instanceof UnreadableReturnError) {
+    return invalidArtifact(
+      `${path}: ${inFile(error.at)}: ${error.message.replace(/^\[Sixb\]\s*/, "")}`
+    )
+  }
+
+  if (error instanceof ObjectQueryValidationError || error instanceof ObjectQueryPlanningError) {
+    const issues = error.issues.map((issue) => `${inFile(issue.path)}: ${issue.message}`)
+    return invalidArtifact(`${path}: ${issues.join("; ")}`)
+  }
+
+  if (error instanceof AuthorizationError || error instanceof ObjectQueryExecutionError) {
+    return invalidArtifact(`${path}: ${error.message.replace(/^\[Sixb\]\s*/, "")}`)
+  }
+
+  return error
+}