@sixb/core 0.0.1

package/src/authorization/grant-kinds.ts

@@ -0,0 +1,149 @@
+/**
+ * Grant kinds: the single source of truth for the (capability, target) space.
+ *
+ * Every grant collapses to one `GrantKind` discriminant — the same
+ * `capability:target` string the decision engine uses as a grant key (e.g.
+ * `view:object`, `run:sync`). Resolution, validation, enforcement, and the
+ * resolved `GrantIndex` all key off it, so adding a grant family is a single
+ * entry in `GRANT_KINDS` plus the compile errors that forces at every consumer.
+ */
+
+import type { GrantDefinition } from "../security/types"
+
+export type GrantKind =
+  | "access:application"
+  | "view:object"
+  | "view:dataset"
+  | "edit:object"
+  | "append:telemetry"
+  | "apply:action"
+  | "run:workflow"
+  | "run:sync"
+  | "run:pipeline"
+  | "run:agent"
+  | "observe:logs"
+
+/** Registered id universes a grant kind ranges over, plus subtype expansion. */
+export interface GrantUniverse {
+  readonly applicationIds: ReadonlySet<string>
+  readonly objectTypeIds: ReadonlySet<string>
+  readonly datasetIds: ReadonlySet<string>
+  readonly actionIds: ReadonlySet<string>
+  readonly workflowIds: ReadonlySet<string>
+  readonly syncIds: ReadonlySet<string>
+  readonly pipelineIds: ReadonlySet<string>
+  readonly agentIds: ReadonlySet<string>
+  readonly observableIds: ReadonlySet<string>
+  readonly getSubTypes: (objectTypeId: string) => readonly string[]
+}
+
+/** The registered-id sets a grant kind validates against (no subtype hook). */
+export type GrantUniverseKey = Exclude<keyof GrantUniverse, "getSubTypes">
+
+interface GrantKindSpec {
+  /** Registered universe the grant's ids must belong to. */
+  readonly universeKey: GrantUniverseKey
+  /** Subject noun used in validation errors ("unknown <subject> '<id>'"). */
+  readonly subject: string
+  /** Actionable hint appended to the "unknown <subject>" error. */
+  readonly fix: string
+  /** Only object-type grants also expand to subtypes. */
+  readonly expandsSubtypes?: true
+}
+
+/**
+ * The exhaustive grant-kind table. A new grant family is one entry here; the
+ * `Record<GrantKind, …>` makes every omission a compile error.
+ */
+export const GRANT_KINDS: Record<GrantKind, GrantKindSpec> = {
+  "access:application": {
+    universeKey: "applicationIds",
+    subject: "application",
+    fix: "Use an application exported from '@sixb/core'.",
+  },
+  "view:object": {
+    universeKey: "objectTypeIds",
+    subject: "object type",
+    fix: "Register it in 'ontology/' or pass it to createSixb({ ontologies }).",
+    expandsSubtypes: true,
+  },
+  "view:dataset": {
+    universeKey: "datasetIds",
+    subject: "dataset",
+    fix: "Add it to 'datasets/' or pass it to createSixb({ datasets }).",
+  },
+  // Deliberately no `expandsSubtypes`: granting writes on a parent type must not
+  // silently extend to types added under it later. `view:object` expands because
+  // a read of a subtype reveals nothing the parent's grant did not already cover.
+  "edit:object": {
+    universeKey: "objectTypeIds",
+    subject: "object type",
+    fix: "Register it in 'ontology/' or pass it to createSixb({ ontologies }).",
+  },
+  "append:telemetry": {
+    universeKey: "objectTypeIds",
+    subject: "object type",
+    fix: "Register it in 'ontology/' or pass it to createSixb({ ontologies }).",
+  },
+  "apply:action": {
+    universeKey: "actionIds",
+    subject: "action",
+    fix: "Add it to 'actions/' or pass it to createSixb({ actions }).",
+  },
+  "run:workflow": {
+    universeKey: "workflowIds",
+    subject: "workflow",
+    fix: "Add it to 'workflows/' or pass it to createSixb({ workflows }).",
+  },
+  "run:sync": {
+    universeKey: "syncIds",
+    subject: "sync",
+    fix: "Add it to 'syncs/' or pass it to createSixb({ syncs }).",
+  },
+  "run:pipeline": {
+    universeKey: "pipelineIds",
+    subject: "pipeline",
+    fix: "Add it to 'pipelines/' or pass it to createSixb({ pipelines }).",
+  },
+  "run:agent": {
+    universeKey: "agentIds",
+    subject: "agent",
+    fix: "Add it to 'agents/' or pass it to createSixb({ agents }).",
+  },
+  "observe:logs": {
+    universeKey: "observableIds",
+    subject: "observability surface",
+    fix: 'Use can.observe("logs").',
+  },
+}
+
+export const GRANT_KIND_KEYS = Object.keys(GRANT_KINDS) as readonly GrantKind[]
+
+/** The grant kind a stored grant resolves to. */
+export function grantKindOf(grant: GrantDefinition): GrantKind {
+  switch (grant.capability) {
+    case "access":
+      return "access:application"
+    case "view":
+      return `view:${grant.target}`
+    case "edit":
+      return "edit:object"
+    case "append":
+      return "append:telemetry"
+    case "apply":
+      return "apply:action"
+    case "run":
+      return `run:${grant.target}`
+    case "observe":
+      return "observe:logs"
+  }
+}
+
+/** A fresh, mutable grant index with one empty id set per kind. */
+export function emptyGrantSets(): Record<GrantKind, Set<string>> {
+  const sets = {} as Record<GrantKind, Set<string>>
+  for (const kind of GRANT_KIND_KEYS) {
+    sets[kind] = new Set<string>()
+  }
+  return sets
+}

