@sixb/core 0.1.11 → 0.1.13

package/src/auth/session-cache.ts

@@ -3,6 +3,7 @@ import type { AuthenticatedAuthSession } from "./types"
 
 interface SessionCacheEntry {
   readonly tokenHash: string
+  readonly transport: "cookie" | "bearer"
   readonly audience: AuthSessionAudience
   readonly session: AuthenticatedAuthSession
   readonly expiresAtMs: number
@@ -11,11 +12,18 @@ interface SessionCacheEntry {
 export interface SessionCacheGetInput {
   readonly sessionId: string
   readonly tokenHash: string
-  readonly audience: AuthSessionAudience
+  /** A cookie is only ever answered from a cookie entry, and a bearer token from a bearer entry. */
+  readonly transport: "cookie" | "bearer"
+  /** The browser audience a cookie was read for. Bearer sessions carry their own. */
+  readonly audience?: AuthSessionAudience
   readonly nowMs: number
 }
 
-export interface SessionCacheSetInput extends SessionCacheGetInput {
+export interface SessionCacheSetInput {
+  readonly sessionId: string
+  readonly tokenHash: string
+  readonly audience: AuthSessionAudience
+  readonly nowMs: number
   readonly session: AuthenticatedAuthSession
   readonly sessionExpiresAtMs: number
   readonly sessionAbsoluteExpiresAtMs?: number
@@ -30,7 +38,7 @@ export interface SessionCacheSetInput extends SessionCacheGetInput {
  * API stalls. Caching the resolved result for a short TTL collapses those reads to one
  * per session per window.
  *
- * Safety: entries are pinned to the exact token hash + audience that produced them and
+ * Safety: entries are pinned to the exact token hash, transport, and audience that produced them and
  * are never served past the session's rolling or absolute deadline. The short TTL bounds how long
  * a revoked session can linger; sign-out additionally invalidates eagerly via
  * {@link SessionCache.invalidate}.
@@ -52,7 +60,8 @@ export class SessionCache {
     if (
       entry.expiresAtMs <= input.nowMs ||
       entry.tokenHash !== input.tokenHash ||
-      entry.audience !== input.audience
+      entry.transport !== input.transport ||
+      (input.audience !== undefined && entry.audience !== input.audience)
     ) {
       this.entries.delete(input.sessionId)
       return undefined
@@ -62,11 +71,13 @@ export class SessionCache {
   }
 
   set(input: SessionCacheSetInput): void {
-    // Never let a cached session outlive the real session it represents.
+    // Never let a cached session outlive the real session, or a bearer session its access token.
+    const bearer = input.session.session.bearer
     const expiresAtMs = Math.min(
       input.nowMs + this.ttlMs,
       input.sessionExpiresAtMs,
-      input.sessionAbsoluteExpiresAtMs ?? Number.POSITIVE_INFINITY
+      input.sessionAbsoluteExpiresAtMs ?? Number.POSITIVE_INFINITY,
+      bearer?.accessExpiresAt.getTime() ?? Number.POSITIVE_INFINITY
     )
     if (expiresAtMs <= input.nowMs) {
       return
@@ -76,6 +87,7 @@ export class SessionCache {
     this.entries.delete(input.sessionId)
     this.entries.set(input.sessionId, {
       tokenHash: input.tokenHash,
+      transport: bearer ? "bearer" : "cookie",
       audience: input.audience,
       session: input.session,
       expiresAtMs,

package/src/auth/sessions.ts

@@ -53,3 +53,33 @@ export function createSessionCredential(sessionId = `ses_${randomUUID()}`): Sess
     cookieValue: formatSessionCookieValue(sessionId, sessionSecret),
   }
 }
+
+export const SESSION_ACCESS_TOKEN_PREFIX = "sixb_at_"
+export const SESSION_REFRESH_TOKEN_PREFIX = "sixb_rt_"
+
+export interface BearerSessionTokens {
+  readonly accessToken: string
+  readonly refreshToken: string
+  readonly tokenHash: string
+  readonly refreshTokenHash: string
+}
+
+/** Fresh access and refresh tokens for a native client's session. Only their hashes are stored. */
+export function createBearerSessionTokens(sessionId: string): BearerSessionTokens {
+  const accessSecret = generateSessionSecret()
+  const refreshSecret = generateSessionSecret()
+  return {
+    accessToken: `${SESSION_ACCESS_TOKEN_PREFIX}${formatSessionCookieValue(sessionId, accessSecret)}`,
+    refreshToken: `${SESSION_REFRESH_TOKEN_PREFIX}${formatSessionCookieValue(sessionId, refreshSecret)}`,
+    tokenHash: hashSessionSecret(accessSecret),
+    refreshTokenHash: hashSessionSecret(refreshSecret),
+  }
+}
+
+/** The session id and secret in a bearer session token, or null when it is not one. */
+export function parseBearerSessionToken(
+  prefix: typeof SESSION_ACCESS_TOKEN_PREFIX | typeof SESSION_REFRESH_TOKEN_PREFIX,
+  value: string
+): SessionCookieParts | null {
+  return value.startsWith(prefix) ? parseSessionCookieValue(value.slice(prefix.length)) : null
+}

package/src/auth/types.ts

@@ -30,13 +30,6 @@ export function principalsEqual(left: Principal, right: Principal): boolean {
   return left.type === right.type && left.id === right.id
 }
 
-export interface SecurityContext {
-  readonly principal: Principal
-  readonly sessionId?: string
-  readonly projectId: string
-  readonly correlationId: string
-}
-
 export type AuthStrategyKind = "magicLink" | "oidc" | "dev" | "disabled"
 
 export interface AuthStrategy {
@@ -225,7 +218,6 @@ export interface InviteUserInput {
   readonly groups?: readonly GroupDefinition[]
   readonly groupIds?: readonly string[]
   readonly expiresAt?: Date
-  readonly returnTo?: string
   /** Reveal the delivered link once in the result. Defaults to false. */
   readonly revealLink?: boolean
 }
@@ -368,7 +360,8 @@ export interface ReactivateMemberResult {
   readonly groupIds: readonly string[]
 }
 
-export type AuthCredentialSource = "session" | "accessToken" | "any"
+/** `"session"` reads only the cookie; `"any"` reads a bearer access token, else the cookie. */
+export type AuthCredentialSource = "session" | "any"
 
 export interface AuthSessionResolutionOptions extends AuthSessionAudienceOptions {
   readonly credentialSource?: AuthCredentialSource
@@ -376,12 +369,11 @@ export interface AuthSessionResolutionOptions extends AuthSessionAudienceOptions
   readonly sessionActivity?: "foreground"
 }
 
-export interface InviteUserOptions extends AuthSessionAudienceOptions {
-  readonly delivery?: {
-    readonly audience?: AuthSessionAudience
-    readonly requestOrigin?: string
-    readonly returnTo?: string
-  }
+/** Where an invitation link sends its recipient. */
+export interface InvitationDestination {
+  readonly audience: AuthSessionAudience
+  readonly requestOrigin: string
+  readonly returnTo: string
 }
 
 export interface RevokeInvitationInput {
@@ -521,9 +513,7 @@ export type SixbAuthConfig =
 
 export type AuthSessionFailureReason =
   | "auth_disabled"
-  | "missing_credentials"
   | "missing_cookie"
-  | "missing_access_token"
   | "invalid_cookie"
   | "invalid_access_token"
   | "invalid_session"

package/src/bootstrap/index.ts

@@ -15,6 +15,7 @@ export type {
   GenerateOntologyTypeManifestResult,
   OntologyTypeManifestDiscovery,
   OntologyTypeManifestEntry,
+  OntologyValueTypeManifestEntry,
 } from "./ontology-type-manifest"
 export {
   discoverOntologyTypeManifest,

package/src/bootstrap/ontology-type-manifest.ts

@@ -3,6 +3,7 @@ import { dirname, extname, join, relative, resolve, sep } from "node:path"
 import { pathToFileURL } from "node:url"
 import type { OntologyDocumentInput } from "../ontology/registry"
 import type { ObjectTypeWithPropertyTokens } from "../ontology/tokens"
+import type { ValueType } from "../ontology/types"
 import { RuntimeError } from "../runtime/errors"
 
 const moduleExtensions = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"])
@@ -14,8 +15,17 @@ export interface OntologyTypeManifestEntry {
   readonly typeExpression: string
 }
 
+/** A value type the manifest registers, so a string-only `valueTypeRef("id")` is typed. */
+export interface OntologyValueTypeManifestEntry {
+  readonly valueTypeId: string
+  readonly modulePath: string
+  readonly exportName: string
+  readonly typeExpression: string
+}
+
 export interface OntologyTypeManifestDiscovery {
   readonly entries: readonly OntologyTypeManifestEntry[]
+  readonly valueTypeEntries: readonly OntologyValueTypeManifestEntry[]
   readonly moduleCount: number
 }
 
@@ -37,7 +47,8 @@ export async function discoverOntologyTypeManifest(
   const ontologyDir = join(resolvedProjectRoot, "ontology")
   const modulePaths = await listModuleFiles(ontologyDir)
   const entries = new Map<string, OntologyTypeManifestEntry>()
-  const seenObjectTypes = new Set<unknown>()
+  const valueTypeEntries = new Map<string, OntologyValueTypeManifestEntry>()
+  const seen = new Set<unknown>()
 
   for (const modulePath of modulePaths) {
     const moduleSpecifier = toGeneratedModuleSpecifier({
@@ -56,13 +67,17 @@ export async function discoverOntologyTypeManifest(
         modulePath,
         moduleSpecifier,
         entries,
-        seenObjectTypes,
+        valueTypeEntries,
+        seen,
       })
     }
   }
 
   return {
     entries: [...entries.values()].sort((a, b) => a.objectTypeId.localeCompare(b.objectTypeId)),
+    valueTypeEntries: [...valueTypeEntries.values()].sort((a, b) =>
+      a.valueTypeId.localeCompare(b.valueTypeId)
+    ),
     moduleCount: modulePaths.length,
   }
 }
@@ -89,7 +104,7 @@ export async function generateOntologyTypeManifest(
     }
   }
 
-  const content = renderOntologyTypeManifest(discovery.entries)
+  const content = renderOntologyTypeManifest(discovery)
   await mkdir(dirname(outFile), { recursive: true })
   const written = await writeFileIfChanged(outFile, content)
 
@@ -101,98 +116,114 @@ export async function generateOntologyTypeManifest(
   }
 }
 
+/**
+ * Mirrors what runtime discovery registers from an `ontology/` module: exported object types and
+ * value types, the ones an exported ontology document carries, and those inside exported arrays.
+ */
 function collectManifestEntries(input: {
   readonly exportedValue: unknown
   readonly exportName: string
   readonly modulePath: string
   readonly moduleSpecifier: string
   readonly entries: Map<string, OntologyTypeManifestEntry>
-  readonly seenObjectTypes: Set<unknown>
+  readonly valueTypeEntries: Map<string, OntologyValueTypeManifestEntry>
+  readonly seen: Set<unknown>
 }): void {
-  if (isObjectTypeWithPropertyTokens(input.exportedValue)) {
-    addManifestEntry({
-      objectType: input.exportedValue,
-      modulePath: input.modulePath,
-      exportName: input.exportName,
-      typeExpression: `typeof import(${JSON.stringify(input.moduleSpecifier)})[${JSON.stringify(
-        input.exportName
-      )}]`,
-      entries: input.entries,
-      seenObjectTypes: input.seenObjectTypes,
-    })
-    return
+  const exported = `(typeof import(${JSON.stringify(input.moduleSpecifier)})[${JSON.stringify(
+    input.exportName
+  )}])`
+  const add = (value: unknown, typeExpression: (id: string) => string): void => {
+    if (isObjectTypeWithPropertyTokens(value)) {
+      addManifestEntry({
+        kind: "object type",
+        definition: value,
+        entry: {
+          objectTypeId: value.id,
+          modulePath: input.modulePath,
+          exportName: input.exportName,
+          typeExpression: typeExpression(value.id),
+        },
+        idOf: (entry) => entry.objectTypeId,
+        entries: input.entries,
+        seen: input.seen,
+      })
+    } else if (isValueType(value)) {
+      addManifestEntry({
+        kind: "value type",
+        definition: value,
+        entry: {
+          valueTypeId: value.id,
+          modulePath: input.modulePath,
+          exportName: input.exportName,
+          typeExpression: typeExpression(value.id),
+        },
+        idOf: (entry) => entry.valueTypeId,
+        entries: input.valueTypeEntries,
+        seen: input.seen,
+      })
+    }
   }
 
   if (isOntologyDocumentInput(input.exportedValue)) {
     for (const objectType of input.exportedValue.objectTypes) {
-      addManifestEntry({
+      add(
         objectType,
-        modulePath: input.modulePath,
-        exportName: input.exportName,
-        typeExpression: `Extract<(typeof import(${JSON.stringify(
-          input.moduleSpecifier
-        )})[${JSON.stringify(input.exportName)}])["objectTypes"][number], { id: ${JSON.stringify(
-          objectType.id
-        )} }>`,
-        entries: input.entries,
-        seenObjectTypes: input.seenObjectTypes,
-      })
+        (id) => `Extract<${exported}["objectTypes"][number], { id: ${JSON.stringify(id)} }>`
+      )
+    }
+    for (const valueType of input.exportedValue.valueTypes ?? []) {
+      add(
+        valueType,
+        (id) => `Extract<${exported}["valueTypes"][number], { id: ${JSON.stringify(id)} }>`
+      )
     }
     return
   }
 
   if (Array.isArray(input.exportedValue)) {
     for (const item of input.exportedValue) {
-      if (!isObjectTypeWithPropertyTokens(item)) continue
-      addManifestEntry({
-        objectType: item,
-        modulePath: input.modulePath,
-        exportName: input.exportName,
-        typeExpression: `Extract<(typeof import(${JSON.stringify(
-          input.moduleSpecifier
-        )})[${JSON.stringify(input.exportName)}])[number], { id: ${JSON.stringify(item.id)} }>`,
-        entries: input.entries,
-        seenObjectTypes: input.seenObjectTypes,
-      })
+      add(item, (id) => `Extract<${exported}[number], { id: ${JSON.stringify(id)} }>`)
     }
+    return
   }
+
+  add(
+    input.exportedValue,
+    () =>
+      `typeof import(${JSON.stringify(input.moduleSpecifier)})[${JSON.stringify(input.exportName)}]`
+  )
 }
 
-function addManifestEntry(input: {
-  readonly objectType: ObjectTypeWithPropertyTokens
-  readonly modulePath: string
-  readonly exportName: string
-  readonly typeExpression: string
-  readonly entries: Map<string, OntologyTypeManifestEntry>
-  readonly seenObjectTypes: Set<unknown>
+function addManifestEntry<TEntry extends { readonly modulePath: string }>(input: {
+  readonly kind: "object type" | "value type"
+  readonly definition: unknown
+  readonly entry: TEntry
+  readonly idOf: (entry: TEntry) => string
+  readonly entries: Map<string, TEntry>
+  readonly seen: Set<unknown>
 }): void {
-  if (input.seenObjectTypes.has(input.objectType)) {
+  // The same definition re-exported from several places is one registration.
+  if (input.seen.has(input.definition)) {
     return
   }
-  input.seenObjectTypes.add(input.objectType)
-
-  const existing = input.entries.get(input.objectType.id)
-  const entry: OntologyTypeManifestEntry = {
-    objectTypeId: input.objectType.id,
-    modulePath: input.modulePath,
-    exportName: input.exportName,
-    typeExpression: input.typeExpression,
-  }
+  input.seen.add(input.definition)
 
+  const id = input.idOf(input.entry)
+  const existing = input.entries.get(id)
   if (!existing) {
-    input.entries.set(input.objectType.id, entry)
+    input.entries.set(id, input.entry)
     return
   }
 
   throw new RuntimeError(
-    `[Sixb] Duplicate ontology object type id "${input.objectType.id}" while generating `.concat(
+    `[Sixb] Duplicate ontology ${input.kind} id "${id}" while generating `.concat(
       `the type manifest: ${relative(process.cwd(), existing.modulePath)} and `,
-      `${relative(process.cwd(), input.modulePath)}.`
+      `${relative(process.cwd(), input.entry.modulePath)}.`
     )
   )
 }
 
-function renderOntologyTypeManifest(entries: readonly OntologyTypeManifestEntry[]): string {
+function renderOntologyTypeManifest(discovery: OntologyTypeManifestDiscovery): string {
   const lines = [
     "// This file is auto-generated by Sixb.",
     "// Do not edit this file directly.",
@@ -201,10 +232,16 @@ function renderOntologyTypeManifest(entries: readonly OntologyTypeManifestEntry[
     "  interface SixbObjectTypeMap {",
   ]
 
-  for (const entry of entries) {
+  for (const entry of discovery.entries) {
     lines.push(`    ${JSON.stringify(entry.objectTypeId)}: ${entry.typeExpression}`)
   }
 
+  lines.push("  }", "  interface SixbValueTypeMap {")
+
+  for (const entry of discovery.valueTypeEntries) {
+    lines.push(`    ${JSON.stringify(entry.valueTypeId)}: ${entry.typeExpression}`)
+  }
+
   lines.push("  }", "}", "", "export {}", "")
   return lines.join("\n")
 }
@@ -309,6 +346,21 @@ function isObjectTypeWithPropertyTokens(value: unknown): value is ObjectTypeWith
   )
 }
 
+/** Same shape test runtime discovery applies to an exported value type. */
+function isValueType(value: unknown): value is ValueType {
+  if (!isRecord(value)) {
+    return false
+  }
+
+  return (
+    typeof value.id === "string" &&
+    typeof value.name === "string" &&
+    "schema" in value &&
+    !Array.isArray(value.properties) &&
+    !Array.isArray(value.objectTypes)
+  )
+}
+
 function isOntologyDocumentInput(value: unknown): value is OntologyDocumentInput {
   if (!isRecord(value)) {
     return false

package/src/datasets/validation.ts

@@ -1,4 +1,5 @@
 import { isFileRef } from "../blob-storage"
+import { withFailureMessage } from "../errors/failure-message"
 import { isJsonValue, isPlainRecord } from "../json"
 import { isDecimalString } from "../ontology/decimal"
 import { DatasetValidationError } from "./errors"
@@ -233,8 +234,17 @@ export function getDatasetRowValidationError(
   dataset: DatasetDefinition,
   options?: { readonly columns?: Iterable<string> }
 ): string | null {
+  return getDatasetRowValidationFailure(row, dataset, options)?.message ?? null
+}
+
+/** Internal form retains a value-free explanation for the durable failure boundary. */
+export function getDatasetRowValidationFailure(
+  row: unknown,
+  dataset: DatasetDefinition,
+  options?: { readonly columns?: Iterable<string> }
+): Error | null {
   if (!isPlainRecord(row)) {
-    return `Dataset '${dataset.id}' rows must be plain objects.`
+    return rowFailure(`Dataset '${dataset.id}' rows must be plain objects.`)
   }
 
   const columnsByName = new Map(
@@ -251,7 +261,7 @@ export function getDatasetRowValidationError(
         continue
       }
 
-      const error = getColumnValidationError(row, column, dataset)
+      const error = getColumnValidationFailure(row, column, dataset)
       if (error) {
         return error
       }
@@ -262,12 +272,15 @@ export function getDatasetRowValidationError(
 
   for (const columnName of Object.keys(row)) {
     if (!columnsByName.has(columnName)) {
-      return `Dataset '${dataset.id}' row contains unknown column '${columnName}'.`
+      return rowFailure(
+        `Dataset '${dataset.id}' row contains unknown column '${columnName}'.`,
+        `Dataset '${dataset.id}' row contains an undeclared column.`
+      )
     }
   }
 
   for (const column of dataset.schema.columns) {
-    const error = getColumnValidationError(row, column, dataset)
+    const error = getColumnValidationFailure(row, column, dataset)
     if (error) {
       return error
     }
@@ -276,29 +289,37 @@ export function getDatasetRowValidationError(
   return null
 }
 
-function getColumnValidationError(
+function getColumnValidationFailure(
   row: Record<string, unknown>,
   column: DatasetColumnDefinition,
   dataset: DatasetDefinition
-): string | null {
+): Error | null {
   const hasValue = Object.hasOwn(row, column.name)
   const value = row[column.name]
   if (column.name === dataset.sequenceBy) {
-    return getDatasetSequenceValidationError(dataset, value)
+    const message = getDatasetSequenceValidationError(dataset, value)
+    return message === null
+      ? null
+      : rowFailure(
+          message,
+          `Dataset '${dataset.id}' sequence column '${column.name}' must contain a valid ${column.type} source sequence.`
+        )
   }
 
   // Treat `undefined` the same as an omitted field so callers either send a real
   // value or use `null` explicitly on nullable columns.
   if (!hasValue || value === undefined) {
     if (!column.nullable) {
-      return `Dataset '${dataset.id}' row is missing required column '${column.name}'.`
+      return rowFailure(`Dataset '${dataset.id}' row is missing required column '${column.name}'.`)
     }
     return null
   }
 
   if (value === null) {
     if (!column.nullable) {
-      return `Dataset '${dataset.id}' column '${column.name}' does not allow null values.`
+      return rowFailure(
+        `Dataset '${dataset.id}' column '${column.name}' does not allow null values.`
+      )
     }
     return null
   }
@@ -307,13 +328,21 @@ function getColumnValidationError(
   // Reject ambiguous or lossy values before staging, even when another column orders the row.
   if (dataset.sequenceBy !== undefined && column.type === "timestamp") {
     return parseDatasetTimestamp(value) === null
-      ? `Dataset '${dataset.id}' column '${column.name}' must be a valid Date or ISO timestamp with an explicit timezone and at most millisecond precision.`
+      ? rowFailure(
+          `Dataset '${dataset.id}' column '${column.name}' must be a valid Date or ISO timestamp with an explicit timezone and at most millisecond precision.`
+        )
       : null
   }
 
   if (!matchesColumnType(value, column.type)) {
-    return `Dataset '${dataset.id}' column '${column.name}' must match type '${column.type}'.`
+    return rowFailure(
+      `Dataset '${dataset.id}' column '${column.name}' must match type '${column.type}'.`
+    )
   }
 
   return null
 }
+
+function rowFailure(message: string, publicMessage = message): Error {
+  return withFailureMessage(new DatasetValidationError(message), publicMessage)
+}

package/src/datasets/write.ts

@@ -1,6 +1,5 @@
 import type { BlobStorage, FileRef } from "../blob-storage"
 import { isFileRef } from "../blob-storage"
-import { isPlainRecord } from "../json"
 import type { DatasetMergeCommitResult } from "../lake-storage/merge"
 import { getDatasetMergeChangeValidationError } from "../lake-storage/merge-validation"
 import type {
@@ -11,7 +10,7 @@ import type {
 } from "../lake-storage/types"
 import type { MergeChange } from "./changes"
 import type { DatasetDefinition } from "./types"
-import { getDatasetRowValidationError } from "./validation"
+import { getDatasetRowValidationFailure } from "./validation"
 
 export interface DatasetWriteValue {
   readonly value: unknown
@@ -161,19 +160,17 @@ async function validateRow(
   input: WriteDatasetInput,
   itemIndex: number
 ): Promise<DatasetRow> {
-  if (!isPlainRecord(value)) {
-    throw new Error(
-      `${sourceLabel(input)} returned an invalid row at item ${itemIndex}. Dataset rows must be plain objects.`
-    )
-  }
-  const validationError = getDatasetRowValidationError(value, input.dataset)
+  const validationError = getDatasetRowValidationFailure(value, input.dataset)
   if (validationError) {
     throw new Error(
-      `${sourceLabel(input)} returned an invalid row at item ${itemIndex}. ${validationError}`
+      `${sourceLabel(input)} returned an invalid row at item ${itemIndex}. ${validationError.message}`,
+      { cause: validationError }
     )
   }
-  await verifyRowFileRefs(value, input, itemIndex)
-  return value
+  // The validator above establishes the row shape.
+  const row = value as DatasetRow
+  await verifyRowFileRefs(row, input, itemIndex)
+  return row
 }
 
 async function validateMergeChange(