@sixb/core 0.1.17 → 0.1.19

package/src/agents/types.ts

@@ -1,10 +1,13 @@
-import type { BlobBody, FileRef } from "../blob-storage"
+import type { ActionsRuntime } from "../actions/execution"
+import type { BlobBody, FileRef, OpenedFileRef } from "../blob-storage"
 import type { ConnectorRuntime } from "../connectors"
 import type { JsonPrimitive, JsonValue, ReadonlyJsonValue } from "../json"
 import type { Logger } from "../logging"
 import { type LanguageModelRef, MODEL_REASONING_LEVELS, type ModelReasoning } from "../models"
+import type { ModelsRuntime } from "../models/generation-types"
 import type { InferSchema } from "../ontology/inference"
 import type { Schema } from "../ontology/types"
+import type { ObjectReader } from "../runtime/types"
 
 export type {
   AgentContextEntryInput,
@@ -32,9 +35,6 @@ export interface AgentDescriptor {
 
 export type AgentReasoning = ModelReasoning
 
-/** @deprecated Use {@link AgentReasoning}. */
-export type AgentReasoningLevel = AgentReasoning
-
 export const AGENT_REASONING_LEVELS = MODEL_REASONING_LEVELS
 
 type Simplify<T> = { [K in keyof T]: T[K] } & {}
@@ -98,6 +98,19 @@ export interface AgentToolArtifacts {
   put(input: AgentToolArtifactPutInput): Promise<AgentToolArtifact>
 }
 
+/**
+ * The files attached to the run that invoked a tool: the messages of a chat's thread, or the input
+ * files of a workflow AI task. A child Agent has none.
+ */
+export interface AgentToolAttachments {
+  /**
+   * Open an attachment by the `key` the Agent sees in `$SIXB_ATTACHMENTS`. Returns null when its
+   * stored file is gone, and throws an `AgentToolPublicError` for a key that is not one of this
+   * run's attachments.
+   */
+  open(key: string): Promise<OpenedFileRef | null>
+}
+
 export type AgentToolTextContent = {
   readonly type: "text"
   readonly text: string
@@ -120,6 +133,22 @@ export type AgentToolResult = {
   readonly content: readonly AgentToolContent[]
 }
 
+/**
+ * The run's domain SDK as an agent tool sees it. Unlike workflow steps and actions, it acts as the
+ * run's requester: the signed-in user in a chat, that same user in a child Agent, and the step's
+ * groups in a workflow AI task.
+ *
+ * A structural view of the public `Sixb` SDK, like `WorkflowRuntimeFacade`: the handler receives the
+ * run's bound SDK, and this type guides it to what a tool should do. It reads objects and changes
+ * them by requesting actions, which validate and record the change. Authority comes from the run,
+ * not from this view.
+ */
+export interface AgentToolRuntimeFacade extends ObjectReader {
+  readonly actions: ActionsRuntime
+  readonly models: ModelsRuntime
+  readonly connector: ConnectorRuntime
+}
+
 /** The narrow, run-scoped surface passed to an agent tool handler. */
 export interface AgentToolRunContext<
   TInput extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>,
@@ -128,9 +157,10 @@ export interface AgentToolRunContext<
   readonly toolCallId: string
   readonly signal: AbortSignal
   readonly run: AgentToolRunInfo
-  readonly connector: ConnectorRuntime
+  readonly sixb: AgentToolRuntimeFacade
   readonly logger: Logger
   readonly artifacts: AgentToolArtifacts
+  readonly attachments: AgentToolAttachments
 }
 
 /** Agent tool handlers may return only values safe to persist in agent messages. */

package/src/auth/runtime.ts

@@ -655,6 +655,7 @@ export class AuthRuntime {
     caller: AuthenticatedUserRequestSession,
     input: CreatePersonalAccessTokenInput
   ): Promise<CreateAccessTokenResult> {
+    assertSessionCaller(caller)
     const storage = this.requireAuthStorage()
     // A personal token can only carry groups the caller currently belongs to.
     const groupIds = constrainRequestedGroupIds(input.groupIds, caller.groupIds, {
@@ -815,6 +816,7 @@ export class AuthRuntime {
     caller: AuthenticatedUserRequestSession,
     input: CreateServiceAccountAccessTokenInput
   ): Promise<CreateServiceAccountAccessTokenResult> {
+    assertSessionCaller(caller)
     const storage = this.requireAuthStorage()
     const { serviceAccount, groupIds: serviceAccountGroupIds } =
       await this.requireManageableServiceAccount(storage, caller.groupIds, input.serviceAccountId)
@@ -1564,6 +1566,18 @@ function callerSessionId(caller: AuthenticatedRequestAuthSession): string | unde
   return caller.credentialSource === "session" ? caller.session.id : undefined
 }
 
+// Access tokens are created only by a signed-in person, never by another access token. A token
+// minting one could hand out more groups or a later expiry than it carries, and what it minted
+// would outlive its own revocation.
+function assertSessionCaller(caller: AuthenticatedUserRequestSession): void {
+  if (caller.credentialSource !== "session") {
+    throw new AuthRuntimeError(
+      "authorization_denied",
+      "[Sixb] Access tokens can only be created from a signed-in session, not with another access token."
+    )
+  }
+}
+
 function constrainTokenGroupIds(
   principalGroupIds: readonly string[],
   accessToken: AccessTokenRecord

package/src/auth/types.ts

@@ -190,6 +190,12 @@ export interface OidcStartSignInInput {
 
 export interface OidcStartSignInResult {
   readonly redirectTo: string
+  /**
+   * The `state` sent to the provider. The server keeps it in a cookie until `expiresAt` and
+   * completes the callback only in the browser that holds it.
+   */
+  readonly state: string
+  readonly expiresAt: Date
 }
 
 export interface OidcCallbackInput {

package/src/authorization/event-visibility.ts

@@ -38,18 +38,6 @@ export function canViewEvent(
         }) &&
         isAllowed(authorization, { kind: "object.view", objectTypeId: event.payload.targetTypeId })
       )
-    case "actions": {
-      // Apply is necessary; for object-bound actions the principal must also be
-      // able to view the subject type, or the event would leak a hidden
-      // object's id/type — mirroring the rule in `canListAction`.
-      if (!isAllowed(authorization, { kind: "action.apply", actionId: event.payload.actionId })) {
-        return false
-      }
-      const subject = event.payload.subject
-      return subject.kind === "object"
-        ? isAllowed(authorization, { kind: "object.view", objectTypeId: subject.objectTypeId })
-        : true
-    }
     case "workflows":
       return isAllowed(authorization, {
         kind: "workflow.run",

package/src/authorization/resolve.ts

@@ -70,7 +70,7 @@ function expandSelection(
  *
  * 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.
+ * and clearances union into the principal's context.
  */
 export function resolveAuthorizationContext(input: {
   readonly principal: Principal
@@ -81,6 +81,7 @@ export function resolveAuthorizationContext(input: {
   const memberGroupIds = new Set(input.groupIds)
   const roleIds: string[] = []
   const grants = emptyGrantSets()
+  const clearances = new Set<string>()
 
   for (const role of input.roles) {
     if (!role.grantedToGroupIds.some((groupId) => memberGroupIds.has(groupId))) {
@@ -96,6 +97,9 @@ export function resolveAuthorizationContext(input: {
         grants[kind].add(id)
       }
     }
+    for (const markingId of role.clearances ?? []) {
+      clearances.add(markingId)
+    }
   }
 
   return {
@@ -104,5 +108,6 @@ export function resolveAuthorizationContext(input: {
     groupIds: input.groupIds,
     roleIds,
     grants,
+    clearances,
   }
 }

package/src/authorization/types.ts

@@ -42,6 +42,8 @@ export interface ResolvedRole {
   readonly id: string
   readonly grantedToGroupIds: readonly string[]
   readonly grants: GrantIndex
+  /** Marking ids this role clears. Absent means none. */
+  readonly clearances?: ReadonlySet<string>
 }
 
 export interface AuthorizationContext {
@@ -51,4 +53,9 @@ export interface AuthorizationContext {
   /** Roles whose grantedTo groups intersect the principal's memberships. */
   readonly roleIds: readonly string[]
   readonly grants: GrantIndex
+  /**
+   * Marking ids the principal may read, unioned from its roles. Absent means none: a context built
+   * without clearances reads no marked property.
+   */
+  readonly clearances?: ReadonlySet<string>
 }

package/src/blob-storage/execution.ts

@@ -8,6 +8,7 @@ import {
   type FileDownloadUrlContext,
   revokeFileDownloadUrl,
 } from "./download-urls"
+import { canonicalMediaType } from "./media-type"
 import type {
   AbortBlobUploadInput,
   BlobByteRange,
@@ -60,6 +61,7 @@ export function createBlobsRuntime(
   const executionBlobs: BlobsRuntime = {
     put: (input) => {
       assertAccess()
+      assertMediaType("put", input.mediaType)
       return blobStorage.put(input)
     },
     open: (blobId) => {
@@ -89,6 +91,7 @@ export function createBlobsRuntime(
   if (supportsDirectUpload(blobStorage)) {
     executionBlobs.createUpload = (input) => {
       assertAccess()
+      assertMediaType("createUpload", input.mediaType)
       return blobStorage.createUpload(input)
     }
     executionBlobs.signUploadPart = (input) => {
@@ -97,6 +100,7 @@ export function createBlobsRuntime(
     }
     executionBlobs.completeUpload = (input) => {
       assertAccess()
+      assertMediaType("completeUpload", input.mediaType)
       return blobStorage.completeUpload(input)
     }
     executionBlobs.abortUpload = (input) => {
@@ -107,3 +111,11 @@ export function createBlobsRuntime(
 
   return Object.freeze(executionBlobs)
 }
+
+function assertMediaType(method: string, mediaType: string | undefined): void {
+  if (mediaType !== undefined && canonicalMediaType(mediaType) === null) {
+    throw new Error(
+      `[Sixb] blobs.${method}() mediaType must be one media type, such as "application/pdf". Received ${JSON.stringify(mediaType)}.`
+    )
+  }
+}

package/src/blob-storage/file-content.ts

@@ -0,0 +1,106 @@
+import type { BlobInfo, BlobStorage, FileRef, OpenedFileRef } from "./types"
+import { isFileRef } from "./validation"
+
+/**
+ * A file is served only through the record that references it: the caller reads that record with
+ * its own authority, resolves the FileRef inside it, then checks the FileRef against the stored
+ * blob. File content routes and the SDK's `file().open()` share these steps.
+ */
+
+/** The FileRef at a JSON Pointer in an authorized record, or null when none is there. */
+export function resolveFileRefAtPath(root: unknown, path: string): FileRef | null {
+  const value = resolveJsonPointer(root, path)
+  return isFileRef(value) ? value : null
+}
+
+/** The stored blob a FileRef names, or null when it is absent or no longer matches it. */
+export async function statFileRef(
+  blobStorage: Pick<BlobStorage, "stat">,
+  fileRef: FileRef
+): Promise<BlobInfo | null> {
+  const stat = await blobStorage.stat(fileRef.blobId)
+  return stat &&
+    stat.blobId === fileRef.blobId &&
+    stat.digest === fileRef.digest &&
+    stat.sizeBytes === fileRef.sizeBytes
+    ? stat
+    : null
+}
+
+/**
+ * Open a FileRef resolved from an authorized record, or return null when its blob is gone. The
+ * blob itself is opened on the body's first read, so a body nobody reads holds nothing.
+ */
+export async function openFileRef(
+  blobStorage: Pick<BlobStorage, "stat" | "open">,
+  fileRef: FileRef
+): Promise<OpenedFileRef | null> {
+  const stat = await statFileRef(blobStorage, fileRef)
+  if (!stat) return null
+  return { fileRef, body: openOnFirstRead(blobStorage, fileRef.blobId) }
+}
+
+function openOnFirstRead(
+  blobStorage: Pick<BlobStorage, "open">,
+  blobId: string
+): ReadableStream<Uint8Array> {
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined
+  return new ReadableStream<Uint8Array>(
+    {
+      async pull(controller) {
+        reader ??= (await blobStorage.open(blobId)).getReader()
+        const { done, value } = await reader.read()
+        if (done) controller.close()
+        else controller.enqueue(value)
+      },
+      async cancel(reason) {
+        await reader?.cancel(reason)
+      },
+    },
+    // No read-ahead: the first pull waits for the first read.
+    { highWaterMark: 0 }
+  )
+}
+
+/** Escape one segment of a JSON Pointer. */
+export function jsonPointerSegment(segment: string | number): string {
+  return String(segment).replaceAll("~", "~0").replaceAll("/", "~1")
+}
+
+function resolveJsonPointer(root: unknown, pointer: string): unknown {
+  if (pointer === "") {
+    return root
+  }
+
+  if (!pointer.startsWith("/")) {
+    return undefined
+  }
+
+  let current = root
+  for (const rawSegment of pointer.slice(1).split("/")) {
+    const segment = decodeJsonPointerSegment(rawSegment)
+    if (Array.isArray(current)) {
+      const index = Number.parseInt(segment, 10)
+      if (!Number.isInteger(index) || index < 0 || index.toString() !== segment) {
+        return undefined
+      }
+      if (!Object.hasOwn(current, segment)) {
+        return undefined
+      }
+      current = current[index]
+      continue
+    }
+
+    if (typeof current !== "object" || current === null || !Object.hasOwn(current, segment)) {
+      return undefined
+    }
+
+    current = (current as Record<string, unknown>)[segment]
+  }
+
+  return current
+}
+
+function decodeJsonPointerSegment(segment: string): string {
+  return segment.replaceAll("~1", "/").replaceAll("~0", "~")
+}

package/src/blob-storage/index.ts

@@ -21,6 +21,7 @@ export type {
   DirectPutBlobUploadSession,
   DirectUploadBlobStorage,
   MultipartBlobUploadSession,
+  OpenedFileRef,
   PutBlobInput,
   RangeReadableBlobStorage,
   SignBlobUploadPartInput,

package/src/blob-storage/internal.ts

@@ -1 +1,8 @@
 export { FILE_DOWNLOAD_ROUTE_PREFIX, resolveFileDownload } from "./download-urls"
+export {
+  jsonPointerSegment,
+  openFileRef,
+  resolveFileRefAtPath,
+  statFileRef,
+} from "./file-content"
+export { canonicalMediaType } from "./media-type"

package/src/blob-storage/media-type.ts

@@ -0,0 +1,29 @@
+// One media type as RFC 9110 defines it: `type/subtype`, each a token, then optional
+// `;name=value` parameters whose value is a token or a quoted string. Stricter than the RFC where
+// leniency only invites a second reading: no surrounding whitespace, no empty parameters, no
+// escapes, and no comma anywhere. Browsers read a comma-separated value as a list of types and
+// use the last valid one, so a value with a comma can mean something other than its first type.
+const TOKEN = "[!#$%&'*+.^_`|~0-9A-Za-z-]+"
+const QUOTED_STRING = '"[\\t\\x20\\x21\\x23-\\x2b\\x2d-\\x5b\\x5d-\\x7e]*"'
+const PARAMETER = `[\\t ]*;[\\t ]*(${TOKEN})=(${TOKEN}|${QUOTED_STRING})`
+const MEDIA_TYPE_PATTERN = new RegExp(`^(${TOKEN})/(${TOKEN})((?:${PARAMETER})*)$`)
+const PARAMETER_PATTERN = new RegExp(PARAMETER, "g")
+
+/**
+ * The canonical form of a single well-formed media type, or `null` for anything else.
+ *
+ * Type, subtype, and parameter names are case-insensitive, so they are lowercased; parameter
+ * values keep their case. `"Text/Plain; Charset=UTF-8"` becomes `"text/plain;charset=UTF-8"`.
+ */
+export function canonicalMediaType(value: unknown): string | null {
+  if (typeof value !== "string") return null
+  const match = MEDIA_TYPE_PATTERN.exec(value)
+  if (!match) return null
+
+  const [, type, subtype, parameters] = match
+  let canonical = `${type.toLowerCase()}/${subtype.toLowerCase()}`
+  for (const [, name, parameterValue] of parameters.matchAll(PARAMETER_PATTERN)) {
+    canonical += `;${name.toLowerCase()}=${parameterValue}`
+  }
+  return canonical
+}

package/src/blob-storage/types.ts

@@ -7,7 +7,9 @@ export type BlobDigest = `sha256:${string}`
  * `blobId` is always `blob_<sha256 hex>` derived from `digest`. `fileName`,
  * `mediaType`, and `logicalPath` are caller-supplied per-reference metadata (not
  * part of blob identity) and are untrusted — consumers must sanitize them before
- * using them for paths, headers, or rendering.
+ * using them for paths, headers, or rendering. A caller storing a reference must give a
+ * single media type such as `image/png` (`isValidFileRef`); references stored earlier may
+ * hold anything, so file routes re-parse it before serving.
  */
 export interface FileRef {
   readonly blobId: string
@@ -20,6 +22,16 @@ export interface FileRef {
 
 export type BlobBody = ArrayBuffer | Uint8Array | Blob | ReadableStream<Uint8Array>
 
+/** A FileRef opened through the record that references it. */
+export interface OpenedFileRef {
+  readonly fileRef: FileRef
+  /**
+   * The file's bytes. The stored blob is opened on the first read: read the body to its end or
+   * cancel it, and a body never read holds nothing.
+   */
+  readonly body: ReadableStream<Uint8Array>
+}
+
 export interface PutBlobInput {
   readonly body: BlobBody
   /** Reject the write when the consumed byte count differs from this value. */

package/src/blob-storage/validation.ts

@@ -1,5 +1,6 @@
 import { isPlainRecord } from "../json"
 import { blobIdFromDigest } from "./derive"
+import { canonicalMediaType } from "./media-type"
 import type {
   BlobDigest,
   BlobStorage,
@@ -30,6 +31,18 @@ export function isFileRef(value: unknown): value is FileRef {
   )
 }
 
+/**
+ * `isFileRef`, plus a `mediaType` that, when present, is exactly one media type. Paths that store
+ * a reference a caller hands them use this. Reads keep `isFileRef`, so references stored before
+ * the rule still load; file routes re-parse the type before serving it.
+ */
+export function isValidFileRef(value: unknown): value is FileRef {
+  return (
+    isFileRef(value) &&
+    (value.mediaType === undefined || canonicalMediaType(value.mediaType) !== null)
+  )
+}
+
 export function supportsDirectUpload(
   storage: BlobStorage
 ): storage is BlobStorage & DirectUploadBlobStorage {