package/src/authorization/index.ts

@@ -0,0 +1,24 @@
+export { canAccessApplication, isApplicationAccessControlled } from "./application-access"
+export type { AuthzDecision, AuthzRequest } from "./decision"
+export {
+  assertAuthorized,
+  assertCanAppendTelemetry,
+  assertCanEdit,
+  assertPrivileged,
+  evaluate,
+  isAllowed,
+} from "./decision"
+export { AuthorizationError } from "./errors"
+export { canViewEvent } from "./event-visibility"
+export type { GrantKind, GrantUniverse } from "./grant-kinds"
+export { resolveAuthorizationContext, resolveRoleGrants } from "./resolve"
+export {
+  canViewActionRun,
+  canViewPipelineRun,
+  canViewProjection,
+  canViewProjectionRun,
+  canViewWorkflowIntervention,
+  canViewWorkflowRun,
+} from "./run-visibility"
+export type { AuthorizationContext, GrantIndex, ResolvedRole } from "./types"
+export { emptyGrantIndex } from "./types"

package/src/authorization/resolve.ts

@@ -0,0 +1,101 @@
+import type { Principal } from "../auth/types"
+import type { RoleDefinition, Selection } from "../security"
+import {
+  emptyGrantSets,
+  GRANT_KIND_KEYS,
+  GRANT_KINDS,
+  type GrantUniverse,
+  grantKindOf,
+} from "./grant-kinds"
+import type { AuthorizationContext, GrantIndex, ResolvedRole } from "./types"
+
+/**
+ * Expand a role's grants into concrete id sets once at startup.
+ *
+ * Broad grants (`every.object().except([...])`) expand against the registered
+ * universe; object-type grants also expand to subtypes. The result holds only
+ * `Set`s, so per-request resolution and runtime checks stay simple `set.has`.
+ * The per-kind universe and subtype rules come from the `GRANT_KINDS` table, so
+ * this loop never enumerates targets by hand.
+ */
+export function resolveRoleGrants(role: RoleDefinition, universe: GrantUniverse): GrantIndex {
+  const grants = emptyGrantSets()
+
+  for (const grant of role.grants) {
+    const kind = grantKindOf(grant)
+    const spec = GRANT_KINDS[kind]
+    expandSelection(
+      grant.selection,
+      universe[spec.universeKey],
+      grants[kind],
+      spec.expandsSubtypes ? universe.getSubTypes : undefined
+    )
+  }
+
+  return grants
+}
+
+function expandSelection(
+  selection: Selection,
+  universe: ReadonlySet<string>,
+  into: Set<string>,
+  expand?: (id: string) => readonly string[]
+): void {
+  if (selection.all) {
+    const except = new Set(selection.except)
+    for (const id of universe) {
+      if (!except.has(id)) {
+        into.add(id)
+      }
+    }
+    return
+  }
+
+  for (const id of selection.ids) {
+    into.add(id)
+    if (expand) {
+      for (const subTypeId of expand(id)) {
+        into.add(subTypeId)
+      }
+    }
+  }
+}
+
+/**
+ * Resolve a principal's authorization context from its group memberships.
+ *
+ * Pure set-union over pre-resolved roles: roles match when their grantedTo
+ * groups intersect the principal's memberships, and their concrete id sets
+ * union into the principal's grant index.
+ */
+export function resolveAuthorizationContext(input: {
+  readonly principal: Principal
+  readonly sessionId?: string
+  readonly groupIds: readonly string[]
+  readonly roles: readonly ResolvedRole[]
+}): AuthorizationContext {
+  const memberGroupIds = new Set(input.groupIds)
+  const roleIds: string[] = []
+  const grants = emptyGrantSets()
+
+  for (const role of input.roles) {
+    if (!role.grantedToGroupIds.some((groupId) => memberGroupIds.has(groupId))) {
+      continue
+    }
+
+    roleIds.push(role.id)
+    for (const kind of GRANT_KIND_KEYS) {
+      for (const id of role.grants[kind]) {
+        grants[kind].add(id)
+      }
+    }
+  }
+
+  return {
+    principal: input.principal,
+    ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+    groupIds: input.groupIds,
+    roleIds,
+    grants,
+  }
+}

