@sixb/core 0.1.7 → 0.1.9

package/src/security/grants.ts

@@ -7,12 +7,20 @@
  * checks stay simple `set.has(id)` lookups.
  */
 
-import type { ActionDefinition } from "../actions/types"
+import type { ActionDefinition, ObjectActionDefinition } from "../actions/types"
+import { isObjectActionDefinition } from "../actions/validation"
 import type { AgentReference, AgentUsageReference } from "../agents/types"
 import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets"
 import type { ObjectType } from "../ontology"
 import type { PipelineDefinition } from "../pipelines"
+import { createShareActionGrant, createShareViewGrant, isShareTarget } from "../shares/builders"
+import type {
+  ShareActionGrantBuilder,
+  ShareDefinition,
+  ShareTarget,
+  ShareViewGrantBuilder,
+} from "../shares/types"
 import type { SyncDefinition } from "../syncs"
 import type { WorkflowDefinition } from "../workflows/types"
 import { SecurityValidationError } from "./errors"
@@ -33,6 +41,7 @@ import type {
   ObserveGrant,
   RunGrant,
   Selection,
+  ShareGrant,
   ViewGrant,
 } from "./types"
 
@@ -56,6 +65,7 @@ const TARGET_BY_DEFINITION_KIND: Readonly<Partial<Record<string, BreadthTarget>>
   workflow: "workflow",
   application: "application",
   connector: "connector",
+  share: "share",
 }
 
 const UNDISCRIMINATED_TARGETS: readonly BreadthTarget[] = ["object", "action"]
@@ -153,9 +163,15 @@ function access(input: GrantInput<ApplicationDefinition, "application">): Access
   return { kind: "grant", capability: "access", target: "application", selection }
 }
 
+function view<const TObjectTypeId extends string>(
+  input: ShareTarget<TObjectTypeId>
+): ShareViewGrantBuilder<TObjectTypeId>
 function view(input: GrantInput<ObjectType, "object">): ViewGrant<"object">
 function view(input: GrantInput<DatasetDefinition, "dataset">): ViewGrant<"dataset">
-function view(input: GrantInput<ObjectType | DatasetDefinition, "object" | "dataset">): ViewGrant {
+function view(
+  input: ShareTarget | GrantInput<ObjectType | DatasetDefinition, "object" | "dataset">
+): ViewGrant | ShareViewGrantBuilder {
+  if (isShareTarget(input)) return createShareViewGrant(input)
   const { target, selection } = resolveGrant(input, "can.view", VIEW_TARGETS)
   return { kind: "grant", capability: "view", target, selection }
 }
@@ -176,12 +192,37 @@ function append(input: GrantInput<ObjectType, "object">): AppendGrant {
   }
 }
 
+function apply<const TAction extends ObjectActionDefinition>(
+  input: TAction
+): ApplyGrant & ShareActionGrantBuilder<TAction>
+function apply(input: GrantInput<ActionDefinition, "action">): ApplyGrant
 function apply(input: GrantInput<ActionDefinition, "action">): ApplyGrant {
-  return {
+  const grant: ApplyGrant = {
     kind: "grant",
     capability: "apply",
     selection: resolveGrant(input, "can.apply", ["action"]).selection,
   }
+  // `Array.isArray` does not narrow a readonly array. This cast restores the branch already proved
+  // above; every non-selector, non-array GrantInput is one Action definition.
+  const one: ActionDefinition | undefined =
+    Array.isArray(input) || isBreadthSelector(input) ? undefined : (input as ActionDefinition)
+  if (one && isObjectActionDefinition(one)) {
+    Object.defineProperty(grant, "on", {
+      configurable: false,
+      enumerable: false,
+      writable: false,
+      value: (target: ShareTarget) => createShareActionGrant(one, target),
+    })
+  }
+  return grant
+}
+
+function share(input: GrantInput<ShareDefinition, "share">): ShareGrant {
+  return {
+    kind: "grant",
+    capability: "share",
+    selection: resolveGrant(input, "can.share", ["share"]).selection,
+  }
 }
 
 function run(input: GrantInput<WorkflowDefinition, "workflow">): RunGrant<"workflow">
@@ -265,6 +306,7 @@ export const can = {
   edit,
   append,
   apply,
+  share,
   run,
   observe,
   manage,

package/src/security/index.ts

@@ -40,6 +40,7 @@ export type {
   RunGrant,
   RunGrantTarget,
   Selection,
+  ShareGrant,
   ViewGrant,
   ViewGrantTarget,
 } from "./types"

package/src/security/registry.ts

@@ -27,6 +27,7 @@ export interface SecurityRegistryOptions {
   readonly pipelineIds?: ReadonlySet<string>
   readonly agentAvailable?: boolean
   readonly connectorIds?: ReadonlySet<string>
+  readonly shareIds?: ReadonlySet<string>
   readonly getSubTypes?: (objectTypeId: string) => readonly string[]
 }
 
@@ -52,6 +53,7 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
       connectorIds: input.connectorIds,
       observableIds: new Set(["logs", "aiUsage"]),
       manageableIds: new Set(["aiUsage"]),
+      shareIds: input.shareIds,
     })
 
     const universe = {
@@ -65,6 +67,7 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
       connectorIds: input.connectorIds ?? new Set<string>(),
       observableIds: new Set(["logs", "aiUsage"]),
       manageableIds: new Set(["aiUsage"]),
+      shareIds: input.shareIds ?? new Set<string>(),
       getSubTypes: input.getSubTypes ?? (() => []),
     }
 

