@sixb/core 0.0.1

package/src/auth/validation.ts

@@ -0,0 +1,241 @@
+import { resolveAuthCookieOptions } from "./cookies"
+import { AuthRuntimeError } from "./errors"
+import type {
+  AuthSessionOptions,
+  AuthStrategy,
+  InvitationDeliveryAuthStrategy,
+  MagicLinkAuthStrategy,
+  OidcAuthStrategy,
+  ResolvedAuthConfig,
+  SixbAuthConfig,
+} from "./types"
+
+const DAY = 24 * 60 * 60 * 1000
+
+export const DEFAULT_AUTH_SESSION_IDLE_TIMEOUT_MS = 30 * DAY
+export const DEFAULT_AUTH_SESSION_RENEWAL_WINDOW_MS = 7 * DAY
+export const DEFAULT_AUTH_INVITATION_TTL_MS = 7 * DAY
+export const MAX_AUTH_INVITATION_TTL_MS = 30 * DAY
+/**
+ * Default in-process session cache window. Short enough that a revoked session lingers
+ * only briefly, long enough to collapse a burst of requests to a single auth resolution.
+ */
+export const DEFAULT_AUTH_SESSION_CACHE_TTL_MS = 5_000
+
+export { resolveAuthSessionAudience } from "./audience"
+
+export function resolveAuthConfig(config: SixbAuthConfig | undefined): ResolvedAuthConfig {
+  if (!config) {
+    return {
+      strategy: null,
+      session: resolveAuthSessionOptions(undefined),
+      cookies: resolveAuthCookieOptions(undefined),
+    }
+  }
+
+  const strategy = "strategy" in config ? config.strategy : config
+  assertValidStrategy(strategy)
+
+  return {
+    strategy,
+    session: resolveAuthSessionOptions("strategy" in config ? config.session : undefined),
+    cookies: resolveAuthCookieOptions("strategy" in config ? config.cookies : undefined),
+  }
+}
+
+export function resolveInvitationExpiresAt(value: Date | undefined, now: Date): Date {
+  const expiresAt = value
+    ? new Date(value)
+    : new Date(now.getTime() + DEFAULT_AUTH_INVITATION_TTL_MS)
+  const expiresAtTime = expiresAt.getTime()
+
+  if (!Number.isFinite(expiresAtTime)) {
+    throw new AuthRuntimeError(
+      "invalid_auth_input",
+      "[Sixb] Invitation expiresAt must be a valid date."
+    )
+  }
+
+  if (expiresAtTime <= now.getTime()) {
+    throw new AuthRuntimeError(
+      "invalid_auth_input",
+      "[Sixb] Invitation expiresAt must be in the future."
+    )
+  }
+
+  if (expiresAtTime > now.getTime() + MAX_AUTH_INVITATION_TTL_MS) {
+    throw new AuthRuntimeError(
+      "invalid_auth_input",
+      "[Sixb] Invitation expiresAt must be no more than 30 days in the future."
+    )
+  }
+
+  return expiresAt
+}
+
+export function sanitizeReturnTo(value: string | undefined): string {
+  if (!value || !value.startsWith("/") || value.startsWith("//")) {
+    return "/"
+  }
+
+  try {
+    const parsed = new URL(value, "http://sixb.local")
+    if (parsed.origin !== "http://sixb.local") {
+      return "/"
+    }
+
+    return `${parsed.pathname}${parsed.search}${parsed.hash}`
+  } catch {
+    return "/"
+  }
+}
+
+export function assertNonEmpty(value: string, label: string): string {
+  const normalized = value.trim()
+  if (!normalized) {
+    throw new AuthRuntimeError("invalid_auth_input", `[Sixb] ${label} must be a non-empty string.`)
+  }
+  return normalized
+}
+
+export function normalizePagination(input: { readonly limit?: number; readonly offset?: number }): {
+  readonly limit?: number
+  readonly offset: number
+} {
+  if (input.limit !== undefined && (!Number.isInteger(input.limit) || input.limit < 0)) {
+    throw new AuthRuntimeError(
+      "invalid_auth_input",
+      "[Sixb] Invitation list limit must be a non-negative integer."
+    )
+  }
+
+  if (input.offset !== undefined && (!Number.isInteger(input.offset) || input.offset < 0)) {
+    throw new AuthRuntimeError(
+      "invalid_auth_input",
+      "[Sixb] Invitation list offset must be a non-negative integer."
+    )
+  }
+
+  return {
+    limit: input.limit,
+    offset: input.offset ?? 0,
+  }
+}
+
+function resolveAuthSessionOptions(
+  options: AuthSessionOptions | undefined
+): ResolvedAuthConfig["session"] {
+  const idleTimeoutMs = options?.idleTimeoutMs ?? DEFAULT_AUTH_SESSION_IDLE_TIMEOUT_MS
+  if (!Number.isFinite(idleTimeoutMs) || idleTimeoutMs <= 0) {
+    throw new AuthRuntimeError(
+      "invalid_auth_config",
+      "[Sixb] Auth session idleTimeoutMs must be a positive finite number."
+    )
+  }
+
+  const renewalWindowMs = options?.renewalWindowMs ?? DEFAULT_AUTH_SESSION_RENEWAL_WINDOW_MS
+  if (!Number.isFinite(renewalWindowMs) || renewalWindowMs <= 0) {
+    throw new AuthRuntimeError(
+      "invalid_auth_config",
+      "[Sixb] Auth session renewalWindowMs must be a positive finite number."
+    )
+  }
+  if (renewalWindowMs >= idleTimeoutMs) {
+    throw new AuthRuntimeError(
+      "invalid_auth_config",
+      "[Sixb] Auth session renewalWindowMs must be less than idleTimeoutMs."
+    )
+  }
+
+  const absoluteTimeoutMs = options?.absoluteTimeoutMs
+  if (
+    absoluteTimeoutMs !== undefined &&
+    (!Number.isFinite(absoluteTimeoutMs) || absoluteTimeoutMs <= 0)
+  ) {
+    throw new AuthRuntimeError(
+      "invalid_auth_config",
+      "[Sixb] Auth session absoluteTimeoutMs must be a positive finite number when configured."
+    )
+  }
+  if (absoluteTimeoutMs !== undefined && absoluteTimeoutMs < idleTimeoutMs) {
+    throw new AuthRuntimeError(
+      "invalid_auth_config",
+      "[Sixb] Auth session absoluteTimeoutMs must be greater than or equal to idleTimeoutMs."
+    )
+  }
+
+  const cacheTtlMs = options?.cacheTtlMs ?? DEFAULT_AUTH_SESSION_CACHE_TTL_MS
+  if (!Number.isFinite(cacheTtlMs) || cacheTtlMs < 0) {
+    throw new AuthRuntimeError(
+      "invalid_auth_config",
+      "[Sixb] Auth session cacheTtlMs must be a non-negative finite number."
+    )
+  }
+  if (cacheTtlMs >= renewalWindowMs) {
+    throw new AuthRuntimeError(
+      "invalid_auth_config",
+      "[Sixb] Auth session cacheTtlMs must be less than renewalWindowMs."
+    )
+  }
+
+  return {
+    idleTimeoutMs,
+    renewalWindowMs,
+    ...(absoluteTimeoutMs === undefined ? {} : { absoluteTimeoutMs }),
+    cacheTtlMs,
+  }
+}
+
+export function isMagicLinkAuthStrategy(
+  strategy: AuthStrategy | null
+): strategy is MagicLinkAuthStrategy {
+  if (!strategy || strategy.kind !== "magicLink") {
+    return false
+  }
+
+  const candidate = strategy as {
+    readonly requestMagicLink?: unknown
+    readonly completeMagicLinkSignIn?: unknown
+  }
+
+  return (
+    typeof candidate.requestMagicLink === "function" &&
+    typeof candidate.completeMagicLinkSignIn === "function"
+  )
+}
+
+export function isInvitationDeliveryAuthStrategy(
+  strategy: AuthStrategy | null
+): strategy is InvitationDeliveryAuthStrategy {
+  if (!strategy) {
+    return false
+  }
+
+  const candidate = strategy as {
+    readonly deliverInvitation?: unknown
+  }
+
+  return typeof candidate.deliverInvitation === "function"
+}
+
+export function isOidcAuthStrategy(strategy: AuthStrategy | null): strategy is OidcAuthStrategy {
+  if (!strategy || strategy.kind !== "oidc") {
+    return false
+  }
+
+  const candidate = strategy as {
+    readonly startOidcSignIn?: unknown
+    readonly completeOidcSignIn?: unknown
+  }
+
+  return (
+    typeof candidate.startOidcSignIn === "function" &&
+    typeof candidate.completeOidcSignIn === "function"
+  )
+}
+
+function assertValidStrategy(strategy: AuthStrategy): void {
+  if (!strategy.id.trim()) {
+    throw new AuthRuntimeError("invalid_auth_config", "[Sixb] Auth strategy id is required.")
+  }
+}

