@sixb/core 0.0.1

package/src/agents/types.ts

@@ -0,0 +1,70 @@
+import type { LanguageModelV4, LanguageModelV4CallOptions } from "@ai-sdk/provider"
+import type { GroupDefinition } from "../security"
+
+export type {
+  AgentContextEntryInput,
+  AgentContextInput,
+  AgentContextOrigin,
+  AgentContextPart,
+} from "./context"
+
+export type AgentReasoningLevel = NonNullable<LanguageModelV4CallOptions["reasoning"]>
+
+export const AGENT_REASONING_LEVELS = [
+  "provider-default",
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const satisfies readonly AgentReasoningLevel[]
+
+/**
+ * Loop / stop controls for an agent run.
+ *
+ * Consumed by the agent worker when it executes a run.
+ */
+export interface AgentLoopConfig {
+  readonly stopWhen?: {
+    readonly maxSteps?: number
+  }
+}
+
+/**
+ * Declarative config accepted by {@link defineAgent}.
+ *
+ * Every field is a static value. `instructions` is a plain string; widening it to
+ * `string | (ctx) => string` later would be backwards-compatible.
+ */
+export interface DefineAgentConfig {
+  readonly name: string
+  readonly description?: string
+  readonly model: LanguageModelV4
+  readonly reasoning?: AgentReasoningLevel
+  readonly providerOptions?: LanguageModelV4CallOptions["providerOptions"]
+  readonly instructions: string
+  readonly groups?: readonly GroupDefinition[]
+  readonly loop?: AgentLoopConfig
+}
+
+/**
+ * Agent definition registered with Sixb.
+ *
+ * Definitions are safe to export from `agents/` modules; the runtime loads and
+ * registers them. The agent worker runs them as streaming turns. The `model` is an
+ * AI SDK language model instance and is therefore not serialisable — the worker
+ * resolves a definition from its own discovery rather than over the wire.
+ */
+export interface AgentDefinition<TId extends string = string> {
+  readonly kind: "agent"
+  readonly id: TId
+  readonly name: string
+  readonly description?: string
+  readonly model: LanguageModelV4
+  readonly reasoning?: AgentReasoningLevel
+  readonly providerOptions?: LanguageModelV4CallOptions["providerOptions"]
+  readonly instructions: string
+  readonly groupIds: readonly string[]
+  readonly loop?: AgentLoopConfig
+}

package/src/agents/validation.ts

@@ -0,0 +1,151 @@
+import { getInvalidJsonValueReason } from "../json"
+import type { GroupDefinition, SecurityRegistry } from "../security"
+import { AgentDefinitionError } from "./errors"
+import {
+  AGENT_REASONING_LEVELS,
+  type AgentDefinition,
+  type AgentLoopConfig,
+  type AgentReasoningLevel,
+  type DefineAgentConfig,
+} from "./types"
+
+export function assertNonEmpty(value: string, field: string): void {
+  if (!value.trim()) {
+    throw new AgentDefinitionError(`[Sixb] Agent ${field} must not be empty.`)
+  }
+}
+
+export function isAgentDefinition(value: unknown): value is AgentDefinition {
+  return (
+    isRecord(value) &&
+    value.kind === "agent" &&
+    typeof value.id === "string" &&
+    typeof value.name === "string" &&
+    typeof value.instructions === "string" &&
+    (value.reasoning === undefined || isAgentReasoningLevel(value.reasoning)) &&
+    (value.providerOptions === undefined || isProviderOptions(value.providerOptions)) &&
+    Array.isArray(value.groupIds)
+  )
+}
+
+export function assertValidLoopConfig(loop: AgentLoopConfig | undefined): void {
+  const maxSteps = loop?.stopWhen?.maxSteps
+  if (maxSteps === undefined) {
+    return
+  }
+  if (!Number.isInteger(maxSteps) || maxSteps <= 0) {
+    throw new AgentDefinitionError(
+      "[Sixb] Agent loop.stopWhen.maxSteps must be a positive finite integer."
+    )
+  }
+}
+
+export function assertValidReasoningLevel(reasoning: AgentReasoningLevel | undefined): void {
+  if (reasoning === undefined) {
+    return
+  }
+  if (!isAgentReasoningLevel(reasoning)) {
+    throw new AgentDefinitionError(
+      `[Sixb] Agent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}.`
+    )
+  }
+}
+
+export function assertValidProviderOptions(
+  providerOptions: DefineAgentConfig["providerOptions"]
+): void {
+  if (providerOptions === undefined) {
+    return
+  }
+
+  const reason = getInvalidJsonValueReason(providerOptions, "providerOptions")
+  if (!isRecord(providerOptions) || reason) {
+    throw new AgentDefinitionError(
+      `[Sixb] Agent providerOptions must be a provider-keyed JSON object${reason ? `; ${reason}` : "."}`
+    )
+  }
+
+  for (const [provider, options] of Object.entries(providerOptions)) {
+    if (!provider.trim()) {
+      throw new AgentDefinitionError(
+        "[Sixb] Agent providerOptions provider names must not be empty."
+      )
+    }
+    const optionsReason = getInvalidJsonValueReason(options, `providerOptions.${provider}`)
+    if (!isRecord(options) || optionsReason) {
+      throw new AgentDefinitionError(
+        `[Sixb] Agent providerOptions.${provider} must be a JSON object${optionsReason ? `; ${optionsReason}` : "."}`
+      )
+    }
+  }
+}
+
+export function groupIdsFromDefinitions(
+  agentId: string,
+  groups: readonly GroupDefinition[] | undefined
+): readonly string[] {
+  const groupIds = (groups ?? []).map((group) => {
+    if (!isRecord(group) || group.kind !== "group") {
+      throw new AgentDefinitionError(
+        `[Sixb] Agent '${agentId}' groups must contain only group definitions.`
+      )
+    }
+
+    assertNonEmpty(group.id, `Agent '${agentId}' group id`)
+    return group.id
+  })
+
+  assertNoDuplicateGroupIds(agentId, groupIds)
+  return groupIds
+}
+
+export function validateAgentGroupReferences(
+  agents: readonly AgentDefinition[],
+  security: SecurityRegistry
+): void {
+  for (const agent of agents) {
+    assertNoDuplicateGroupIds(agent.id, agent.groupIds)
+    for (const groupId of agent.groupIds) {
+      if (!security.getGroupById(groupId)) {
+        throw new AgentDefinitionError(
+          `[Sixb] Agent '${agent.id}' groups references unknown group '${groupId}'. Add it to 'security/groups/' or pass it to createSixb({ groups }).`
+        )
+      }
+    }
+  }
+}
+
+function assertNoDuplicateGroupIds(agentId: string, groupIds: readonly string[]): void {
+  const seen = new Set<string>()
+  for (const groupId of groupIds) {
+    assertNonEmpty(groupId, `Agent '${agentId}' group id`)
+    if (seen.has(groupId)) {
+      throw new AgentDefinitionError(
+        `[Sixb] Agent '${agentId}' groups contains duplicate group id '${groupId}'.`
+      )
+    }
+    seen.add(groupId)
+  }
+}
+
+function isAgentReasoningLevel(value: unknown): value is AgentReasoningLevel {
+  return typeof value === "string" && (AGENT_REASONING_LEVELS as readonly string[]).includes(value)
+}
+
+function isProviderOptions(
+  value: unknown
+): value is NonNullable<DefineAgentConfig["providerOptions"]> {
+  if (!isRecord(value) || getInvalidJsonValueReason(value) !== undefined) {
+    return false
+  }
+  return Object.entries(value).every(
+    ([provider, options]) =>
+      provider.trim().length > 0 &&
+      isRecord(options) &&
+      getInvalidJsonValueReason(options) === undefined
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}

package/src/auth/access-tokens.ts

@@ -0,0 +1,125 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto"
+
+export const PERSONAL_ACCESS_TOKEN_PREFIX = "sixb_pat"
+export const SERVICE_ACCOUNT_ACCESS_TOKEN_PREFIX = "sixb_sat"
+
+// The token prefix makes credentials self-identifying for operators and logs.
+// Validity, revocation, expiration, and permissions still come from storage.
+export type AccessTokenKind = "personal" | "serviceAccount"
+
+export interface AccessTokenParts {
+  readonly kind: AccessTokenKind
+  readonly tokenId: string
+  readonly tokenSecret: string
+}
+
+export interface AccessTokenCredential extends AccessTokenParts {
+  readonly tokenHash: string
+  readonly tokenValue: string
+}
+
+const ACCESS_TOKEN_ID_PATTERN = /^tok_[A-Za-z0-9_-]+$/
+const ACCESS_TOKEN_SECRET_PATTERN = /^[A-Za-z0-9_-]{32,}$/
+
+export function generateAccessTokenSecret(): string {
+  return randomBytes(32).toString("base64url")
+}
+
+export function hashAccessTokenSecret(secret: string): string {
+  return createHash("sha256").update(secret).digest("hex")
+}
+
+export function formatAccessTokenValue(
+  kind: AccessTokenKind,
+  tokenId: string,
+  tokenSecret: string
+): string {
+  const prefix = accessTokenPrefixForKind(kind)
+
+  if (!ACCESS_TOKEN_ID_PATTERN.test(tokenId)) {
+    throw new Error("[Sixb] Access token ids must start with 'tok_' and be URL-safe.")
+  }
+
+  if (!ACCESS_TOKEN_SECRET_PATTERN.test(tokenSecret)) {
+    throw new Error("[Sixb] Access token secrets must be at least 32 URL-safe characters.")
+  }
+
+  return `${prefix}_${tokenId}.${tokenSecret}`
+}
+
+export function parseAccessTokenValue(value: string | undefined): AccessTokenParts | null {
+  // Parsing is intentionally non-throwing so auth paths can treat malformed
+  // credentials exactly like missing credentials.
+  if (!value) {
+    return null
+  }
+
+  const firstDot = value.indexOf(".")
+  if (firstDot <= 0 || firstDot !== value.lastIndexOf(".") || firstDot === value.length - 1) {
+    return null
+  }
+
+  const tokenLabel = value.slice(0, firstDot)
+  const tokenSecret = value.slice(firstDot + 1)
+  const kind = accessTokenKindFromLabel(tokenLabel)
+  if (!kind || !ACCESS_TOKEN_SECRET_PATTERN.test(tokenSecret)) {
+    return null
+  }
+
+  const tokenId = tokenLabel.slice(`${accessTokenPrefixForKind(kind)}_`.length)
+  if (!ACCESS_TOKEN_ID_PATTERN.test(tokenId)) {
+    return null
+  }
+
+  return { kind, tokenId, tokenSecret }
+}
+
+export function getBearerAccessTokenValue(request: Request): string | null {
+  const header = request.headers.get("authorization")
+  if (!header) {
+    return null
+  }
+
+  const [scheme, token, extra] = header.trim().split(/\s+/)
+  if (scheme?.toLowerCase() !== "bearer" || !token || extra) {
+    return null
+  }
+
+  return token
+}
+
+export function createAccessTokenCredential(
+  kind: AccessTokenKind,
+  tokenId = `tok_${randomUUID()}`
+): AccessTokenCredential {
+  const tokenSecret = generateAccessTokenSecret()
+  // Callers should return tokenValue once, then persist only tokenHash.
+  return {
+    kind,
+    tokenId,
+    tokenSecret,
+    tokenHash: hashAccessTokenSecret(tokenSecret),
+    tokenValue: formatAccessTokenValue(kind, tokenId, tokenSecret),
+  }
+}
+
+function accessTokenPrefixForKind(kind: AccessTokenKind): string {
+  switch (kind) {
+    case "personal":
+      return PERSONAL_ACCESS_TOKEN_PREFIX
+    case "serviceAccount":
+      return SERVICE_ACCOUNT_ACCESS_TOKEN_PREFIX
+  }
+}
+
+function accessTokenKindFromLabel(label: string): AccessTokenKind | null {
+  if (label.startsWith(`${PERSONAL_ACCESS_TOKEN_PREFIX}_`)) {
+    return "personal"
+  }
+
+  if (label.startsWith(`${SERVICE_ACCOUNT_ACCESS_TOKEN_PREFIX}_`)) {
+    return "serviceAccount"
+  }
+
+  return null
+}

package/src/auth/audience.ts

@@ -0,0 +1,28 @@
+import { AuthRuntimeError } from "./errors"
+
+export const DEFAULT_AUTH_SESSION_AUDIENCE = "atlas"
+
+export type AuthSessionAudience = typeof DEFAULT_AUTH_SESSION_AUDIENCE | "app"
+
+export interface AuthSessionAudienceOptions {
+  readonly audience?: AuthSessionAudience
+}
+
+export function isValidAuthSessionAudience(value: string): value is AuthSessionAudience {
+  return value === "atlas" || value === "app"
+}
+
+export function resolveAuthSessionAudience(
+  value: AuthSessionAudience | undefined
+): AuthSessionAudience {
+  const audience = value ?? DEFAULT_AUTH_SESSION_AUDIENCE
+
+  if (!isValidAuthSessionAudience(audience)) {
+    throw new AuthRuntimeError(
+      "invalid_auth_config",
+      `[Sixb] Auth session audience '${audience}' is invalid. Expected 'atlas' or 'app'.`
+    )
+  }
+
+  return audience
+}

package/src/auth/cookies.ts

@@ -0,0 +1,263 @@
+import type { AuthSessionAudience } from "./audience"
+import { DEFAULT_AUTH_SESSION_AUDIENCE, resolveAuthSessionAudience } from "./audience"
+import type { AuthCookieOptions } from "./types"
+
+export const DEFAULT_SESSION_COOKIE_NAME = "sixb_session"
+export const DEFAULT_CSRF_COOKIE_NAME = "sixb_csrf"
+
+export interface ResolvedAuthCookieOptions {
+  readonly sessionCookieName: string
+  readonly csrfCookieName: string
+  readonly domain?: string
+  readonly secure: boolean | "auto"
+  readonly sameSite: "strict"
+  readonly csrfHttpOnly: boolean
+}
+
+interface CookieSerializationOptions {
+  readonly name: string
+  readonly value: string
+  readonly httpOnly?: boolean
+  readonly maxAge?: number
+  readonly expires?: Date
+  readonly domain?: string
+  readonly secure?: boolean
+  readonly sameSite: "strict"
+}
+
+export function resolveAuthCookieOptions(
+  options: AuthCookieOptions | undefined
+): ResolvedAuthCookieOptions {
+  const resolved = {
+    sessionCookieName: options?.sessionCookieName ?? DEFAULT_SESSION_COOKIE_NAME,
+    csrfCookieName: options?.csrfCookieName ?? DEFAULT_CSRF_COOKIE_NAME,
+    domain: options?.cookieDomain,
+    secure: options?.secure ?? "auto",
+    sameSite: options?.sameSite ?? "strict",
+    csrfHttpOnly: options?.csrfHttpOnly ?? false,
+  }
+
+  assertValidCookieOptions(resolved)
+  return resolved
+}
+
+export function resolveAuthCookieOptionsForAudience(
+  options: ResolvedAuthCookieOptions,
+  audience: AuthSessionAudience | undefined
+): ResolvedAuthCookieOptions {
+  const resolvedAudience = resolveAuthSessionAudience(audience)
+  if (resolvedAudience === DEFAULT_AUTH_SESSION_AUDIENCE) {
+    return options
+  }
+
+  return {
+    ...options,
+    sessionCookieName: `${options.sessionCookieName}_${resolvedAudience}`,
+    csrfCookieName: `${options.csrfCookieName}_${resolvedAudience}`,
+  }
+}
+
+export function parseCookieHeader(header: string | null): ReadonlyMap<string, string> {
+  const cookies = new Map<string, string>()
+  if (!header) {
+    return cookies
+  }
+
+  for (const part of header.split(";")) {
+    const separator = part.indexOf("=")
+    if (separator <= 0) {
+      continue
+    }
+
+    const name = part.slice(0, separator).trim()
+    if (!name || cookies.has(name)) {
+      continue
+    }
+
+    const value = part.slice(separator + 1).trim()
+    cookies.set(name, value)
+  }
+
+  return cookies
+}
+
+export function getCookie(request: Request, name: string): string | undefined {
+  return parseCookieHeader(request.headers.get("cookie")).get(name)
+}
+
+export function serializeCookie(options: CookieSerializationOptions): string {
+  const parts = [`${options.name}=${options.value}`]
+
+  parts.push("Path=/")
+  parts.push("SameSite=Strict")
+
+  if (options.domain) {
+    parts.push(`Domain=${options.domain}`)
+  }
+
+  if (options.httpOnly) {
+    parts.push("HttpOnly")
+  }
+
+  if (options.secure) {
+    parts.push("Secure")
+  }
+
+  if (options.maxAge !== undefined) {
+    parts.push(`Max-Age=${Math.trunc(options.maxAge)}`)
+  }
+
+  if (options.expires) {
+    parts.push(`Expires=${options.expires.toUTCString()}`)
+  }
+
+  return parts.join("; ")
+}
+
+export function shouldUseSecureCookies(
+  request: Request,
+  options: ResolvedAuthCookieOptions
+): boolean {
+  if (
+    requiresSecureCookieName(options.sessionCookieName) ||
+    requiresSecureCookieName(options.csrfCookieName)
+  ) {
+    return true
+  }
+
+  if (typeof options.secure === "boolean") {
+    return options.secure
+  }
+
+  const url = new URL(request.url)
+  if (isLocalhost(url.hostname)) {
+    return false
+  }
+
+  return url.protocol === "https:" || process.env.NODE_ENV === "production"
+}
+
+export function createSessionCookieHeader(params: {
+  readonly request: Request
+  readonly value: string
+  readonly expiresAt: Date
+  readonly options: ResolvedAuthCookieOptions
+}): string {
+  const lifetime = resolveCookieLifetime(params.expiresAt)
+  return serializeCookie({
+    name: params.options.sessionCookieName,
+    value: params.value,
+    httpOnly: true,
+    ...lifetime,
+    domain: params.options.domain,
+    secure: shouldUseSecureCookies(params.request, params.options),
+    sameSite: params.options.sameSite,
+  })
+}
+
+export function createCsrfCookieHeader(params: {
+  readonly request: Request
+  readonly value: string
+  readonly expiresAt: Date
+  readonly options: ResolvedAuthCookieOptions
+}): string {
+  const lifetime = resolveCookieLifetime(params.expiresAt)
+  return serializeCookie({
+    name: params.options.csrfCookieName,
+    value: params.value,
+    httpOnly: params.options.csrfHttpOnly,
+    ...lifetime,
+    domain: params.options.domain,
+    secure: shouldUseSecureCookies(params.request, params.options),
+    sameSite: params.options.sameSite,
+  })
+}
+
+function resolveCookieLifetime(expiresAt: Date): {
+  readonly maxAge: number
+  readonly expires: Date
+} {
+  const expiresAtMs = expiresAt.getTime()
+  if (!Number.isFinite(expiresAtMs)) {
+    throw new Error("[Sixb] Auth cookie expiresAt must be a valid date.")
+  }
+
+  return {
+    maxAge: Math.max(0, Math.floor((expiresAtMs - Date.now()) / 1000)),
+    expires: new Date(expiresAtMs),
+  }
+}
+
+export function clearSessionCookieHeader(params: {
+  readonly request: Request
+  readonly options: ResolvedAuthCookieOptions
+}): string {
+  return serializeCookie({
+    name: params.options.sessionCookieName,
+    value: "",
+    httpOnly: true,
+    maxAge: 0,
+    expires: new Date(0),
+    domain: params.options.domain,
+    secure: shouldUseSecureCookies(params.request, params.options),
+    sameSite: params.options.sameSite,
+  })
+}
+
+export function clearCsrfCookieHeader(params: {
+  readonly request: Request
+  readonly options: ResolvedAuthCookieOptions
+}): string {
+  return serializeCookie({
+    name: params.options.csrfCookieName,
+    value: "",
+    maxAge: 0,
+    expires: new Date(0),
+    domain: params.options.domain,
+    secure: shouldUseSecureCookies(params.request, params.options),
+    sameSite: params.options.sameSite,
+  })
+}
+
+function isLocalhost(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1"
+}
+
+function assertValidCookieOptions(options: ResolvedAuthCookieOptions): void {
+  assertValidCookieName(options.sessionCookieName, "sessionCookieName")
+  assertValidCookieName(options.csrfCookieName, "csrfCookieName")
+
+  if (options.sameSite !== "strict") {
+    throw new Error("[Sixb] Auth cookie sameSite must be 'strict'.")
+  }
+
+  if (
+    options.domain &&
+    (isHostPrefixedCookieName(options.sessionCookieName) ||
+      isHostPrefixedCookieName(options.csrfCookieName))
+  ) {
+    throw new Error("[Sixb] __Host- auth cookies cannot be configured with cookieDomain.")
+  }
+
+  if (
+    options.secure === false &&
+    (requiresSecureCookieName(options.sessionCookieName) ||
+      requiresSecureCookieName(options.csrfCookieName))
+  ) {
+    throw new Error("[Sixb] __Host- auth cookies require secure cookies.")
+  }
+}
+
+function assertValidCookieName(name: string, label: string): void {
+  if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name)) {
+    throw new Error(`[Sixb] Auth cookie ${label} '${name}' is not a valid cookie name.`)
+  }
+}
+
+function isHostPrefixedCookieName(name: string): boolean {
+  return name.startsWith("__Host-")
+}
+
+function requiresSecureCookieName(name: string): boolean {
+  return isHostPrefixedCookieName(name) || name.startsWith("__Secure-")
+}

