@sixb/core 0.1.19 → 0.1.21

package/src/sandboxes/configuration.ts

@@ -112,12 +112,7 @@ export function createSandboxDefinition<TParams extends ParamsConfig>(
     }
   }
   const params = structuredClone(config.params ?? {}) as ParamsConfig
-  const environment = captureEnvironment({
-    ...(config.source === undefined ? {} : { source: config.source }),
-    ...(config.setup === undefined ? {} : { setup: config.setup }),
-    ...(config.env === undefined ? {} : { env: config.env }),
-    ...(config.network === undefined ? {} : { network: config.network }),
-  })
+  const environment = staticSandboxRecipe(config)
   // Capture the function too: later mutation of application config must not change this host.
   // Erase inference only after capturing its schema; every invocation validates and coerces below.
   const resolve = config.resolve as SandboxConfig["resolve"]
@@ -144,6 +139,51 @@ export function createSandboxDefinition<TParams extends ParamsConfig>(
   })
 }
 
+/** What the source access rule reads: the provider's capability and one recipe's source. */
+interface SandboxCredentialRuleInput {
+  readonly supportsRequestCredentials?: boolean
+  /** The factory's source auth; it applies to every recipe the factory resolves. */
+  readonly auth?: unknown
+  readonly source?: SandboxSource
+}
+
+/**
+ * Why a recipe cannot get the source access it declares, as a whole message, or undefined.
+ *
+ * Write access needs source auth. Source auth needs a provider that injects request credentials
+ * outside the sandbox, even for a recipe without a source: auth is the factory's, so startup and
+ * every run give the same answer. Source auth without a source is otherwise fine; that recipe
+ * does not use it.
+ */
+export function sandboxCredentialIssue(input: SandboxCredentialRuleInput): string | undefined {
+  const { supportsRequestCredentials, auth, source } = input
+
+  if (source?.access === "write" && auth === undefined) {
+    return 'Sandbox write access needs source auth: add auth to the sandbox factory or use access "read".'
+  }
+  if (auth !== undefined && !supportsRequestCredentials) {
+    return "Sandbox source auth needs a provider that injects request credentials outside the sandbox: use @sixb/sandboxes-vercel, or remove auth."
+  }
+
+  return undefined
+}
+
+/** The static part of a recipe, captured: all a run without thread params can apply. */
+export function staticSandboxRecipe(configuration: {
+  readonly source?: unknown
+  readonly setup?: unknown
+  readonly env?: unknown
+  readonly network?: unknown
+}): SandboxEnvironment {
+  const { source, setup, env, network } = configuration
+  return captureEnvironment({
+    ...(source === undefined ? {} : { source }),
+    ...(setup === undefined ? {} : { setup }),
+    ...(env === undefined ? {} : { env }),
+    ...(network === undefined ? {} : { network }),
+  })
+}
+
 /** Capture declarative data only; never retain caller-owned objects or include values in errors. */
 export function captureEnvironment(value: unknown): SandboxEnvironment {
   if (
@@ -177,6 +217,10 @@ function validateSource(source: unknown): void {
   if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
     fail("source URL: expected credential-free HTTPS")
   }
+
+  // The repository host joins the run's network, where "*" would open every matching domain.
+  if (url.hostname.includes("*")) fail("source URL: wildcard hosts are not allowed")
+
   if (
     source.revision !== undefined &&
     (typeof source.revision !== "string" ||
@@ -202,7 +246,13 @@ function validateSetup(setup: unknown): void {
   }
 }
 
-function validateEnv(env: unknown): void {
+/** Snapshot guest-readable variables under the recipe `env` rules; never include values in errors. */
+export function captureSandboxEnv(value: unknown): Readonly<Record<string, string>> {
+  validateEnv(value)
+  return structuredClone(value)
+}
+
+function validateEnv(env: unknown): asserts env is Record<string, string> {
   if (
     !isPlainRecord(env) ||
     Object.entries(env).some(
@@ -248,6 +298,10 @@ function validateNetworkTarget(target: unknown): void {
   if (!["http:", "https:"].includes(url.protocol) || url.origin !== target.origin) {
     fail("network origin")
   }
+
+  // Providers such as Vercel read "*" in a domain as a wildcard: one target would open every
+  // matching domain. List each domain instead.
+  if (url.hostname.includes("*")) fail("network origin: wildcard hosts are not allowed")
 }
 
 function parseUrl(value: string, field: string): URL {

package/src/sandboxes/index.ts

@@ -32,6 +32,7 @@ export type {
   SandboxNetworkPolicy,
   SandboxNetworkTarget,
   SandboxRequestCredential,
+  SandboxRequestMethod,
   SandboxSessionOptions,
   SandboxStatus,
 } from "./sandbox"

package/src/sandboxes/sandbox.ts

@@ -78,13 +78,33 @@ export interface SandboxNetworkTarget {
   readonly origin: string
 }
 
-/** Host-only credentials injected outside the guest into one exact HTTPS request target.
- * This selects authenticated requests, not the sandbox's general egress allowlist.
+/** HTTP methods a request credential can be injected into. HEAD and OPTIONS never are. */
+export type SandboxRequestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+
+/**
+ * Host-only credentials injected outside the guest into matching HTTPS requests.
+ *
+ * A credential selects which requests receive its Authorization header. It does not decide what
+ * the guest can reach, which is the network policy, nor which resources the token can act on:
+ * the token's own permissions are the boundary, so issue it with the narrowest scope that works.
+ *
+ * Providers apply the same rules so that a credential means the same thing everywhere:
+ * - `origin` is one `https://` domain: no port, path, user info, IP address, loopback host or
+ *   `*` wildcard.
+ * - A path is matched case-sensitively against the raw request path. It starts with a single
+ *   "/" and is printable ASCII without spaces, control characters, "?", "#", "%", "\\", or "."
+ *   and ".." segments. A prefix also ends with "/", so it stops at a segment boundary.
+ * - Two credentials must not match the same request: one credential per request, so providers
+ *   reject the overlap instead of picking one.
+ * - Only Authorization can be set, and the provider forces the request's Host header to
+ *   `origin`'s domain.
  */
 export interface SandboxRequestCredential {
   readonly origin: string
-  readonly path: string
-  readonly method: "GET" | "POST"
+  /** One exact path, or every path under `prefix`. */
+  readonly path: string | { readonly prefix: string }
+  /** One method, or a non-empty list of distinct methods. */
+  readonly method: SandboxRequestMethod | readonly SandboxRequestMethod[]
   readonly headers: { readonly Authorization: string }
 }
 
@@ -123,6 +143,8 @@ export interface Sandbox {
   /** Optional secure injection capability. Replaces all credentials on this session only.
    * An empty list removes injection. Secrets must never enter guest files, env or snapshots.
    * Must not resume a stopped session or change defaults inherited by future sessions.
+   * Renewal, ephemeral or persistent, targets the handle's session; after stop() it rejects.
+   * A thrown error is reported to onError: it and its causes must never contain a credential.
    */
   readonly setRequestCredentials?: (
     credentials: readonly SandboxRequestCredential[]
@@ -166,7 +188,7 @@ export interface Sandbox {
  * Credentials and current authority must be supplied again, never inferred from saved files.
  */
 export interface SandboxFactory<in out TParams extends ParamsConfig = ParamsConfig> {
-  /** Supports initial and renewable host-only credentials on named persistent sessions. */
+  /** Supports initial and renewable host-only credentials on ephemeral and named sessions. */
   readonly supportsRequestCredentials?: boolean
   /** Common host-side environment recipe. Never a discovered Agent definition. */
   readonly configuration?: SandboxConfig<TParams>

package/src/security/applied-markings-contribution.ts

@@ -0,0 +1,277 @@
+import type { ProjectionEventOrigin } from "../events/envelope"
+import type { DatasetVersion } from "../lake-storage/types"
+import type { OntologyDefinitionCatalog } from "../ontology/registry"
+import type { PipelineDefinition } from "../pipelines/types"
+import type { LinkProjectionDefinition, ObjectProjectionDefinition } from "../projections/types"
+import type { ActiveOntologySource } from "../storage/ontology"
+import { type AppliedContribution, NO_CONTRIBUTION } from "./applied-markings-snapshot"
+import type { VersionClassification } from "./dataset-version-markings"
+import { registeredSteps } from "./marking-propagation"
+import { type ProjectionKeyTarget, projectionSurplus } from "./projection-markings"
+
+export type SourceProjection = ObjectProjectionDefinition | LinkProjectionDefinition
+
+/** What reading a projection's applied version from the lake gave. */
+export type AppliedVersionRead =
+  | {
+      readonly kind: "read"
+      readonly version: DatasetVersion
+      readonly classification: VersionClassification
+    }
+  | { readonly kind: "missing" }
+  | { readonly kind: "failed"; readonly error: unknown }
+
+export interface AppliedContributionContext {
+  readonly ontology: Pick<OntologyDefinitionCatalog, "getObjectTypeById">
+  /** The revision of a projection's current definition. */
+  readonly revisionOf: (projectionId: string) => string
+  /** What a version that cannot be read may carry. */
+  readonly everyMarking: ReadonlySet<string>
+  /** The pipeline that writes a dataset in the current code, for messages. */
+  readonly pipelineOf: (datasetId: string) => string | undefined
+}
+
+/**
+ * What one projection's applied version adds to the code's markings, with the notice that explains
+ * it. It reads nothing: the caller reads and classifies the version.
+ *
+ * - A version that could not be read seals the projection's target with every marking.
+ * - Objects written by an earlier definition, which may have mapped any column, seal it with every
+ *   marking of the version.
+ * - Otherwise a property keeps the markings its column carries beyond its declaration, and a key
+ *   column that carries markings seals what it keys.
+ */
+export function appliedContribution(
+  projection: SourceProjection,
+  source: ActiveOntologySource,
+  read: AppliedVersionRead,
+  context: AppliedContributionContext
+): AppliedContribution {
+  const { datasetId, versionId } = source.datasetVersion
+  const subject = `version '${versionId}' of '${datasetId}'`
+  const target = projectionTarget(projection)
+  const hint = rerunHint(datasetId, read.kind === "read" ? read.version : undefined, context)
+  const every = [...context.everyMarking].sort()
+
+  if (read.kind === "failed") {
+    return sealed(projection.id, target, every, hint, {
+      reason: `the ${subject} it applied, which could not be read from the lake,`,
+      detail: `applied ${subject}, which could not be read from the lake: ${sentence(errorMessage(read.error))}`,
+    })
+  }
+
+  if (read.kind === "missing") {
+    return sealed(projection.id, target, every, hint, {
+      reason: `the ${subject} it applied, which the lake no longer has,`,
+      detail: `applied ${subject}, which the lake no longer has.`,
+    })
+  }
+
+  const { columns, conservative } = read.classification
+  const because =
+    conservative === undefined
+      ? ""
+      : ` The version was classified with every marking its sources could hold, because ${conservative}.`
+
+  if (
+    datasetId !== projection.datasetId ||
+    source.projectionRevision !== context.revisionOf(projection.id)
+  ) {
+    const markings = appliedVersionMarkings(read, context.everyMarking)
+    return sealed(projection.id, target, markings, hint, {
+      reason: `the ${subject} it applied under an earlier definition of the projection`,
+      detail: `applied ${subject} under an earlier definition of the projection, and that version carries ${markingList(markings)}.${because}`,
+    })
+  }
+
+  const markingsOf = (column: string) => [...(columns.get(column) ?? [])].sort()
+  const surplus = projectionSurplus(projection, context.ontology, markingsOf)
+  if (surplus.properties.length === 0 && surplus.keys.length === 0) return NO_CONTRIBUTION
+
+  const column = (name: string) => `'${datasetId}.${name}'`
+  const seals = surplus.keys.map((key) => ({
+    target: key.target,
+    seal: {
+      projectionId: projection.id,
+      markings: key.markings,
+      reason: `in the version '${versionId}' it applied, column ${column(key.column)}, which ${key.role},`,
+    },
+  }))
+
+  const details = [
+    ...surplus.keys.map(
+      (key) => `column ${column(key.column)} ${key.role} and carries ${markingList(key.markings)}`
+    ),
+    ...surplus.properties.map(
+      (property) =>
+        `property '${property.objectTypeId}.${property.propertyId}' is projected from column ${column(property.column)}, which carries ${markingList(property.markings)}`
+    ),
+  ]
+
+  const consequences: string[] = []
+  if (seals.length > 0) {
+    const markings = [...new Set(seals.flatMap(({ seal }) => seal.markings))].sort()
+    consequences.push(
+      `${describeTargets(seals.map(({ target }) => target))} cannot be read without clearance for ${markingList(markings)}`
+    )
+  }
+
+  if (surplus.properties.length > 0) {
+    const names = surplus.properties.map((p) => `'${p.objectTypeId}.${p.propertyId}'`)
+    const verb = surplus.properties.length === 1 ? "keeps" : "keep"
+    consequences.push(`${describeNames(names)} ${verb} these markings`)
+  }
+
+  return {
+    properties: surplus.properties.map(({ objectTypeId, propertyId, markings }) => ({
+      objectTypeId,
+      propertyId,
+      markings,
+    })),
+    seals,
+    notice: {
+      projectionId: projection.id,
+      sealed: seals.length > 0,
+      message: `[Sixb] Projection '${projection.id}' applied ${subject}, in which ${details.join("; ")}.${because} ${capitalize(consequences.join(", and "))} until the projection applies a version the code allows. ${hint}`,
+    },
+  }
+}
+
+/** Every marking the version carries in any column; every marking when it could not be read. */
+export function appliedVersionMarkings(
+  read: AppliedVersionRead,
+  everyMarking: ReadonlySet<string>
+): readonly string[] {
+  if (read.kind !== "read") return [...everyMarking].sort()
+
+  const { columns } = read.classification
+  return [...new Set([...columns.values()].flatMap((set) => [...set]))].sort()
+}
+
+/** An object event a projection emitted: the version its values came from, and its type. */
+export type EventOriginRef = Pick<
+  ProjectionEventOrigin,
+  "projectionId" | "datasetId" | "datasetVersionId"
+> & { readonly objectTypeId: string }
+
+/**
+ * The markings an object event's origin version carries on each property its projection maps.
+ * When the projection now maps another dataset or type, or the version cannot be read, every
+ * property but the primary one carries every marking it could, as objects written under an
+ * earlier definition do.
+ */
+export function eventOriginMarkings(
+  projection: ObjectProjectionDefinition,
+  origin: EventOriginRef,
+  read: AppliedVersionRead,
+  context: Pick<AppliedContributionContext, "ontology" | "everyMarking">
+): AppliedContribution["properties"] {
+  const { objectTypeId } = origin
+
+  if (
+    read.kind === "read" &&
+    projection.datasetId === origin.datasetId &&
+    projection.objectTypeId === objectTypeId
+  ) {
+    const { columns } = read.classification
+    return Object.entries(projection.properties).flatMap(([propertyId, column]) => {
+      const markings = [...(columns.get(column) ?? [])].sort()
+      return markings.length === 0 ? [] : [{ objectTypeId, propertyId, markings }]
+    })
+  }
+
+  const markings = appliedVersionMarkings(read, context.everyMarking)
+  if (markings.length === 0) return []
+
+  return (context.ontology.getObjectTypeById(objectTypeId)?.properties ?? [])
+    .filter((property) => !property.primary)
+    .map((property) => ({ objectTypeId, propertyId: property.id, markings }))
+}
+
+/** The pipeline that writes each dataset in the current code. */
+export function producingPipelines(
+  pipelines: readonly PipelineDefinition[]
+): (datasetId: string) => string | undefined {
+  const byDataset = new Map<string, string>()
+  for (const { pipelineId, step } of registeredSteps(pipelines)) {
+    if (!byDataset.has(step.output.id)) byDataset.set(step.output.id, pipelineId)
+  }
+
+  return (datasetId) => byDataset.get(datasetId)
+}
+
+/** Seal the projection's whole target: its object type, or its link. */
+function sealed(
+  projectionId: string,
+  target: ProjectionKeyTarget,
+  markings: readonly string[],
+  hint: string,
+  text: { readonly reason: string; readonly detail: string }
+): AppliedContribution {
+  if (markings.length === 0) return NO_CONTRIBUTION
+  return {
+    properties: [],
+    seals: [{ target, seal: { projectionId, markings, reason: text.reason } }],
+    notice: {
+      projectionId,
+      sealed: true,
+      message: `[Sixb] Projection '${projectionId}' ${text.detail} ${describeTargets([target])} cannot be read without clearance for ${markingList(markings)} until the projection applies a version the code allows. ${hint}`,
+    },
+  }
+}
+
+function projectionTarget(projection: SourceProjection): ProjectionKeyTarget {
+  return projection._tag === "ObjectProjectionDefinition"
+    ? { kind: "type", objectTypeId: projection.objectTypeId }
+    : {
+        kind: "link",
+        objectTypeId: projection.sourceObjectTypeId,
+        linkId: projection.linkId,
+        targetObjectTypeId: projection.targetObjectTypeId,
+      }
+}
+
+function rerunHint(
+  datasetId: string,
+  version: DatasetVersion | undefined,
+  context: AppliedContributionContext
+): string {
+  const pipelineId =
+    context.pipelineOf(datasetId) ??
+    (version?.producer?.kind === "pipeline" ? version.producer.id : undefined)
+  return pipelineId === undefined
+    ? `Write a new version of '${datasetId}' to replace it.`
+    : `Rerun pipeline '${pipelineId}' to replace it.`
+}
+
+function describeTargets(targets: readonly ProjectionKeyTarget[]): string {
+  return describeNames(
+    targets.map((target) =>
+      target.kind === "type"
+        ? `'${target.objectTypeId}'`
+        : `link '${target.objectTypeId}.${target.linkId}'`
+    )
+  )
+}
+
+function describeNames(names: readonly string[]): string {
+  const unique = [...new Set(names)]
+  const last = unique.pop() ?? ""
+  return unique.length === 0 ? last : `${unique.join(", ")} and ${last}`
+}
+
+function capitalize(text: string): string {
+  return text.charAt(0).toUpperCase() + text.slice(1)
+}
+
+export function sentence(text: string): string {
+  return text.endsWith(".") ? text : `${text}.`
+}
+
+function markingList(markings: readonly string[]): string {
+  return `[${markings.join(", ")}]`
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/security/applied-markings-host.ts

@@ -0,0 +1,41 @@
+import type { AppliedMarkings } from "./applied-markings"
+import { errorMessage } from "./applied-markings-contribution"
+
+const appliedMarkingsKey: unique symbol = Symbol("sixb.appliedMarkings")
+
+interface AppliedMarkingsOwner {
+  readonly [appliedMarkingsKey]?: AppliedMarkings
+}
+
+/** One snapshot per host, so every reader shares it and its resolved clearances. */
+export function registerAppliedMarkings(owner: object, markings: AppliedMarkings): void {
+  const registered = (owner as AppliedMarkingsOwner)[appliedMarkingsKey]
+  if (registered && registered !== markings) {
+    throw new Error("[Sixb] Applied markings are already registered for this owner.")
+  }
+
+  Object.defineProperty(owner, appliedMarkingsKey, {
+    configurable: false,
+    enumerable: false,
+    value: markings,
+    writable: false,
+  })
+}
+
+export function getAppliedMarkings(owner: object): AppliedMarkings {
+  const markings = (owner as AppliedMarkingsOwner)[appliedMarkingsKey]
+  if (markings) return markings
+  throw new Error("[Sixb] Applied markings are not registered for this runtime.")
+}
+
+/**
+ * Read the applied versions ahead of the first request that needs them. A failure is only
+ * reported here: that request reads them again, and fails closed if it cannot.
+ */
+export function warmAppliedMarkings(owner: object): void {
+  getAppliedMarkings(owner)
+    .current()
+    .catch((error: unknown) => {
+      console.warn(errorMessage(error))
+    })
+}