package/src/authorization/application-access.ts

@@ -0,0 +1,34 @@
+import type { AuthSessionAudience } from "../auth/audience"
+import { isAllowed } from "./decision"
+import type { AuthorizationContext, ResolvedRole } from "./types"
+
+/** Whether declaring roles has enabled an allowlist for an application. */
+export function isApplicationAccessControlled(
+  roles: readonly ResolvedRole[],
+  audience: AuthSessionAudience
+): boolean {
+  return roles.some((role) => role.grants["access:application"].has(audience))
+}
+
+/**
+ * Whether this principal may open this application.
+ *
+ * KNOWN LIMITATION (0.1.x): application access is the one capability that is **not** deny-by-default.
+ * While no role mentions an application, every authenticated principal may open it; the allowlist only
+ * switches on once some role grants it. Every other capability — `view`, `apply`, `run`, `observe` —
+ * denies unless granted, so this is the single asymmetry in the model.
+ *
+ * It is deliberate for now: flipping it would lock every project out of Atlas until it declares a role,
+ * including projects with no security definitions at all. Closing it means shipping a default grant with
+ * the scaffold first, and it is a breaking change for any project relying on the open default.
+ */
+export function canAccessApplication(
+  authorization: AuthorizationContext,
+  roles: readonly ResolvedRole[],
+  audience: AuthSessionAudience
+): boolean {
+  return (
+    !isApplicationAccessControlled(roles, audience) ||
+    isAllowed(authorization, { kind: "application.access", audience })
+  )
+}