package/src/security/types.ts

@@ -86,6 +86,13 @@ export interface ApplyGrant {
   readonly selection: Selection
 }
 
+/** Issue, list, and revoke grants created from the selected Share definitions. */
+export interface ShareGrant {
+  readonly kind: "grant"
+  readonly capability: "share"
+  readonly selection: Selection
+}
+
 export type RunGrantTarget = "workflow" | "sync" | "pipeline"
 
 export interface RunGrant<TTarget extends RunGrantTarget = RunGrantTarget> {
@@ -127,6 +134,7 @@ export type GrantDefinition =
   | EditGrant
   | AppendGrant
   | ApplyGrant
+  | ShareGrant
   | RunGrant
   | AgentRunGrant
   | ObserveGrant

package/src/security/validation.ts

@@ -30,6 +30,7 @@ const GRANT_CAPABILITIES = Object.keys({
   edit: true,
   append: true,
   apply: true,
+  share: true,
   run: true,
   observe: true,
   manage: true,
@@ -321,6 +322,8 @@ export function validateSecurityDefinitionsAtStartup(input: {
   readonly manageableIds?: ReadonlySet<string>
   /** Registered connector ids — when provided, manage grants must reference them. */
   readonly connectorIds?: ReadonlySet<string>
+  /** Registered Share ids — when provided, share grants must reference them. */
+  readonly shareIds?: ReadonlySet<string>
 }): RegisteredSecurityDefinitions {
   const groupsById = new Map<string, GroupDefinition>()
   const rolesById = new Map<string, RoleDefinition>()

package/src/shares/access-plan.ts

@@ -0,0 +1,225 @@
+import type { ObjectRef } from "../ontology"
+import {
+  captureSelectedObjectReadScope,
+  compileSelectedObjectReadScope,
+} from "../storage/objects/read-scope"
+import type { ObjectReadRoot, SelectedObjectReadScope } from "../storage/objects/types"
+
+const MAX_SCOPED_GRANTS = 1_024
+const MAX_SCOPED_VIEW_ROOTS_BEFORE_COMPILATION = 1_024
+const MAX_SCOPED_ACTION_SUBJECTS = 4_096
+const MAX_SCOPED_ACTION_IDENTIFIER_CHARACTERS = 1_000_000
+
+/** One capability paired with the exact resources it authorizes. */
+export type ShareScopedGrant = ShareScopedViewGrant | ShareScopedActionGrant
+
+export interface ShareScopedViewGrant {
+  readonly kind: "object.view"
+  readonly selection: SelectedObjectReadScope
+}
+
+export interface ShareScopedActionGrant {
+  readonly kind: "action.apply"
+  readonly actionId: string
+  readonly subjects: readonly ObjectRef[]
+}
+
+/** Internal authority compiled from a delegation such as a shared-access grant. */
+export interface ShareAccessPlan {
+  readonly grants: readonly ShareScopedGrant[]
+}
+
+interface CapturedViewGrant {
+  readonly kind: "object.view"
+  readonly rootStart: number
+  readonly rootCount: number
+}
+
+type CapturedGrant = CapturedViewGrant | ShareScopedActionGrant
+
+interface ActionCaptureBudget {
+  subjectCount: number
+  identifierCharacters: number
+}
+
+/** Validate and detach an access plan before registering process-local authority. */
+export function snapshotShareAccessPlan(input: ShareAccessPlan): ShareAccessPlan {
+  const captured = captureAccessPlanGrants(input)
+  const selection = validateMergedViewSelection(captured.viewRoots)
+  return assembleAccessPlanSnapshot(captured.grants, selection)
+}
+
+function captureAccessPlanGrants(input: ShareAccessPlan): {
+  readonly grants: readonly CapturedGrant[]
+  readonly viewRoots: readonly ObjectReadRoot[]
+} {
+  if (!isRecord(input)) {
+    throw new Error("[Sixb] Share access plan must contain scoped grants.")
+  }
+  const authoredGrants = input.grants
+  if (!Array.isArray(authoredGrants)) {
+    throw new Error("[Sixb] Share access plan must contain scoped grants.")
+  }
+  const grantCount = authoredGrants.length
+  if (grantCount > MAX_SCOPED_GRANTS) {
+    throw new Error(
+      `[Sixb] Share access plan exceeds the maximum of ${MAX_SCOPED_GRANTS} scoped grants.`
+    )
+  }
+
+  // Share budgets across grants and capture caller-controlled fields exactly once.
+  const budget: ActionCaptureBudget = { subjectCount: 0, identifierCharacters: 0 }
+  const viewRoots: ObjectReadRoot[] = []
+  const grants: CapturedGrant[] = []
+  for (let index = 0; index < grantCount; index += 1) {
+    const grant = authoredGrants[index]
+    if (!isRecord(grant)) {
+      throw new Error(`[Sixb] Scoped grant ${index} must be an object.`)
+    }
+    const kind = grant.kind
+    switch (kind) {
+      case "object.view":
+        grants.push(captureViewGrant(grant, index, viewRoots))
+        break
+      case "action.apply":
+        grants.push(captureActionGrant(grant, index, budget))
+        break
+      default:
+        throw new Error(`[Sixb] Unknown scoped grant kind '${String(kind)}'.`)
+    }
+  }
+  return { grants, viewRoots }
+}
+
+function captureViewGrant(
+  grant: Record<string, unknown>,
+  index: number,
+  viewRoots: ObjectReadRoot[]
+): CapturedViewGrant {
+  const selection = grant.selection
+  if (!isRecord(selection)) {
+    throw new Error(`[Sixb] Scoped grant ${index} requires a selected object read scope.`)
+  }
+  const selectionKind = selection.kind
+  const roots = selection.roots
+  if (selectionKind !== "selected" || !Array.isArray(roots)) {
+    throw new Error(`[Sixb] Scoped grant ${index} requires a selected object read scope.`)
+  }
+  const rootCount = roots.length
+  if (rootCount > MAX_SCOPED_VIEW_ROOTS_BEFORE_COMPILATION - viewRoots.length) {
+    throw new Error(
+      `[Sixb] Share access plan exceeds the maximum of ${MAX_SCOPED_VIEW_ROOTS_BEFORE_COMPILATION} raw scoped view roots.`
+    )
+  }
+  const rootStart = viewRoots.length
+  for (let rootIndex = 0; rootIndex < rootCount; rootIndex += 1) {
+    viewRoots.push(roots[rootIndex] as ObjectReadRoot)
+  }
+  return { kind: "object.view", rootStart, rootCount }
+}
+
+function captureActionGrant(
+  grant: Record<string, unknown>,
+  index: number,
+  budget: ActionCaptureBudget
+): ShareScopedActionGrant {
+  const authoredActionId = grant.actionId
+  const authoredSubjects = grant.subjects
+  const actionId = nonEmpty(authoredActionId, `Scoped grant ${index} action id`)
+  addActionIdentifierCharacters(budget, actionId.length)
+  if (!Array.isArray(authoredSubjects)) {
+    throw new Error(`[Sixb] Scoped grant ${index} action subjects must be an array.`)
+  }
+  const subjectCount = authoredSubjects.length
+  budget.subjectCount += subjectCount
+  if (budget.subjectCount > MAX_SCOPED_ACTION_SUBJECTS) {
+    throw new Error(
+      `[Sixb] Share access plan exceeds the maximum of ${MAX_SCOPED_ACTION_SUBJECTS} scoped action subjects.`
+    )
+  }
+  const subjects: ObjectRef[] = []
+  for (let subjectIndex = 0; subjectIndex < subjectCount; subjectIndex += 1) {
+    const subject = captureActionSubject(authoredSubjects[subjectIndex], index, subjectIndex)
+    addActionIdentifierCharacters(budget, subject.objectTypeId.length + subject.primaryId.length)
+    subjects.push(subject)
+  }
+  return Object.freeze({ kind: "action.apply", actionId, subjects: Object.freeze(subjects) })
+}
+
+function captureActionSubject(
+  subject: unknown,
+  grantIndex: number,
+  subjectIndex: number
+): ObjectRef {
+  if (!isRecord(subject)) {
+    throw new Error(`[Sixb] Scoped grant ${grantIndex} subject ${subjectIndex} must be an object.`)
+  }
+  const authoredObjectTypeId = subject.objectTypeId
+  const authoredPrimaryId = subject.primaryId
+  const objectTypeId = nonEmpty(
+    authoredObjectTypeId,
+    `Scoped grant ${grantIndex} subject ${subjectIndex} object type id`
+  )
+  const primaryId = nonEmpty(
+    authoredPrimaryId,
+    `Scoped grant ${grantIndex} subject ${subjectIndex} primary id`
+  )
+  return Object.freeze({ objectTypeId, primaryId })
+}
+
+function addActionIdentifierCharacters(budget: ActionCaptureBudget, count: number): void {
+  budget.identifierCharacters += count
+  if (budget.identifierCharacters > MAX_SCOPED_ACTION_IDENTIFIER_CHARACTERS) {
+    throw new Error(
+      `[Sixb] Share access plan exceeds the maximum of ${MAX_SCOPED_ACTION_IDENTIFIER_CHARACTERS} scoped action identifier characters.`
+    )
+  }
+}
+
+function validateMergedViewSelection(roots: readonly ObjectReadRoot[]): SelectedObjectReadScope {
+  // Snapshot all roots together so the provider's limits apply globally across view grants.
+  const selection = captureSelectedObjectReadScope({ kind: "selected", roots })
+  // Compile the exact immutable snapshot, without rereading caller-controlled data.
+  compileSelectedObjectReadScope(selection)
+  return selection
+}
+
+function assembleAccessPlanSnapshot(
+  capturedGrants: readonly CapturedGrant[],
+  selection: SelectedObjectReadScope
+): ShareAccessPlan {
+  const grants = capturedGrants.map((grant): ShareScopedGrant => {
+    if (grant.kind === "action.apply") return grant
+    const roots = Object.freeze(
+      selection.roots.slice(grant.rootStart, grant.rootStart + grant.rootCount)
+    )
+    return Object.freeze({
+      kind: "object.view",
+      selection: Object.freeze({ kind: "selected", roots }),
+    })
+  })
+  return Object.freeze({ grants: Object.freeze(grants) })
+}
+
+/** Merge view grants only; capability/resource pairing remains intact for every other grant. */
+export function objectReadScopeForAccessPlan(plan: ShareAccessPlan): SelectedObjectReadScope {
+  return Object.freeze({
+    kind: "selected",
+    roots: Object.freeze(
+      plan.grants.flatMap((grant) =>
+        grant.kind === "object.view" ? [...grant.selection.roots] : []
+      )
+    ),
+  })
+}
+
+function nonEmpty(value: unknown, label: string): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`[Sixb] ${label} must not be empty.`)
+  }
+  return value
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}