@exvio/os-backend-core 0.4.0

package/src/db/plugins/tenant-filter.ts

@@ -0,0 +1,518 @@
+/**
+ * Shared Kysely plugin that auto-injects tenant_id filters on tagged tables,
+ * reading the active tenantId from AsyncLocalStorage (../tenant-context).
+ *
+ * Behaviour:
+ *   - SELECT / UPDATE / DELETE: walk From/Join nodes, add WHERE on
+ *     tenant-aware tables.
+ *   - INNER/LEFT joins: put joined-side predicates in ON so LEFT JOIN keeps
+ *     unmatched rows. RIGHT/FULL/CROSS/APPLY variants fail when their joined
+ *     side is tenant-aware because the same rewrite is not semantics-safe.
+ *   - UPDATE: tenant_id itself is immutable in a tenant-scoped query;
+ *     multi-table targets and dynamic/raw column names fail loudly.
+ *   - INSERT (VALUES): inject (or overwrite) tenant_id in the row(s).
+ *   - UPSERT / REPLACE into tenant-aware tables: throws fail-loud until the
+ *     conflict target can be proven to include tenant_id.
+ *   - INSERT … SELECT / INSERT … DEFAULT VALUES into a tenant-aware
+ *     table: throws fail-loud. The inner SELECT does still get its own
+ *     tenant_id filter via OperationNodeTransformer recursion, but the
+ *     INSERT projection itself can't be safely stamped (we'd be guessing
+ *     where in the column list to splice tenant_id), so we'd be relying
+ *     on the DB's NOT NULL constraint to catch the missing column at
+ *     execute time. Better to refuse at the call site — caller must use
+ *     bypassTenant() and explicitly guarantee the projected tenant_id.
+ *   - bypass=true: pass through unmodified.
+ *   - no context: configurable; v0.1 defaults to compatibility passthrough.
+ *   - MERGE: throws fail-loud (not yet supported; wrap call in
+ *     bypassTenant() if intentional).
+ *
+ * Recursion model
+ * ───────────────
+ * The plugin extends Kysely's `OperationNodeTransformer`, which already
+ * walks the entire AST depth-first. Our overrides:
+ *
+ *   1. Inject the tenant predicate into the *current* SELECT/UPDATE/
+ *      DELETE/INSERT node.
+ *   2. Then call `super.transform*` on the rewritten node — which
+ *      recurses into every child (FROM/JOIN/WHERE/HAVING/SET/CTE
+ *      body/scalar subquery/EXISTS/IN-subquery/etc.). Any nested
+ *      SelectQueryNode hits our `transformSelectQuery` override again
+ *      and gets its own predicate.
+ *
+ * This is the only correct way to handle subqueries built via
+ * `eb.selectFrom(...)`: a single root-level inspection misses every
+ * nested SELECT (cross-tenant data leak). See test cases tagged
+ * "nested-AST coverage" for what this fix prevents.
+ *
+ * Known limitations
+ * ─────────────────
+ *   - **Raw `sql\`...\`` template strings bypass the plugin entirely.**
+ *     They are compiled directly to SQL fragments without an AST node
+ *     for tables/joins, so there is nothing structural to walk. Code
+ *     that assembles tenant-aware queries via `sql\`...\`` MUST add
+ *     the `tenant_id = ?` predicate by hand. (We considered string-
+ *     scanning RawNode.sql but it's brittle — quoted identifiers,
+ *     comments, alias collisions all turn it into a parser project.)
+ *   - **MERGE statements throw fail-loud.** The Kysely query builder
+ *     doesn't currently expose a "from" we can rewrite uniformly, and
+ *     we'd rather block at the call site than silently leak.
+ *   - **Unsupported joins fail when the joined table is tenant-aware.**
+ *     RIGHT/FULL joins preserve the joined side, so adding its predicate to ON
+ *     does not remove cross-tenant rows. CROSS/APPLY variants have different
+ *     or absent ON semantics. Callers must rewrite or explicitly bypass with
+ *     their own tenant predicate.
+ *
+ * AST notes (Kysely 0.28.x)
+ * ─────────────────────────
+ *   - TableNode wraps a SchemableIdentifierNode (which wraps an
+ *     IdentifierNode .name); table name is at .table.identifier.name.
+ *   - AliasNode.alias for table aliases is itself an IdentifierNode
+ *     (so its name is at .alias.name).
+ *   - UpdateQueryNode.table is a TableNode/AliasNode for the supported
+ *     single-table form. Kysely represents multi-table targets as ListNode;
+ *     unresolved target shapes fail loudly instead of bypassing isolation.
+ *   - InsertQueryNode.values is an OperationNode (declared as such),
+ *     practically a ValuesNode whose .values is an array of
+ *     PrimitiveValueListNode (raw primitives) or ValueListNode (wrapped
+ *     ValueNodes). We handle both — Kysely uses Primitive when all row
+ *     values are plain primitives, otherwise ValueList.
+ *   - All AST nodes are frozen / readonly; we always return new objects
+ *     via spread, never mutate.
+ */
+import {
+  type KyselyPlugin,
+  type PluginTransformQueryArgs,
+  type PluginTransformResultArgs,
+  type RootOperationNode,
+  type OperationNode,
+  type QueryResult,
+  type UnknownRow,
+  OperationNodeTransformer,
+  SelectQueryNode,
+  UpdateQueryNode,
+  DeleteQueryNode,
+  InsertQueryNode,
+  MergeQueryNode,
+  WhereNode,
+  AndNode,
+  BinaryOperationNode,
+  ColumnNode,
+  ReferenceNode,
+  TableNode,
+  AliasNode,
+  ValueNode,
+  OperatorNode,
+  ValuesNode,
+  PrimitiveValueListNode,
+  ValueListNode,
+  IdentifierNode,
+  JoinNode,
+  type ColumnUpdateNode,
+} from 'kysely'
+import { tenantContext, type TenantStore } from '../tenant-context.ts'
+
+const TENANT_ID_COLUMN = 'tenant_id'
+const SAFE_ON_CLAUSE_JOIN_TYPES = new Set([
+  'InnerJoin',
+  'LeftJoin',
+  'LateralInnerJoin',
+  'LateralLeftJoin',
+])
+
+export type MissingTenantContextPolicy = 'passthrough' | 'throw'
+
+/** The narrow context surface required by TenantFilterPlugin. */
+export interface TenantContextReader {
+  getStore(): TenantStore | undefined
+}
+
+export interface TenantFilterPluginOptions {
+  /**
+   * Explicit context injection prevents a linked or duplicated package from
+   * silently giving the plugin a different AsyncLocalStorage instance.
+   */
+  context?: TenantContextReader
+  /**
+   * `passthrough` preserves the pre-package fleet behaviour. Consumers should
+   * migrate non-HTTP entry points and then opt into `throw` fail-closed mode.
+   */
+  onMissingContext?: MissingTenantContextPolicy
+}
+
+/**
+ * Identifies a table-reference as it appears in FROM/JOIN/UPDATE: both
+ * the underlying table name (used to look up tenant-awareness) and the
+ * alias to qualify the injected WHERE column with (so a JOIN's two
+ * filters don't collide on the same `tenant_id` reference).
+ */
+interface TableRef {
+  /** Underlying table name (used for tenant-awareness lookup). */
+  tableName: string
+  /** Alias if present, otherwise the table name (used to qualify the WHERE). */
+  qualifier: string
+}
+
+/**
+ * AST transformer that walks the full operation-node tree and injects a
+ * `tenant_id = $tid` predicate on every SELECT/UPDATE/DELETE that
+ * targets a tenant-aware table, plus stamps `tenant_id = $tid` into
+ * every INSERT row. Recursion is delegated to the base class — see the
+ * "Recursion model" docblock at the top of the file.
+ */
+class TenantFilterTransformer extends OperationNodeTransformer {
+  constructor(
+    private readonly tables: ReadonlySet<string>,
+    private readonly tid: number,
+  ) {
+    super()
+  }
+
+  protected override transformSelectQuery(node: SelectQueryNode): SelectQueryNode {
+    // 1. Inject WHERE for tenant-aware tables in *this* SELECT's FROM/JOIN.
+    const filtered = this.injectIntoSelect(node)
+    // 2. Recurse: every nested SelectQueryNode (subquery, CTE body,
+    //    EXISTS, IN, scalar) hits transformSelectQuery again.
+    return super.transformSelectQuery(filtered)
+  }
+
+  protected override transformUpdateQuery(node: UpdateQueryNode): UpdateQueryNode {
+    const filtered = this.injectIntoUpdate(node)
+    return super.transformUpdateQuery(filtered)
+  }
+
+  protected override transformDeleteQuery(node: DeleteQueryNode): DeleteQueryNode {
+    const filtered = this.injectIntoDelete(node)
+    return super.transformDeleteQuery(filtered)
+  }
+
+  protected override transformInsertQuery(node: InsertQueryNode): InsertQueryNode {
+    const filtered = this.injectIntoInsert(node)
+    return super.transformInsertQuery(filtered)
+  }
+
+  protected override transformMergeQuery(_node: MergeQueryNode): MergeQueryNode {
+    throw new Error(
+      'TenantFilterPlugin: MERGE statements are not supported — wrap the call ' +
+      'in bypassTenant() if intentional, or rewrite as INSERT/UPDATE/DELETE.',
+    )
+  }
+
+  // ── helpers ─────────────────────────────────────────────────────────────
+
+  /**
+   * Resolves a from/join/update target node to its underlying table name
+   * + the qualifier (alias if any, else table name) used to scope the
+   * injected WHERE. Returns null for things we cannot interpret as a
+   * single tenant-aware table (subqueries, raw expressions, etc.).
+   */
+  private resolveTableRef(node: OperationNode): TableRef | null {
+    if (AliasNode.is(node)) {
+      const inner = node.node
+      if (!TableNode.is(inner)) return null
+      const tableName = inner.table.identifier.name
+      const aliasName = IdentifierNode.is(node.alias) ? node.alias.name : tableName
+      return { tableName, qualifier: aliasName }
+    }
+    if (TableNode.is(node)) {
+      const tableName = node.table.identifier.name
+      return { tableName, qualifier: tableName }
+    }
+    return null
+  }
+
+  /** Build `<qualifier>.tenant_id = $tid` BinaryOperationNode. */
+  private buildTenantPredicate(qualifier: string): BinaryOperationNode {
+    return BinaryOperationNode.create(
+      ReferenceNode.create(ColumnNode.create(TENANT_ID_COLUMN), TableNode.create(qualifier)),
+      OperatorNode.create('='),
+      ValueNode.create(this.tid),
+    )
+  }
+
+  /**
+   * Append `predicate` to an existing WhereNode (AND-combined) or wrap
+   * it in a new WhereNode if there isn't one yet.
+   */
+  private appendWhere(existing: WhereNode | undefined, predicate: OperationNode): WhereNode {
+    if (!existing) return WhereNode.create(predicate)
+    return WhereNode.create(AndNode.create(existing.where, predicate))
+  }
+
+  /**
+   * Collect tenant predicates for every tenant-aware FROM/USING item.
+   * These go into the outer WHERE clause (FROM tables are not inside any
+   * JOIN's ON, so WHERE is the correct landing spot).
+   */
+  private collectFromPredicates(
+    fromItems: ReadonlyArray<OperationNode> | undefined,
+  ): OperationNode[] {
+    const preds: OperationNode[] = []
+    if (!fromItems) return preds
+    for (const item of fromItems) {
+      const ref = this.resolveTableRef(item)
+      if (ref && this.tables.has(ref.tableName)) {
+        preds.push(this.buildTenantPredicate(ref.qualifier))
+      }
+    }
+    return preds
+  }
+
+  /**
+   * For each tenant-aware JOIN, append the tenant predicate to the JOIN's
+   * own ON clause (NOT the outer WHERE). This is correctness-critical for
+   * LEFT JOIN: putting the joined-side `tenant_id = ?` filter in the outer
+   * WHERE turns a LEFT JOIN into an effective INNER JOIN, because rows
+   * where the right-hand side is unmatched have NULL for every joined
+   * column — including tenant_id — and `NULL = ?` is falsy. Symptom: a
+   * user with a NULL FK to a tenant-aware table silently disappears from
+   * results. INNER JOIN behaviour is identical either way; placing in ON
+   * is uniform.
+   */
+  private rewriteJoins(
+    joins: ReadonlyArray<JoinNode> | undefined,
+  ): ReadonlyArray<JoinNode> | undefined {
+    if (!joins?.length) return joins
+    return joins.map((join) => {
+      // JoinNode.table is the joined-table OperationNode (TableNode or
+      // AliasNode-wrapped TableNode).
+      const ref = this.resolveTableRef(join.table)
+      if (!ref || !this.tables.has(ref.tableName)) return join
+      if (!SAFE_ON_CLAUSE_JOIN_TYPES.has(join.joinType)) {
+        throw new Error(
+          `TenantFilterPlugin: ${join.joinType} against tenant-aware table ` +
+          `${ref.tableName} is not supported. Rewrite the join as INNER/LEFT, ` +
+          `or use bypassTenant() with an explicit tenant predicate.`,
+        )
+      }
+      // JoinNode.cloneWithOn AND-combines into the existing ON, or
+      // creates a fresh ON if none was present.
+      return JoinNode.cloneWithOn(join, this.buildTenantPredicate(ref.qualifier))
+    })
+  }
+
+  // ── inject methods ──────────────────────────────────────────────────────
+
+  private injectIntoSelect(node: SelectQueryNode): SelectQueryNode {
+    const fromPreds = this.collectFromPredicates(node.from?.froms)
+    const newJoins = this.rewriteJoins(node.joins)
+    const joinsChanged = newJoins !== node.joins
+    if (fromPreds.length === 0 && !joinsChanged) return node
+
+    let where = node.where
+    for (const p of fromPreds) where = this.appendWhere(where, p)
+    return { ...node, where, joins: newJoins }
+  }
+
+  private injectIntoUpdate(node: UpdateQueryNode): UpdateQueryNode {
+    if (!node.table) return node
+    // Only a statically resolvable single-table target is safe to rewrite.
+    // Kysely emits ListNode for multi-table UPDATE and may accept raw target
+    // expressions; neither form has unambiguous ownership/filter semantics.
+    // The target table's tenant filter goes into the outer WHERE — UPDATE
+    // has no "ON clause" for its target, and there's no LEFT-JOIN-style
+    // NULL-row hazard for the target itself.
+    const targetRef = this.resolveTableRef(node.table)
+    if (!targetRef) {
+      throw new Error(
+        `TenantFilterPlugin: UPDATE target shape ${node.table.kind} is not supported. ` +
+        `Use a single statically named table, or bypassTenant() only for a ` +
+        `reviewed operation with explicit tenant predicates.`,
+      )
+    }
+    const fromPreds: OperationNode[] = []
+    if (this.tables.has(targetRef.tableName)) {
+      this.assertTenantOwnershipIsNotUpdated(node.updates, targetRef.tableName)
+      fromPreds.push(this.buildTenantPredicate(targetRef.qualifier))
+    }
+    // UPDATE … FROM list (auxiliary tables): same FROM-clause logic as SELECT.
+    fromPreds.push(...this.collectFromPredicates(node.from?.froms))
+    // UPDATE … JOIN: filter inside each JOIN's ON, same reasoning as SELECT.
+    const newJoins = this.rewriteJoins(node.joins)
+    const joinsChanged = newJoins !== node.joins
+    if (fromPreds.length === 0 && !joinsChanged) return node
+
+    let where = node.where
+    for (const p of fromPreds) where = this.appendWhere(where, p)
+    return { ...node, where, joins: newJoins }
+  }
+
+  private injectIntoDelete(node: DeleteQueryNode): DeleteQueryNode {
+    const fromPreds = [
+      ...this.collectFromPredicates(node.from?.froms),
+      ...this.collectFromPredicates(node.using?.tables),
+    ]
+    // DELETE … USING / JOIN: same handling — joined-side filter into ON.
+    const newJoins = this.rewriteJoins(node.joins)
+    const joinsChanged = newJoins !== node.joins
+    if (fromPreds.length === 0 && !joinsChanged) return node
+
+    let where = node.where
+    for (const p of fromPreds) where = this.appendWhere(where, p)
+    return { ...node, where, joins: newJoins }
+  }
+
+  private injectIntoInsert(node: InsertQueryNode): InsertQueryNode {
+    if (!node.into) return node
+    const tableName = node.into.table.identifier.name
+    if (!this.tables.has(tableName)) return node
+
+    if (
+      node.replace ||
+      node.onConflict ||
+      node.onDuplicateKey ||
+      node.orAction?.action.toLowerCase() === 'replace'
+    ) {
+      throw new Error(
+        `TenantFilterPlugin: upsert/replace is not supported for tenant-aware ` +
+        `table ${tableName}. Use a tenant-scoped UPDATE followed by INSERT, or ` +
+        `bypassTenant() only after proving the conflict key includes tenant_id.`,
+      )
+    }
+
+    const columns = node.columns ?? []
+    const tenantColIdx = columns.findIndex(
+      (c) => ColumnNode.is(c) && c.column.name === TENANT_ID_COLUMN,
+    )
+
+    const valuesNode = node.values
+    if (!valuesNode || !ValuesNode.is(valuesNode)) {
+      // INSERT … SELECT or INSERT … DEFAULT VALUES into a tenant-aware
+      // table. The inner SELECT (if any) still gets filtered by the
+      // OperationNodeTransformer recursion in transformInsertQuery, so
+      // the *rows* selected match the current tenant — but the INSERT
+      // projection itself doesn't get tenant_id stamped, so the column
+      // either isn't in the target list at all or carries through
+      // whatever the source SELECT projected (potentially the wrong
+      // tenant). Relying on DB NOT NULL to catch this is a runtime
+      // failure mode we'd rather refuse explicitly. Mirror the MERGE
+      // policy: fail loud at the call site.
+      throw new Error(
+        `TenantFilterPlugin: INSERT INTO ${tableName} ... SELECT (or DEFAULT VALUES) ` +
+        `is not supported for tenant-aware tables. Wrap the operation in ` +
+        `bypassTenant() and explicitly guarantee tenant_id if it is intentional.`,
+      )
+    }
+
+    if (tenantColIdx >= 0) {
+      // Already in column list — overwrite the per-row value at that index.
+      const newRows = valuesNode.values.map((row) => {
+        if (PrimitiveValueListNode.is(row)) {
+          const newVals = row.values.slice()
+          newVals[tenantColIdx] = this.tid
+          return PrimitiveValueListNode.create(newVals)
+        }
+        if (ValueListNode.is(row)) {
+          const newVals = row.values.slice()
+          newVals[tenantColIdx] = ValueNode.create(this.tid)
+          return ValueListNode.create(newVals)
+        }
+        return row
+      })
+      return {
+        ...node,
+        values: ValuesNode.create(newRows as ReadonlyArray<typeof valuesNode.values[number]>),
+      }
+    }
+
+    // tenant_id not in column list — append column + per-row value.
+    const newColumns = [...columns, ColumnNode.create(TENANT_ID_COLUMN)]
+    const newRows = valuesNode.values.map((row) => {
+      if (PrimitiveValueListNode.is(row)) {
+        return PrimitiveValueListNode.create([...row.values, this.tid])
+      }
+      if (ValueListNode.is(row)) {
+        return ValueListNode.create([...row.values, ValueNode.create(this.tid)])
+      }
+      return row
+    })
+    return {
+      ...node,
+      columns: newColumns,
+      values: ValuesNode.create(newRows as ReadonlyArray<typeof valuesNode.values[number]>),
+    }
+  }
+
+  private assertTenantOwnershipIsNotUpdated(
+    updates: ReadonlyArray<ColumnUpdateNode> | undefined,
+    tableName: string,
+  ): void {
+    if (!updates) return
+    for (const update of updates) {
+      const columnName = this.resolveColumnName(update.column)
+      if (columnName === null) {
+        throw new Error(
+          `TenantFilterPlugin: UPDATE uses a dynamic/raw column name on ` +
+          `tenant-aware table ${tableName}. Use statically named columns so ` +
+          `tenant_id ownership can be verified.`,
+        )
+      }
+      if (columnName === TENANT_ID_COLUMN) {
+        throw new Error(
+          `TenantFilterPlugin: UPDATE cannot change tenant_id on tenant-aware ` +
+          `table ${tableName}. Move ownership through a reviewed cross-tenant ` +
+          `operation, not a tenant-scoped UPDATE.`,
+        )
+      }
+    }
+  }
+
+  private resolveColumnName(node: OperationNode): string | null {
+    if (ColumnNode.is(node)) return node.column.name
+    if (ReferenceNode.is(node) && ColumnNode.is(node.column)) {
+      return node.column.column.name
+    }
+    return null
+  }
+}
+
+/**
+ * Kysely plugin entry point. Builds a fresh transformer per query so
+ * the captured tenant id can't leak across requests.
+ */
+export class TenantFilterPlugin implements KyselyPlugin {
+  private readonly tables: ReadonlySet<string>
+  private readonly context: TenantContextReader
+  private readonly onMissingContext: MissingTenantContextPolicy
+
+  constructor(
+    tables: ReadonlySet<string>,
+    options: TenantFilterPluginOptions = {},
+  ) {
+    // The catalogue is a security boundary. Snapshot it so later consumer
+    // mutation cannot silently change which tables receive tenant predicates.
+    this.tables = new Set(tables)
+    this.context = options.context ?? tenantContext
+    this.onMissingContext = options.onMissingContext ?? 'passthrough'
+  }
+
+  transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+    const ctx = this.context.getStore()
+    if (!ctx) return this.handleMissingContext(args.node)
+    if (ctx.bypass) return args.node
+    if (!Number.isSafeInteger(ctx.tenantId) || ctx.tenantId == null || ctx.tenantId <= 0) {
+      throw new Error(
+        'TenantFilterPlugin: non-bypass tenant context must contain a positive ' +
+        'safe-integer tenantId. Use withTenant() to establish tenant work, or ' +
+        'bypassTenant() for a reviewed cross-tenant operation.',
+      )
+    }
+
+    const transformer = new TenantFilterTransformer(this.tables, ctx.tenantId)
+    return transformer.transformNode(args.node) as RootOperationNode
+  }
+
+  private handleMissingContext(node: RootOperationNode): RootOperationNode {
+    if (this.onMissingContext === 'throw') {
+      throw new Error(
+        'TenantFilterPlugin: query executed without a valid tenant context. ' +
+        'Wrap tenant work in withTenant()/tenantContext.run(), or use ' +
+        'bypassTenant() for a reviewed cross-tenant operation.',
+      )
+    }
+    return node
+  }
+
+  async transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+    return args.result
+  }
+}