package/src/authorization/run-visibility.ts

@@ -0,0 +1,78 @@
+import type { ProjectionDefinition, ProjectionTarget } from "../projections"
+import { projectionTargetOf } from "../projections/builders"
+import type { ActionRunRecord } from "../storage/action-runs"
+import type { PipelineRunRecord } from "../storage/pipeline-runs"
+import type { WorkflowInterventionRecord } from "../storage/workflow-interventions"
+import type { WorkflowRunRecord } from "../storage/workflow-runs"
+import { isAllowed } from "./decision"
+import type { AuthorizationContext } from "./types"
+
+export function canViewActionRun(
+  authorization: AuthorizationContext | null | undefined,
+  run: Pick<ActionRunRecord, "actionId" | "subject">
+): boolean {
+  if (!authorization) {
+    return true
+  }
+
+  if (!isAllowed(authorization, { kind: "action.apply", actionId: run.actionId })) {
+    return false
+  }
+
+  return run.subject.kind !== "object"
+    ? true
+    : isAllowed(authorization, {
+        kind: "object.view",
+        objectTypeId: run.subject.objectTypeId,
+      })
+}
+
+export function canViewWorkflowRun(
+  authorization: AuthorizationContext | null | undefined,
+  run: Pick<WorkflowRunRecord, "workflowId">
+): boolean {
+  return (
+    !authorization || isAllowed(authorization, { kind: "workflow.run", workflowId: run.workflowId })
+  )
+}
+
+export function canViewWorkflowIntervention(
+  authorization: AuthorizationContext | null | undefined,
+  intervention: Pick<WorkflowInterventionRecord, "workflowId">
+): boolean {
+  return (
+    !authorization ||
+    isAllowed(authorization, { kind: "workflow.run", workflowId: intervention.workflowId })
+  )
+}
+
+export function canViewPipelineRun(
+  authorization: AuthorizationContext | null | undefined,
+  run: Pick<PipelineRunRecord, "pipelineId">
+): boolean {
+  return (
+    !authorization || isAllowed(authorization, { kind: "pipeline.run", pipelineId: run.pipelineId })
+  )
+}
+
+/** A projection run is viewable when its target object type(s) are viewable. */
+export function canViewProjectionRun(
+  authorization: AuthorizationContext | null | undefined,
+  target: ProjectionTarget
+): boolean {
+  if (!authorization) return true
+  const canView = (objectTypeId: string) =>
+    isAllowed(authorization, { kind: "object.view", objectTypeId })
+  if ("sourceObjectTypeId" in target) {
+    return canView(target.sourceObjectTypeId) && canView(target.targetObjectTypeId)
+  }
+  return canView(target.objectTypeId)
+}
+
+/** Whether a principal may see a projection definition (and its run history). */
+export function canViewProjection(
+  authorization: AuthorizationContext | null | undefined,
+  projection: ProjectionDefinition
+): boolean {
+  return canViewProjectionRun(authorization, projectionTargetOf(projection))
+}

package/src/authorization/types.ts

