@sixb/core 0.1.0 → 0.1.2

package/src/agents/validation.ts

@@ -1,14 +1,38 @@
-import { getInvalidJsonValueReason } from "../json"
-import type { GroupDefinition, SecurityRegistry } from "../security"
+import { getInvalidJsonValueReason, isPlainRecord, type JsonValue } from "../json"
+import {
+  normalizeSchemaValue,
+  type ObjectSchema,
+  OntologyValidationError,
+  type ValueType,
+  validateSchemaValue,
+} from "../ontology"
+import type { GroupDefinition, SecurityDefinitionCatalog } from "../security"
 import { AgentDefinitionError } from "./errors"
 import {
   AGENT_REASONING_LEVELS,
   type AgentDefinition,
   type AgentLoopConfig,
   type AgentReasoningLevel,
+  type AgentToolDefinition,
+  type AgentToolInputSchema,
   type DefineAgentConfig,
 } from "./types"
 
+const AGENT_TOOL_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/
+const AGENT_TOOL_PRIMITIVE_SCHEMAS = new Set([
+  "string",
+  "integer",
+  "double",
+  "decimal",
+  "boolean",
+  "date",
+  "timestamp",
+  "uuid",
+  "fileRef",
+])
+
+export const AGENT_RESERVED_TOOL_NAMES = ["bash", "read"] as const
+
 export function assertNonEmpty(value: string, field: string): void {
   if (!value.trim()) {
     throw new AgentDefinitionError(`[Sixb] Agent ${field} must not be empty.`)
@@ -24,10 +48,117 @@ export function isAgentDefinition(value: unknown): value is AgentDefinition {
     typeof value.instructions === "string" &&
     (value.reasoning === undefined || isAgentReasoningLevel(value.reasoning)) &&
     (value.providerOptions === undefined || isProviderOptions(value.providerOptions)) &&
-    Array.isArray(value.groupIds)
+    Array.isArray(value.groupIds) &&
+    isAgentToolDefinitionArray(value.tools)
+  )
+}
+
+export function isAgentToolDefinition(value: unknown): value is AgentToolDefinition {
+  return (
+    isRecord(value) &&
+    value.kind === "agentTool" &&
+    typeof value.name === "string" &&
+    typeof value.description === "string" &&
+    isPlainRecord(value.input) &&
+    typeof value.handler === "function"
+  )
+}
+
+export function assertValidAgentToolName(name: unknown): asserts name is string {
+  if (typeof name !== "string" || !AGENT_TOOL_NAME_PATTERN.test(name)) {
+    throw new AgentDefinitionError(
+      "[Sixb] Agent tool name must be 1-64 characters, start with a letter or underscore, and contain only letters, numbers, underscores, or hyphens."
+    )
+  }
+  if ((AGENT_RESERVED_TOOL_NAMES as readonly string[]).includes(name)) {
+    throw new AgentDefinitionError(`[Sixb] Agent tool name '${name}' is reserved by the framework.`)
+  }
+}
+
+export function assertValidAgentToolDescription(name: string, description: unknown): void {
+  if (typeof description !== "string" || !description.trim()) {
+    throw new AgentDefinitionError(`[Sixb] Agent tool '${name}' description must not be empty.`)
+  }
+}
+
+export function assertValidAgentToolInput(name: string, input: unknown): void {
+  if (!isPlainRecord(input)) {
+    throw new AgentDefinitionError(`[Sixb] Agent tool '${name}' input must be a schema object.`)
+  }
+
+  for (const [field, schema] of Object.entries(input)) {
+    if (!field.trim()) {
+      throw new AgentDefinitionError(
+        `[Sixb] Agent tool '${name}' input field names must not be empty.`
+      )
+    }
+    assertValidAgentToolSchema(name, schema, `input.${field}`, new Set())
+  }
+}
+
+export function validateAndSnapshotAgentToolInput<TInput extends AgentToolInputSchema>(
+  toolName: string,
+  input: TInput
+): TInput {
+  assertValidAgentToolInput(toolName, input)
+  try {
+    return deepFreeze(structuredClone(input))
+  } catch {
+    throw new AgentDefinitionError(
+      `[Sixb] Agent tool '${toolName}' input must be safely snapshot-compatible.`
+    )
+  }
+}
+
+/** Validate model input against a tool schema, normalize it to JSON, and lock the snapshot. */
+export function validateAndNormalizeAgentToolInput(
+  toolName: string,
+  shape: AgentToolInputSchema,
+  value: unknown,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): Record<string, JsonValue> {
+  const label = `Agent tool '${toolName}' input`
+  if (!isPlainRecord(value)) {
+    throw new OntologyValidationError(`[Sixb] ${label} must be a JSON object.`)
+  }
+
+  const reason = getInvalidJsonValueReason(value, label)
+  if (reason) {
+    throw new OntologyValidationError(`[Sixb] ${label} must be JSON-compatible; ${reason}.`)
+  }
+
+  const schema: ObjectSchema = {
+    type: "object",
+    properties: Object.fromEntries(
+      Object.entries(shape).map(([field, fieldSchema]) => [
+        field,
+        { schema: fieldSchema, required: true },
+      ])
+    ),
+  }
+  validateSchemaValue(schema, value, label, valueTypesById)
+  return deepFreeze(
+    normalizeSchemaValue(schema, value, label, valueTypesById) as Record<string, JsonValue>
   )
 }
 
+/** Revalidate and lock tool definitions supplied directly to the runtime. */
+export function validateAgentToolsAtStartup(agents: readonly AgentDefinition[]): void {
+  for (const agent of agents) {
+    if (!isAgentDefinition(agent)) {
+      throw new AgentDefinitionError("[Sixb] Agents must contain only valid agent definitions.")
+    }
+
+    assertValidAgentToolDefinitions(agent.id, agent.tools)
+    for (const tool of agent.tools) {
+      deepFreeze(tool.input)
+      Object.freeze(tool)
+    }
+    Object.freeze(agent.tools)
+    Object.freeze(agent)
+  }
+}
+
 export function assertValidLoopConfig(loop: AgentLoopConfig | undefined): void {
   const maxSteps = loop?.stopWhen?.maxSteps
   if (maxSteps === undefined) {
@@ -96,12 +227,12 @@ export function groupIdsFromDefinitions(
   })
 
   assertNoDuplicateGroupIds(agentId, groupIds)
-  return groupIds
+  return Object.freeze(groupIds)
 }
 
 export function validateAgentGroupReferences(
   agents: readonly AgentDefinition[],
-  security: SecurityRegistry
+  security: SecurityDefinitionCatalog
 ): void {
   for (const agent of agents) {
     assertNoDuplicateGroupIds(agent.id, agent.groupIds)
@@ -146,6 +277,159 @@ function isProviderOptions(
   )
 }
 
+function assertValidAgentToolSchema(
+  toolName: string,
+  schema: unknown,
+  path: string,
+  visiting: Set<object>
+): void {
+  if (typeof schema === "string") {
+    if (AGENT_TOOL_PRIMITIVE_SCHEMAS.has(schema)) {
+      return
+    }
+    throw invalidAgentToolSchema(toolName, path)
+  }
+  if (!isPlainRecord(schema) || typeof schema.type !== "string" || visiting.has(schema)) {
+    throw invalidAgentToolSchema(toolName, path)
+  }
+
+  visiting.add(schema)
+  switch (schema.type) {
+    case "enum": {
+      const values = schema.values
+      const validValues = isValidAgentToolEnumValues(values, schema.valueType)
+      if (!validValues || new Set(values).size !== values.length) {
+        throw invalidAgentToolSchema(toolName, path)
+      }
+      break
+    }
+    case "array":
+      assertValidAgentToolSchema(toolName, schema.items, `${path}.items`, visiting)
+      break
+    case "map":
+      if (schema.keySchema !== "string") {
+        throw invalidAgentToolSchema(toolName, path)
+      }
+      assertValidAgentToolSchema(toolName, schema.valueSchema, `${path}.valueSchema`, visiting)
+      break
+    case "object": {
+      if (!isPlainRecord(schema.properties)) {
+        throw invalidAgentToolSchema(toolName, path)
+      }
+      for (const [fieldId, field] of Object.entries(schema.properties)) {
+        if (!fieldId.trim() || !isPlainRecord(field) || !("schema" in field)) {
+          throw invalidAgentToolSchema(toolName, `${path}.properties.${fieldId}`)
+        }
+        if (
+          (field.required !== undefined && typeof field.required !== "boolean") ||
+          (field.nullable !== undefined && typeof field.nullable !== "boolean") ||
+          (field.description !== undefined &&
+            (typeof field.description !== "string" || !field.description.trim()))
+        ) {
+          throw invalidAgentToolSchema(toolName, `${path}.properties.${fieldId}`)
+        }
+        assertValidAgentToolSchema(
+          toolName,
+          field.schema,
+          `${path}.properties.${fieldId}.schema`,
+          visiting
+        )
+      }
+      break
+    }
+    case "valueTypeRef":
+      if (typeof schema.valueTypeId !== "string" || !schema.valueTypeId.trim()) {
+        throw invalidAgentToolSchema(toolName, path)
+      }
+      if (schema._resolved !== undefined) {
+        assertValidAgentToolSchema(toolName, schema._resolved, `${path}._resolved`, visiting)
+      }
+      break
+    default:
+      throw invalidAgentToolSchema(toolName, path)
+  }
+  visiting.delete(schema)
+}
+
+function invalidAgentToolSchema(toolName: string, path: string): AgentDefinitionError {
+  return new AgentDefinitionError(
+    `[Sixb] Agent tool '${toolName}' ${path} must be a valid Sixb schema.`
+  )
+}
+
+function isAgentToolDefinitionArray(value: unknown): value is readonly AgentToolDefinition[] {
+  if (!Array.isArray(value)) {
+    return false
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index) || !isAgentToolDefinition(value[index])) {
+      return false
+    }
+  }
+  return true
+}
+
+export function assertValidAgentToolDefinitions(
+  agentId: string,
+  tools: readonly AgentToolDefinition[]
+): void {
+  const seen = new Set<string>()
+  for (let index = 0; index < tools.length; index += 1) {
+    const tool = tools[index]
+    if (!Object.hasOwn(tools, index) || !isAgentToolDefinition(tool)) {
+      throw new AgentDefinitionError(
+        `[Sixb] Agent '${agentId}' tools must contain only agent tool definitions.`
+      )
+    }
+
+    assertValidAgentToolName(tool.name)
+    assertValidAgentToolDescription(tool.name, tool.description)
+    assertValidAgentToolInput(tool.name, tool.input)
+    if (seen.has(tool.name)) {
+      throw new AgentDefinitionError(
+        `[Sixb] Agent '${agentId}' tools contains duplicate tool name '${tool.name}'.`
+      )
+    }
+    seen.add(tool.name)
+  }
+}
+
+function isValidAgentToolEnumValues(values: unknown, valueType: unknown): values is unknown[] {
+  if (!Array.isArray(values) || values.length === 0) {
+    return false
+  }
+
+  for (let index = 0; index < values.length; index += 1) {
+    if (!Object.hasOwn(values, index)) {
+      return false
+    }
+    const value = values[index]
+    if (
+      valueType === "string"
+        ? typeof value !== "string"
+        : valueType !== "integer" || typeof value !== "number" || !Number.isInteger(value)
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
+function deepFreeze<T>(value: T, seen: Set<object> = new Set()): T {
+  if (value === null || typeof value !== "object" || seen.has(value)) {
+    return value
+  }
+
+  seen.add(value)
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)
+    if (descriptor && "value" in descriptor) {
+      deepFreeze(descriptor.value, seen)
+    }
+  }
+  return Object.freeze(value)
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value)
 }