package/src/authorization/decision.ts

@@ -0,0 +1,215 @@
+/**
+ * Authorization decisions for the core data path.
+ *
+ * `evaluate` is the single place that maps a request to the resolved grant
+ * 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.
+ */
+
+import type { AuthSessionAudience } from "../auth/audience"
+import { AuthorizationError } from "./errors"
+import type { GrantKind } from "./grant-kinds"
+import type { AuthorizationContext, GrantIndex } from "./types"
+
+/** Something a principal may attempt, paired with the resource it targets. */
+export type AuthzRequest =
+  | { readonly kind: "application.access"; readonly audience: AuthSessionAudience }
+  | { readonly kind: "object.view"; readonly objectTypeId: string }
+  | { readonly kind: "dataset.view"; readonly datasetId: string }
+  | { readonly kind: "object.edit"; readonly objectTypeId: string }
+  | { readonly kind: "telemetry.append"; readonly objectTypeId: string }
+  | { readonly kind: "action.apply"; readonly actionId: string }
+  | { readonly kind: "workflow.run"; readonly workflowId: string }
+  | { readonly kind: "sync.run"; readonly syncId: string }
+  | { readonly kind: "pipeline.run"; readonly pipelineId: string }
+  | { readonly kind: "agent.run"; readonly agentId: string }
+  | { readonly kind: "logs.observe" }
+  | { readonly kind: "object.query"; readonly touchedObjectTypeIds: readonly string[] }
+
+export interface AuthzDecision {
+  readonly allowed: boolean
+  /** Grant keys the request needs, e.g. `view:object:quote`. */
+  readonly requirements: readonly string[]
+  /** Required keys the principal lacks; empty when allowed. */
+  readonly missing: readonly string[]
+}
+
+interface AuthorizedRuntime {
+  readonly authorization?: AuthorizationContext
+}
+
+// A request expands to one or more atomic (grant kind, id) checks. The atom is
+// the single unit that both names a requirement and tests the grant index, so
+// the two can never drift. `kind` is the resolved-index key, so enforcement is
+// a direct lookup with no per-target dispatch.
+interface Atom {
+  readonly kind: GrantKind
+  readonly id: string
+}
+
+function atomsFor(request: AuthzRequest): readonly Atom[] {
+  switch (request.kind) {
+    case "application.access":
+      return [{ kind: "access:application", id: request.audience }]
+    case "object.view":
+      return [{ kind: "view:object", id: request.objectTypeId }]
+    case "dataset.view":
+      return [{ kind: "view:dataset", id: request.datasetId }]
+    case "object.edit":
+      return [{ kind: "edit:object", id: request.objectTypeId }]
+    case "telemetry.append":
+      return [{ kind: "append:telemetry", id: request.objectTypeId }]
+    case "action.apply":
+      return [{ kind: "apply:action", id: request.actionId }]
+    case "workflow.run":
+      return [{ kind: "run:workflow", id: request.workflowId }]
+    case "sync.run":
+      return [{ kind: "run:sync", id: request.syncId }]
+    case "pipeline.run":
+      return [{ kind: "run:pipeline", id: request.pipelineId }]
+    case "agent.run":
+      return [{ kind: "run:agent", id: request.agentId }]
+    case "logs.observe":
+      return [{ kind: "observe:logs", id: "logs" }]
+    case "object.query":
+      return request.touchedObjectTypeIds.map((id) => ({ kind: "view:object", id }))
+  }
+}
+
+function atomKey(atom: Atom): string {
+  if (atom.kind === "observe:logs") return atom.kind
+  return `${atom.kind}:${atom.id}`
+}
+
+function holds(grants: GrantIndex, atom: Atom): boolean {
+  return grants[atom.kind].has(atom.id)
+}
+
+/** Resolve a request against a principal's grants. Never throws. */
+export function evaluate(
+  authorization: AuthorizationContext | null | undefined,
+  request: AuthzRequest
+): AuthzDecision {
+  const atoms = atomsFor(request)
+  const requirements = atoms.map(atomKey)
+  const missing = authorization
+    ? atoms.filter((atom) => !holds(authorization.grants, atom)).map(atomKey)
+    : []
+  return { allowed: missing.length === 0, requirements, missing }
+}
+
+export function isAllowed(
+  authorization: AuthorizationContext | null | undefined,
+  request: AuthzRequest
+): boolean {
+  return evaluate(authorization, request).allowed
+}
+
+export function assertAuthorized(runtime: AuthorizedRuntime, request: AuthzRequest): void {
+  const decision = evaluate(runtime.authorization, request)
+  if (decision.allowed) {
+    return
+  }
+
+  throw new AuthorizationError(
+    decision.missing[0] ?? request.kind,
+    deniedMessage(runtime.authorization, request)
+  )
+}
+
+/**
+ * Assert a principal may write objects of this type.
+ *
+ * Requires `view:object` as well as `edit:object`, and that is not belt-and-braces: an upsert
+ * returns the *merged* row, which the Materializer reconciles against source authority, so the
+ * response can carry properties the caller never sent. Granting the write without the read would
+ * leak them.
+ *
+ * The pairing is asserted here rather than implied during resolution: `resolveRoleGrants` has no
+ * notion of one grant entailing another, and giving it one would put ids in the resolved index that
+ * no role granted — an index that no longer answers "what was actually granted".
+ *
+ * Telemetry append is deliberately *not* paired this way; see {@link assertCanAppendTelemetry}.
+ */
+export function assertCanEdit(runtime: AuthorizedRuntime, objectTypeId: string): void {
+  assertAuthorized(runtime, { kind: "object.view", objectTypeId })
+  assertAuthorized(runtime, { kind: "object.edit", objectTypeId })
+}
+
+/**
+ * Assert a principal may append telemetry points to objects of this type.
+ *
+ * No `view:object` requirement, unlike {@link assertCanEdit}: an append answers with no object
+ * state, so there is nothing to leak. That is what makes a write-only principal — a device, an
+ * ingestion service — expressible at all, and it is the reason telemetry has its own grant.
+ */
+export function assertCanAppendTelemetry(runtime: AuthorizedRuntime, objectTypeId: string): void {
+  assertAuthorized(runtime, { kind: "telemetry.append", objectTypeId })
+}
+
+/**
+ * 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.
+ */
+export function assertPrivileged(runtime: AuthorizedRuntime, operation: string): void {
+  if (!runtime.authorization) {
+    return
+  }
+
+  throw new AuthorizationError(
+    `privileged:${operation}`,
+    `[Sixb] Operation '${operation}' is not covered by scoped authorization grants.`
+  )
+}
+
+function deniedMessage(
+  authorization: AuthorizationContext | null | undefined,
+  request: AuthzRequest
+): string {
+  const principalId = authorization?.principal.id ?? "unknown"
+  switch (request.kind) {
+    case "application.access":
+      return `[Sixb] Principal '${principalId}' is not allowed to access application '${request.audience}'.`
+    case "object.view":
+      return `[Sixb] Principal '${principalId}' is not allowed to view object type '${request.objectTypeId}'.`
+    case "dataset.view":
+      return `[Sixb] Principal '${principalId}' is not allowed to view dataset '${request.datasetId}'.`
+    case "object.edit":
+      return `[Sixb] Principal '${principalId}' is not allowed to write object type '${request.objectTypeId}'.`
+    case "telemetry.append":
+      return `[Sixb] Principal '${principalId}' is not allowed to append telemetry for object type '${request.objectTypeId}'.`
+    case "action.apply":
+      return `[Sixb] Principal '${principalId}' is not allowed to apply action '${request.actionId}'.`
+    case "workflow.run":
+      return `[Sixb] Principal '${principalId}' is not allowed to run workflow '${request.workflowId}'.`
+    case "sync.run":
+      return `[Sixb] Principal '${principalId}' is not allowed to run sync '${request.syncId}'.`
+    case "pipeline.run":
+      return `[Sixb] Principal '${principalId}' is not allowed to run pipeline '${request.pipelineId}'.`
+    case "agent.run":
+      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 "object.query": {
+      // Name the first touched type the principal cannot view.
+      const blocked = request.touchedObjectTypeIds.find(
+        (objectTypeId) => !isAllowed(authorization, { kind: "object.view", objectTypeId })
+      )
+      return `[Sixb] Principal '${principalId}' is not allowed to view object type '${blocked}'.`
+    }
+  }
+}