@@ -0,0 +1,52 @@
+/**
+ * Authorization context types.
+ *
+ * The context is plain, immutable data resolved once per request
+ * (`principal -> groups -> roles -> grants`). Grants resolve eagerly into set
+ * lookups so enforcement on the hot path is synchronous and allocation-free.
+ * Group and role ids are retained so decisions stay explainable.
+ */
+
+import type { Principal } from "../auth/types"
+import { emptyGrantSets, type GrantKind } from "./grant-kinds"
+
+/**
+ * Grants resolved to concrete id sets, keyed by grant kind (`view:object`,
+ * `run:sync`, …). Broad grants and object subtypes are already expanded, so
+ * enforcement is a single `grants[kind].has(id)` lookup. Keyed by `GrantKind`
+ * so a new grant family adds one key, not a new bucket every consumer must
+ * learn.
+ */
+export type GrantIndex = Readonly<Record<GrantKind, ReadonlySet<string>>>
+
+/**
+ * A grant index that grants nothing, as the base for a hand-built context — typically in tests.
+ *
+ * This is the read-only face of `emptyGrantSets()`, the mutable builder resolution fills in and which
+ * stays internal. A factory rather than a shared constant, because the sets are only `ReadonlySet` to
+ * the type system: one frozen instance would be aliased into every context that spreads it.
+ *
+ * Writing the literal by hand is what this avoids. `GrantIndex` is deliberately a total `Record` so
+ * that `grants[kind].has(id)` cannot be misspelled into a silent `undefined` — with an optional index
+ * every enforcement site would read `?.has(id) ?? false`, where a typo denies instead of failing to
+ * compile. The cost of totality is that a literal breaks whenever a grant family is added.
+ */
+export function emptyGrantIndex(): GrantIndex {
+  return emptyGrantSets()
+}
+
+/** A role with its grants pre-expanded to concrete id sets at startup. */
+export interface ResolvedRole {
+  readonly id: string
+  readonly grantedToGroupIds: readonly string[]
+  readonly grants: GrantIndex
+}
+
+export interface AuthorizationContext {
+  readonly principal: Principal
+  readonly sessionId?: string
+  readonly groupIds: readonly string[]
+  /** Roles whose grantedTo groups intersect the principal's memberships. */
+  readonly roleIds: readonly string[]
+  readonly grants: GrantIndex
+}

package/src/blob-storage/browser.ts

@@ -0,0 +1,28 @@
+// Browser-safe blob-storage surface: the FileRef contract plus pure helpers that
+// never reach `node:crypto`. Client and UI code should import from
+// `@sixb/core/blob-storage` (this module) rather than the root `@sixb/core`
+// barrel, which co-bundles the Node-only provider utilities.
+
+import type { FileRef } from "./types"
+
+export { DEFAULT_SIMPLE_FILE_UPLOAD_BYTES } from "./constants"
+export { blobDigestHex, blobIdFromDigest } from "./derive"
+export type { BlobDigest, BlobInfo, FileRef } from "./types"
+export { isBlobDigest, isFileRef } from "./validation"
+
+/**
+ * Best-effort display name for a file reference: the trailing path segment of
+ * `fileName`, else of `logicalPath`, else a synthetic `<blobId>.bin`.
+ *
+ * `fileName`/`logicalPath` are untrusted caller metadata; callers that render or
+ * set headers with the result must still sanitize it.
+ */
+export function fileNameFor(fileRef: FileRef): string {
+  const fromFileName = fileRef.fileName?.split(/[\\/]/).filter(Boolean).at(-1)
+  if (fromFileName) {
+    return fromFileName
+  }
+
+  const fromLogicalPath = fileRef.logicalPath?.split(/[\\/]/).filter(Boolean).at(-1)
+  return fromLogicalPath || `${fileRef.blobId}.bin`
+}

package/src/blob-storage/constants.ts

@@ -0,0 +1,9 @@
+/**
+ * Maximum size, in bytes, of a single-request ("server"-strategy) file upload.
+ *
+ * This is a single source of truth for two sides that must agree: it is both the
+ * server's simple-upload ceiling AND the client's threshold for switching to a
+ * staged (direct-put) upload. Keeping one constant prevents the two limits from
+ * drifting apart.
+ */
+export const DEFAULT_SIMPLE_FILE_UPLOAD_BYTES = 25 * 1024 * 1024

package/src/blob-storage/derive.ts

@@ -0,0 +1,13 @@
+import type { BlobDigest } from "./types"
+
+// Pure, crypto-free derivations of blob identity from a digest. Kept out of
+// `utils.ts` (which imports `node:crypto`) so the browser-safe `./browser`
+// barrel can reuse them without dragging Node crypto into the client bundle.
+
+export function blobDigestHex(digest: BlobDigest): string {
+  return digest.slice("sha256:".length)
+}
+
+export function blobIdFromDigest(digest: BlobDigest): string {
+  return `blob_${blobDigestHex(digest)}`
+}