package/src/auth/attribution.ts

@@ -0,0 +1,48 @@
+import { compareStrings } from "../json"
+import type { AuthStorage } from "../storage/auth"
+import type { Principal } from "./types"
+
+/**
+ * Resolve the durable group-membership snapshot used to attribute admitted work.
+ *
+ * Authorization contexts can carry a token-restricted subset of the principal's groups, so they
+ * are deliberately not accepted here. Accounting attribution comes from auth storage whenever it
+ * is configured. A system principal, or a runtime with no durable auth storage, has no groups.
+ */
+export async function snapshotRequesterGroupIds(input: {
+  readonly auth: AuthStorage | undefined
+  readonly projectId: string
+  readonly principal: Principal
+}): Promise<readonly string[]> {
+  if (input.principal.type === "system" || !input.auth) {
+    return []
+  }
+
+  const memberships =
+    input.principal.type === "user"
+      ? await input.auth.groupMemberships.listForUser({
+          projectId: input.projectId,
+          userId: input.principal.id,
+        })
+      : await input.auth.serviceAccountGroupMemberships.listForServiceAccount({
+          projectId: input.projectId,
+          serviceAccountId: input.principal.id,
+        })
+
+  return normalizeRequesterGroupIds(memberships.map((membership) => membership.groupId))
+}
+
+/** Validate and canonicalize an immutable requester-group snapshot at a storage boundary. */
+export function normalizeRequesterGroupIds(groupIds: readonly string[]): readonly string[] {
+  if (!Array.isArray(groupIds)) {
+    throw new TypeError("[Sixb] requesterGroupIds must be an array.")
+  }
+  const unique = new Set<string>()
+  for (const groupId of groupIds) {
+    if (typeof groupId !== "string" || groupId.trim().length === 0) {
+      throw new TypeError("[Sixb] requesterGroupIds entries must be nonblank.")
+    }
+    unique.add(groupId)
+  }
+  return [...unique].sort(compareStrings)
+}