package/src/db/tenant-context.ts

@@ -0,0 +1,51 @@
+/**
+ * Package-owned tenant context, propagated through async calls via
+ * AsyncLocalStorage. Set by tenantMiddleware; read by the Kysely
+ * tenant-filter plugin when transforming queries.
+ *
+ * `bypass: true` tells the plugin to leave queries unmodified — used by
+ * cross-tenant system queries (OAuth callback before tenant resolution,
+ * Hub admin tenant CRUD, etc.). See `bypass-tenant.ts` for the
+ * caller-facing helper.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+export interface TenantStore {
+  /** null = no tenant resolved (only valid when bypass=true). */
+  readonly tenantId: number | null
+  /** When true, the Kysely plugin leaves queries unmodified. */
+  readonly bypass: boolean
+}
+
+export const tenantContext = new AsyncLocalStorage<TenantStore>()
+
+/** Returns the current tenant store, or null if no run() is on the call stack. */
+export function getCurrentTenant(): TenantStore | null {
+  return tenantContext.getStore() ?? null
+}
+
+/**
+ * Run `fn` with bypass=true. Preserves the existing tenantId so logs
+ * that read tenant context still work; only the auto-injection is
+ * suppressed. Outside an existing tenantContext.run, treats as
+ * { tenantId: null, bypass: true }.
+ */
+export async function withBypass<T>(fn: () => T | Promise<T>): Promise<T> {
+  const current = tenantContext.getStore()
+  const next: TenantStore = current
+    ? { tenantId: current.tenantId, bypass: true }
+    : { tenantId: null,             bypass: true }
+  return tenantContext.run(next, fn)
+}
+
+/**
+ * Run `fn` scoped to one tenant. Background jobs run outside the HTTP
+ * middleware lifecycle and must use this helper before touching tenant-aware
+ * tables; otherwise there is no context for the Kysely plugin to read.
+ */
+export async function withTenant<T>(tenantId: number, fn: () => T | Promise<T>): Promise<T> {
+  if (!Number.isSafeInteger(tenantId) || tenantId <= 0) {
+    throw new RangeError('withTenant: tenantId must be a positive safe integer')
+  }
+  return tenantContext.run({ tenantId, bypass: false }, fn)
+}