package/src/blob-storage/errors.ts

@@ -0,0 +1,6 @@
+/**
+ * Error for blob storage invariants and provider-level failures.
+ */
+export class BlobStorageError extends Error {
+  readonly name = "BlobStorageError"
+}

package/src/blob-storage/in-memory.ts

@@ -0,0 +1,74 @@
+import { blobIdFromDigest } from "./derive"
+import { BlobStorageError } from "./errors"
+import type {
+  BlobByteRange,
+  BlobInfo,
+  BlobStorage,
+  FileRef,
+  PutBlobInput,
+  RangeReadableBlobStorage,
+} from "./types"
+import {
+  assertExpectedBlobSize,
+  assertValidExpectedBlobSize,
+  computeBlobDigest,
+  createFileRef,
+  readBlobBody,
+} from "./utils"
+
+type StoredBlob = {
+  readonly bytes: Uint8Array
+  readonly info: BlobInfo
+}
+
+export class InMemoryBlobStorage implements BlobStorage, RangeReadableBlobStorage {
+  private readonly blobsById = new Map<string, StoredBlob>()
+
+  async put(input: PutBlobInput): Promise<FileRef> {
+    assertValidExpectedBlobSize(input.expectedSizeBytes)
+    const bytes = await readBlobBody(input.body, input.signal)
+    assertExpectedBlobSize(input.expectedSizeBytes, bytes.byteLength, "BlobStorage")
+    const digest = computeBlobDigest(bytes)
+    const blobId = blobIdFromDigest(digest)
+
+    let stored = this.blobsById.get(blobId)
+    if (!stored) {
+      stored = {
+        bytes,
+        info: {
+          blobId,
+          digest,
+          sizeBytes: bytes.byteLength,
+        },
+      }
+      this.blobsById.set(blobId, stored)
+    }
+
+    return createFileRef(input, stored.info)
+  }
+
+  async open(blobId: string): Promise<ReadableStream<Uint8Array>> {
+    const stored = this.requireStoredBlob(blobId)
+    return new Blob([new Uint8Array(stored.bytes)]).stream()
+  }
+
+  async openRange(blobId: string, range: BlobByteRange): Promise<ReadableStream<Uint8Array>> {
+    const stored = this.requireStoredBlob(blobId)
+    const bytes = stored.bytes.slice(range.start, range.endInclusive + 1)
+    return new Blob([bytes]).stream()
+  }
+
+  async stat(blobId: string): Promise<BlobInfo | null> {
+    const stored = this.blobsById.get(blobId)
+    return stored ? { ...stored.info } : null
+  }
+
+  private requireStoredBlob(blobId: string): StoredBlob {
+    const stored = this.blobsById.get(blobId)
+    if (!stored) {
+      throw new BlobStorageError(`[BlobStorage] Unknown blob '${blobId}'`)
+    }
+
+    return stored
+  }
+}

package/src/blob-storage/index.ts

@@ -0,0 +1,37 @@
+export type { BlobDigest, BlobInfo, FileRef } from "./browser"
+export {
+  blobDigestHex,
+  blobIdFromDigest,
+  DEFAULT_SIMPLE_FILE_UPLOAD_BYTES,
+  fileNameFor,
+  isBlobDigest,
+  isFileRef,
+} from "./browser"
+export { BlobStorageError } from "./errors"
+export { InMemoryBlobStorage } from "./in-memory"
+export type {
+  AbortBlobUploadInput,
+  BlobBody,
+  BlobByteRange,
+  BlobStorage,
+  BlobUploadPart,
+  BlobUploadSession,
+  CompleteBlobUploadInput,
+  CreateBlobUploadInput,
+  DirectPutBlobUploadSession,
+  DirectUploadBlobStorage,
+  MultipartBlobUploadSession,
+  PutBlobInput,
+  RangeReadableBlobStorage,
+  SignBlobUploadPartInput,
+  SignedBlobUploadPart,
+} from "./types"
+export {
+  assertExpectedBlobSize,
+  assertValidExpectedBlobSize,
+  computeBlobDigest,
+  createFileRef,
+  readBlobBody,
+  streamBlobBody,
+} from "./utils"
+export { supportsDirectUpload, supportsRangeRead } from "./validation"