package/src/authorization/errors.ts

@@ -0,0 +1,12 @@
+/** Thrown when a scoped operation is not covered by the principal's grants. Maps to HTTP 403. */
+export class AuthorizationError extends Error {
+  readonly name = "AuthorizationError"
+
+  constructor(
+    /** Stable key of the missing grant, e.g. `view:object:Contract`. */
+    readonly grantKey: string,
+    message: string
+  ) {
+    super(message)
+  }
+}

package/src/authorization/event-visibility.ts

@@ -0,0 +1,99 @@
+/**
+ * Event visibility derived from grants.
+ *
+ * There is no standalone "view events" capability: a principal sees a domain
+ * event only when it can view/apply/run the event's subject. A privileged
+ * caller (no authorization context) sees everything.
+ *
+ * The topic switch is fail-closed: an unrecognized topic is hidden, because a
+ * topic we don't yet model may carry a subject the principal is not allowed to
+ * see. Adding an event topic therefore requires an explicit visibility decision
+ * here, never a silent default.
+ */
+
+import type { StoredDomainEvent } from "../events"
+import { isAllowed } from "./decision"
+import type { AuthorizationContext } from "./types"
+
+export function canViewEvent(
+  authorization: AuthorizationContext | null | undefined,
+  event: StoredDomainEvent
+): boolean {
+  if (!authorization) {
+    return true
+  }
+
+  switch (event.topic) {
+    case "objects":
+    case "telemetry":
+      return isAllowed(authorization, {
+        kind: "object.view",
+        objectTypeId: event.payload.objectTypeId,
+      })
+    case "links":
+      return (
+        isAllowed(authorization, {
+          kind: "object.view",
+          objectTypeId: event.payload.sourceTypeId,
+        }) &&
+        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",
+        workflowId: event.payload.workflowId,
+      })
+    case "rules":
+      // Rule events carry the object they fired on, so gate on viewing it —
+      // otherwise they leak the existence and id of hidden-type objects.
+      return isAllowed(authorization, {
+        kind: "object.view",
+        objectTypeId: event.payload.subject.objectTypeId,
+      })
+    // Run grant gates the operational stream. These payloads may also carry the
+    // produced datasetId/versionId; that target is already visible to a runner
+    // through the sync/pipeline catalog (`sync.target.dataset`), so surfacing it
+    // here discloses nothing new.
+    case "syncs":
+      return isAllowed(authorization, {
+        kind: "sync.run",
+        syncId: event.payload.syncId,
+      })
+    case "pipelines":
+      return isAllowed(authorization, {
+        kind: "pipeline.run",
+        pipelineId: event.payload.pipelineId,
+      })
+    case "schedules":
+      // Infra topics with no object/action/workflow/dataset subject: no grant
+      // governs them yet, so they stay visible to any authorized reader. When
+      // they gain their own grants, add the checks here.
+      return true
+    case "datasets":
+      // dataset.view alone. The payload's `producer` (the sync/pipeline that
+      // produced the version, plus its runId) is intentionally visible to any
+      // dataset viewer as provenance — the same identity the versions API
+      // already serializes for that principal. This is distinct from the
+      // operational `references` in the dataset catalog (which syncs/pipelines
+      // are wired to a dataset), which stays gated on the run grants.
+      return isAllowed(authorization, {
+        kind: "dataset.view",
+        datasetId: event.payload.datasetId,
+      })
+    default:
+      // Fail closed: an unmodeled topic may carry a subject we don't yet gate.
+      return false
+  }
+}