package/src/auth/index.ts

@@ -9,6 +9,7 @@ export {
   parseAccessTokenValue,
   SERVICE_ACCOUNT_ACCESS_TOKEN_PREFIX,
 } from "./access-tokens"
+export { normalizeRequesterGroupIds, snapshotRequesterGroupIds } from "./attribution"
 export type { AuthSessionAudience, AuthSessionAudienceOptions } from "./audience"
 export {
   DEFAULT_AUTH_SESSION_AUDIENCE,

package/src/auth/runtime.ts

@@ -11,7 +11,7 @@ import {
   type MembershipPolicyScope,
   missingMembershipGroupIds,
   resolveMembershipPolicyScope,
-  type SecurityRegistry,
+  type SecurityDefinitionCatalog,
 } from "../security"
 import type { Storage } from "../storage"
 import {
@@ -120,14 +120,14 @@ const ACCESS_TOKEN_TOUCH_INTERVAL_MS = 60_000
 export interface AuthRuntimeOptions {
   readonly projectId: string
   readonly storage: Storage
-  readonly security: SecurityRegistry
+  readonly security: SecurityDefinitionCatalog
   readonly config?: SixbAuthConfig
 }
 
 export class AuthRuntime {
   private readonly projectId: string
   private readonly storage: Storage
-  private readonly security: SecurityRegistry
+  private readonly security: SecurityDefinitionCatalog
   private readonly config: ResolvedAuthConfig
   private readonly sessionCache: SessionCache | null
 
@@ -566,8 +566,8 @@ export class AuthRuntime {
   /**
    * Resolve the authenticated principal's authorization context for a request.
    *
-   * Grants resolve eagerly (`groups -> roles -> grants`, subtype-expanded), so
-   * the returned context supports synchronous set-lookup checks and `sixb.as()`.
+   * Grants resolve eagerly (`groups -> roles -> grants`, subtype-expanded), so the returned
+   * context supports synchronous checks when Core binds a request execution SDK.
    */
   async createAuthorizationContext(
     request: Request,

package/src/authorization/decision.ts

@@ -5,18 +5,17 @@
  * index. `can` (boolean) and `assertAuthorized` (throw) are the two ways to
  * consume a decision; every enforcement site goes through one of them.
  *
- * A missing authorization context means a privileged caller (raw `sixb`,
- * syncs, workers, tests) — everything is allowed. Scoped contexts are
- * default-deny: a request without a covering grant is denied.
- *
- * SECURITY — this makes "privileged" the silent default: any caller that
- * reaches a leaf without an authorization context bypasses all grant checks.
- * That is intended for internal callers, but it means HTTP routes serving
- * authenticated principals must go through the scoped runtime (`sixb.as(ctx)`),
- * never the raw runtime. See `RequestAuthState` in the server for the rule.
+ * Every protected leaf first resolves the opaque runtime capability. Missing, forged, or
+ * unregistered authority is denied; only an explicitly registered trusted or disabled execution
+ * is unrestricted.
  */
 
 import type { AuthSessionAudience } from "../auth/audience"
+import {
+  type ResolvedRuntimeAuthorization,
+  resolveRuntimeAuthorization,
+} from "../execution/authorization"
+import type { ExecutionContext, RuntimeAuthorization } from "../execution/types"
 import { AuthorizationError } from "./errors"
 import type { GrantKind } from "./grant-kinds"
 import type { AuthorizationContext, GrantIndex } from "./types"
@@ -34,6 +33,7 @@ export type AuthzRequest =
   | { readonly kind: "pipeline.run"; readonly pipelineId: string }
   | { readonly kind: "agent.run"; readonly agentId: string }
   | { readonly kind: "logs.observe" }
+  | { readonly kind: "connector.manage"; readonly connectorId: string }
   | { readonly kind: "object.query"; readonly touchedObjectTypeIds: readonly string[] }
 
 export interface AuthzDecision {
@@ -45,6 +45,7 @@ export interface AuthzDecision {
 }
 
 interface AuthorizedRuntime {
+  readonly runtimeAuthorization?: RuntimeAuthorization
   readonly authorization?: AuthorizationContext
 }
 
@@ -81,6 +82,8 @@ function atomsFor(request: AuthzRequest): readonly Atom[] {
       return [{ kind: "run:agent", id: request.agentId }]
     case "logs.observe":
       return [{ kind: "observe:logs", id: "logs" }]
+    case "connector.manage":
+      return [{ kind: "manage:connector", id: request.connectorId }]
     case "object.query":
       return request.touchedObjectTypeIds.map((id) => ({ kind: "view:object", id }))
   }
@@ -116,17 +119,33 @@ export function isAllowed(
 }
 
 export function assertAuthorized(runtime: AuthorizedRuntime, request: AuthzRequest): void {
-  const decision = evaluate(runtime.authorization, request)
+  const resolved = assertRuntimeAuthorizationBound(runtime)
+  const authorization = resolved.type === "principal" ? resolved.context : undefined
+  const decision = evaluate(authorization, request)
   if (decision.allowed) {
     return
   }
 
   throw new AuthorizationError(
     decision.missing[0] ?? request.kind,
-    deniedMessage(runtime.authorization, request)
+    deniedMessage(authorization, request)
   )
 }
 
+/** Resolve registered process-local authority before a protected leaf makes a decision. */
+export function assertRuntimeAuthorizationBound(
+  runtime: AuthorizedRuntime
+): Exclude<ResolvedRuntimeAuthorization, { readonly type: "denied" }> {
+  const resolved = resolveRuntimeAuthorization(runtime.runtimeAuthorization)
+  if (resolved.type === "denied") {
+    throw new AuthorizationError(
+      "runtime:unbound",
+      "[Sixb] Protected operations require a registered execution scope."
+    )
+  }
+  return resolved
+}
+
 /**
  * Assert a principal may write objects of this type.
  *
@@ -157,16 +176,56 @@ export function assertCanAppendTelemetry(runtime: AuthorizedRuntime, objectTypeI
   assertAuthorized(runtime, { kind: "telemetry.append", objectTypeId })
 }
 
+/** Assert a principal may manage lifecycle state for this connector definition. */
+export function assertCanManageConnector(runtime: AuthorizedRuntime, connectorId: string): void {
+  assertAuthorized(runtime, { kind: "connector.manage", connectorId })
+}
+
 /**
  * Fail closed for operations that have no grant semantics yet.
  *
  * One caller left — `listLinks`, whose rows reveal target types that no read grant covers. Object,
  * link, and telemetry writes moved to {@link assertCanEdit} / {@link assertCanAppendTelemetry}.
- * Keeps unsupported surfaces denied even if a scoped runtime context reaches a code path the scoped
- * SDK does not expose.
+ * Keeps unsupported surfaces denied even if a principal-bound runtime context reaches a code path
+ * the execution SDK does not expose.
  */
 export function assertPrivileged(runtime: AuthorizedRuntime, operation: string): void {
-  if (!runtime.authorization) {
+  const resolved = assertRuntimeAuthorizationBound(runtime)
+  if (resolved.type === "unrestricted") {
+    return
+  }
+
+  throw new AuthorizationError(
+    `privileged:${operation}`,
+    `[Sixb] Operation '${operation}' is not covered by scoped authorization grants.`
+  )
+}
+
+/**
+ * Assert access to process providers that trusted executions and genuine agent runs may use.
+ *
+ * Agent provenance alone is not authority: the registered capability must be bound to the exact
+ * same agent and run before this check succeeds.
+ */
+export function assertProviderAccess(
+  runtime: AuthorizedRuntime,
+  execution: ExecutionContext,
+  operation: string
+): void {
+  const resolved = assertRuntimeAuthorizationBound(runtime)
+  if (resolved.type === "unrestricted") {
+    return
+  }
+
+  const binding = resolved.executionBinding
+  const executor = execution.executor
+  if (
+    binding?.type === "agent" &&
+    executor.type === "agent" &&
+    binding.executionId === execution.id &&
+    binding.agentId === executor.agentId &&
+    binding.runId === executor.runId
+  ) {
     return
   }
 
@@ -204,6 +263,8 @@ function deniedMessage(
       return `[Sixb] Principal '${principalId}' is not allowed to run agent '${request.agentId}'.`
     case "logs.observe":
       return `[Sixb] Principal '${principalId}' is not allowed to observe project logs.`
+    case "connector.manage":
+      return `[Sixb] Principal '${principalId}' is not allowed to manage connector '${request.connectorId}'.`
     case "object.query": {
       // Name the first touched type the principal cannot view.
       const blocked = request.touchedObjectTypeIds.find(

package/src/authorization/grant-kinds.ts

@@ -22,6 +22,7 @@ export type GrantKind =
   | "run:pipeline"
   | "run:agent"
   | "observe:logs"
+  | "manage:connector"
 
 /** Registered id universes a grant kind ranges over, plus subtype expansion. */
 export interface GrantUniverse {
@@ -34,6 +35,7 @@ export interface GrantUniverse {
   readonly pipelineIds: ReadonlySet<string>
   readonly agentIds: ReadonlySet<string>
   readonly observableIds: ReadonlySet<string>
+  readonly connectorIds: ReadonlySet<string>
   readonly getSubTypes: (objectTypeId: string) => readonly string[]
 }
 
@@ -115,6 +117,11 @@ export const GRANT_KINDS: Record<GrantKind, GrantKindSpec> = {
     subject: "observability surface",
     fix: 'Use can.observe("logs").',
   },
+  "manage:connector": {
+    universeKey: "connectorIds",
+    subject: "connector",
+    fix: "Add it to 'connectors/' or pass it to createSixb({ connectors }).",
+  },
 }
 
 export const GRANT_KIND_KEYS = Object.keys(GRANT_KINDS) as readonly GrantKind[]
@@ -136,6 +143,8 @@ export function grantKindOf(grant: GrantDefinition): GrantKind {
       return `run:${grant.target}`
     case "observe":
       return "observe:logs"
+    case "manage":
+      return "manage:connector"
   }
 }
 

package/src/authorization/index.ts

@@ -4,7 +4,9 @@ export {
   assertAuthorized,
   assertCanAppendTelemetry,
   assertCanEdit,
+  assertCanManageConnector,
   assertPrivileged,
+  assertProviderAccess,
   evaluate,
   isAllowed,
 } from "./decision"