package/src/guide/index.ts

@@ -0,0 +1,5 @@
+export { parseGuideMarkdown, stripGuideAiContext } from './markdown.ts'
+export { createGuideService } from './service.ts'
+export { createFileGuideContentSource, isGuideIdentifier } from './source.ts'
+export { GuideError } from './types.ts'
+export type * from './types.ts'

package/src/guide/markdown.ts

@@ -0,0 +1,108 @@
+import { GuideError } from './types.ts'
+import type { GuideFrontmatter, ParsedGuideMarkdown } from './types.ts'
+
+const AI_CONTEXT_START = /<!--\s*ai-context\b/gi
+
+/**
+ * Removes private authoring context from user-facing markdown. An unclosed
+ * marker removes the remainder of the document (fail-closed).
+ */
+export function stripGuideAiContext(markdown: string): string {
+  if (typeof markdown !== 'string') malformed()
+
+  let output = ''
+  let cursor = 0
+  AI_CONTEXT_START.lastIndex = 0
+  for (;;) {
+    const match = AI_CONTEXT_START.exec(markdown)
+    if (!match) break
+    output += markdown.slice(cursor, match.index)
+    const end = markdown.indexOf('-->', AI_CONTEXT_START.lastIndex)
+    if (end < 0) return output
+    cursor = end + 3
+    AI_CONTEXT_START.lastIndex = cursor
+  }
+  return output + markdown.slice(cursor)
+}
+
+/** Tiny, deliberately limited frontmatter parser for title and description. */
+export function parseGuideMarkdown(raw: string): ParsedGuideMarkdown {
+  if (typeof raw !== 'string') malformed()
+  const document = raw.startsWith('\uFEFF') ? raw.slice(1) : raw
+  const first = readLine(document, 0)
+  if (first.value !== '---') {
+    return freezeParsed({ title: '' }, stripGuideAiContext(document))
+  }
+
+  const values: Record<string, string> = Object.create(null) as Record<string, string>
+  let cursor = first.next
+  let closed = false
+  while (cursor <= document.length) {
+    const line = readLine(document, cursor)
+    if (line.value === '---') {
+      cursor = line.next
+      closed = true
+      break
+    }
+    parseFrontmatterLine(line.value, values)
+    if (line.next === cursor) break
+    cursor = line.next
+  }
+  if (!closed) malformed()
+
+  const title = values['title'] ?? ''
+  const description = values['description']
+  const frontmatter: GuideFrontmatter = Object.freeze({
+    title,
+    ...(description === undefined ? {} : { description }),
+  })
+  return Object.freeze({
+    frontmatter,
+    body: stripGuideAiContext(document.slice(cursor)),
+  })
+}
+
+function parseFrontmatterLine(line: string, values: Record<string, string>): void {
+  const trimmed = line.trim()
+  if (!trimmed || trimmed.startsWith('#')) return
+  const match = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line)
+  if (!match) malformed()
+  const key = match[1]!
+  if (key !== 'title' && key !== 'description') malformed()
+  if (Object.hasOwn(values, key)) malformed()
+  values[key] = parseScalar(match[2]!)
+}
+
+function parseScalar(raw: string): string {
+  const value = raw.trim()
+  if (!value) return ''
+  const quote = value[0]
+  if (quote !== '"' && quote !== "'") return value
+  if (value.length < 2 || value.at(-1) !== quote) malformed()
+  const inner = value.slice(1, -1)
+  if (quote === "'") return inner.replace(/''/g, "'")
+  try {
+    return JSON.parse(value) as string
+  } catch {
+    malformed()
+  }
+}
+
+function readLine(value: string, start: number): { value: string; next: number } {
+  const lf = value.indexOf('\n', start)
+  if (lf < 0) {
+    return { value: value.slice(start).replace(/\r$/, ''), next: value.length }
+  }
+  return { value: value.slice(start, lf).replace(/\r$/, ''), next: lf + 1 }
+}
+
+function freezeParsed(frontmatter: GuideFrontmatter, body: string): ParsedGuideMarkdown {
+  return Object.freeze({ frontmatter: Object.freeze(frontmatter), body })
+}
+
+function malformed(): never {
+  throw new GuideError({
+    code: 'malformed_document',
+    message: 'Guide document is malformed',
+  })
+}