package/src/auth/csrf.ts

@@ -0,0 +1,41 @@
+import { randomBytes, timingSafeEqual } from "node:crypto"
+import { getCookie } from "./cookies"
+
+export const CSRF_HEADER_NAME = "x-sixb-csrf"
+
+export function generateCsrfToken(): string {
+  return randomBytes(32).toString("base64url")
+}
+
+export function isCsrfExemptMethod(method: string): boolean {
+  const normalized = method.toUpperCase()
+  return normalized === "GET" || normalized === "HEAD" || normalized === "OPTIONS"
+}
+
+export function verifyDoubleSubmitCsrf(
+  request: Request,
+  options: { readonly cookieName: string; readonly headerName?: string }
+): boolean {
+  if (isCsrfExemptMethod(request.method)) {
+    return true
+  }
+
+  const cookieValue = getCookie(request, options.cookieName)
+  const headerValue = request.headers.get(options.headerName ?? CSRF_HEADER_NAME)
+
+  if (!cookieValue || !headerValue) {
+    return false
+  }
+
+  return safeEqual(cookieValue, headerValue)
+}
+
+function safeEqual(left: string, right: string): boolean {
+  const leftBytes = Buffer.from(left)
+  const rightBytes = Buffer.from(right)
+  if (leftBytes.length !== rightBytes.length) {
+    return false
+  }
+
+  return timingSafeEqual(leftBytes, rightBytes)
+}

package/src/auth/errors.ts

@@ -0,0 +1,19 @@
+export type AuthRuntimeErrorCode =
+  | "authentication_required"
+  | "auth_storage_missing"
+  | "authorization_denied"
+  | "invalid_auth_input"
+  | "invalid_auth_config"
+  | "rate_limited"
+  | "production_auth_required"
+
+export class AuthRuntimeError extends Error {
+  readonly name = "AuthRuntimeError"
+
+  constructor(
+    readonly code: AuthRuntimeErrorCode,
+    message: string
+  ) {
+    super(message)
+  }
+}