@malloy-publisher/server 0.0.203 → 0.0.205

package/src/service/annotations.ts

@@ -0,0 +1,91 @@
+import { Annotations, type ModelDef } from "@malloydata/malloy";
+
+/**
+ * The raw IR annotation bundle. Workaround: `@malloydata/malloy` exports the
+ * `Annotations` view but not the underlying `AnnotationsDef` type, so we
+ * recover it from the view's constructor parameter. Replace with a direct
+ * `import type { AnnotationsDef }` once malloy exports it.
+ */
+export type AnnotationsDef = NonNullable<
+   ConstructorParameters<typeof Annotations>[0]
+>;
+
+/**
+ * True if a route belongs to Malloy's own reserved namespace rather than an
+ * application. Malloy claims the empty route (`''` — MOTLY tags / render
+ * config) and the whole punctuation-sigil namespace (`!` `@` `"` `:`, and
+ * any punct-only route — Form 2 reserves all of them). Everything else is a
+ * bracketed app route (`#(doc)`, `#<label>`, …).
+ *
+ * TODO: this route classification belongs in `@malloydata/malloy` core,
+ * beside `parsePrefix` — otherwise every consumer reinvents it. Remove when
+ * core exports an equivalent.
+ */
+export function isReservedRoute(route: string): boolean {
+   return route === "" || !/[\p{L}\p{N}]/u.test(route);
+}
+
+/**
+ * The model (`##`) annotation bundle for one model, folded across its
+ * import/extend lineage.
+ *
+ * Workaround: malloy 0.0.405 moved model annotations off `ModelDef.annotation`
+ * and onto `ModelDef.modelAnnotations` (a `modelID → {ownNotes, inheritsFrom}`
+ * registry), folded by the `getModelAnnotations` helper — which malloy does
+ * NOT export from its public barrel. We replicate it (matching
+ * `@malloydata/malloy/dist/model/annotation_utils.js`): a post-order DFS over
+ * `inheritsFrom` (cycle-safe, each model emitted once at its most-ancestral
+ * slot) yields ancestral-first / local-last order, folded into an
+ * `AnnotationsDef` whose `inherits` chain runs most-ancestral-deepest / local
+ * at the top.
+ *
+ * A model that contributes no `##` of its own adds NO link to the chain (we
+ * skip empty `ownNotes`), so `.notes` returns the nearest ancestor that
+ * actually has notes — not an empty local node. This matters because `.notes`
+ * feeds file-level `##(authorize)` enforcement: an imported model's
+ * `##(authorize)` must still flow into an importing file that declares no `##`
+ * of its own. We also copy only `notes`/`blockNotes` rather than spreading
+ * `ownNotes`, whose own `inherits` would otherwise leak in. Replace with a
+ * direct `import { getModelAnnotations }` once malloy exports it.
+ */
+export function modelAnnotations(modelDef: ModelDef): AnnotationsDef {
+   const registry = modelDef.modelAnnotations ?? {};
+   const visited = new Set<string>();
+   const order: string[] = [];
+   const visit = (id: string): void => {
+      if (visited.has(id)) return;
+      visited.add(id);
+      const entry = registry[id];
+      if (!entry) return;
+      for (const dep of entry.inheritsFrom) visit(dep);
+      order.push(id); // post-order: ancestors precede the model itself
+   };
+   visit(modelDef.modelID);
+
+   // Fold most-ancestral → local so the local model lands at the top of the
+   // resulting `inherits` chain. Models with no own notes add no link.
+   let folded: AnnotationsDef | undefined;
+   for (const id of order) {
+      const own = registry[id].ownNotes;
+      if (!own.notes?.length && !own.blockNotes?.length) continue;
+      folded = {
+         notes: own.notes,
+         blockNotes: own.blockNotes,
+         inherits: folded,
+      };
+   }
+   return folded ?? {};
+}
+
+/**
+ * Every annotation text on an entity — its own `notes` and `blockNotes`
+ * plus everything inherited from its ancestors. All of an entity's
+ * annotations apply; none are dropped by source location. Returns
+ * `undefined`, not `[]`, when empty, to match the optional API shape.
+ */
+export function annotationTexts(
+   annote: AnnotationsDef | undefined,
+): string[] | undefined {
+   const texts = new Annotations(annote).texts();
+   return texts.length > 0 ? texts : undefined;
+}

package/src/service/authorize.spec.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "bun:test";
+import {
+   collectAuthorizeExprs,
+   isProbeTrue,
+   parseAuthorizeAnnotation,
+} from "./authorize";
+
+describe("isProbeTrue", () => {
+   it("grants only on a genuine true / 1 / 'true'", () => {
+      expect(isProbeTrue(true)).toBe(true);
+      expect(isProbeTrue(1)).toBe(true);
+      expect(isProbeTrue("true")).toBe(true);
+   });
+
+   it("denies on anything else (fail closed)", () => {
+      for (const v of [false, 0, "false", "", null, undefined, {}, "TRUE", 2]) {
+         expect(isProbeTrue(v)).toBe(false);
+      }
+   });
+});
+
+describe("parseAuthorizeAnnotation", () => {
+   it("parses a source-level #(authorize) expression", () => {
+      expect(parseAuthorizeAnnotation(`#(authorize) "$ROLE = 'analyst'"`)).toBe(
+         "$ROLE = 'analyst'",
+      );
+   });
+
+   it("parses a file-level ##(authorize) expression", () => {
+      expect(parseAuthorizeAnnotation(`##(authorize) "$ROLE = 'admin'"`)).toBe(
+         "$ROLE = 'admin'",
+      );
+   });
+
+   it("tolerates the trailing newline Malloy keeps on note text", () => {
+      expect(
+         parseAuthorizeAnnotation(`#(authorize) "$REGION = 'us-west'"\n`),
+      ).toBe("$REGION = 'us-west'");
+   });
+
+   it("preserves inner single quotes (Malloy string literals)", () => {
+      expect(
+         parseAuthorizeAnnotation(`#(authorize) "$TENANT in ['a', 'b']"`),
+      ).toBe("$TENANT in ['a', 'b']");
+   });
+
+   it("unescapes escaped inner double quotes", () => {
+      expect(parseAuthorizeAnnotation(`#(authorize) "$NAME = \\"foo\\""`)).toBe(
+         `$NAME = "foo"`,
+      );
+   });
+
+   it("handles a constant false gate", () => {
+      expect(parseAuthorizeAnnotation(`#(authorize) "false"`)).toBe("false");
+   });
+
+   it("returns null for non-authorize annotations", () => {
+      expect(
+         parseAuthorizeAnnotation(`#(filter) dimension=x type=equal`),
+      ).toBeNull();
+      expect(parseAuthorizeAnnotation(`##! experimental.givens`)).toBeNull();
+      expect(parseAuthorizeAnnotation(`## just a doc comment`)).toBeNull();
+      expect(parseAuthorizeAnnotation(`# plain`)).toBeNull();
+      expect(parseAuthorizeAnnotation(``)).toBeNull();
+   });
+
+   it("throws when the body is not quoted", () => {
+      expect(() =>
+         parseAuthorizeAnnotation(`#(authorize) $ROLE = 'analyst'`),
+      ).toThrow(/double-quoted/);
+   });
+
+   it("throws on mismatched / unterminated quotes", () => {
+      expect(() =>
+         parseAuthorizeAnnotation(`#(authorize) "$ROLE = 'analyst'`),
+      ).toThrow(/mismatched quotes/);
+   });
+
+   it("throws on an empty expression body", () => {
+      expect(() => parseAuthorizeAnnotation(`#(authorize) ""`)).toThrow(
+         /empty expression/,
+      );
+   });
+
+   it("throws on content after the closing quote", () => {
+      expect(() =>
+         parseAuthorizeAnnotation(`#(authorize) "$ROLE = 'a'" extra`),
+      ).toThrow(/unexpected content/);
+   });
+
+   it("throws when the prefix has no body", () => {
+      expect(() => parseAuthorizeAnnotation(`#(authorize)`)).toThrow(
+         /double-quoted/,
+      );
+   });
+});
+
+describe("collectAuthorizeExprs", () => {
+   it("collects authorize expressions in declaration order", () => {
+      expect(
+         collectAuthorizeExprs([
+            `##(authorize) "$ROLE = 'admin'"`,
+            `#(filter) dimension=x type=equal`,
+            `#(authorize) "$REGION = 'us-west'"`,
+         ]),
+      ).toEqual(["$ROLE = 'admin'", "$REGION = 'us-west'"]);
+   });
+
+   it("returns [] when there are no authorize annotations", () => {
+      expect(
+         collectAuthorizeExprs([`#(filter) dimension=x type=equal`, `## doc`]),
+      ).toEqual([]);
+   });
+
+   it("keeps duplicate gates (no dedup — OR semantics)", () => {
+      expect(
+         collectAuthorizeExprs([
+            `#(authorize) "$ROLE = 'admin'"`,
+            `#(authorize) "$ROLE = 'admin'"`,
+         ]),
+      ).toEqual(["$ROLE = 'admin'", "$ROLE = 'admin'"]);
+   });
+
+   it("propagates the throw from a malformed authorize annotation", () => {
+      expect(() =>
+         collectAuthorizeExprs([
+            `#(authorize) "$ROLE = 'admin'"`,
+            `#(authorize) "unterminated`,
+         ]),
+      ).toThrow(/mismatched quotes/);
+   });
+});

package/src/service/authorize.ts

@@ -0,0 +1,241 @@
+/**
+ * `#(authorize)` / `##(authorize)` annotation parsing.
+ *
+ * Annotation format:
+ *   #(authorize)  "<malloy-bool-expr>"   — source-level, on a single source
+ *   ##(authorize) "<malloy-bool-expr>"   — file/model-level, applies to the file
+ *
+ * The body is a single double-quoted Malloy boolean expression that references
+ * declared givens (`$NAME`), e.g. `#(authorize) "$ROLE = 'analyst'"`. The
+ * expression itself routinely contains single quotes (Malloy string literals),
+ * so we cannot reuse filter.ts's whitespace tokenizer — we unwrap exactly one
+ * layer of double quotes and hand the inner expression back untouched.
+ *
+ * This module parses, collects, and (at compile time) validates authorize
+ * annotations. Evaluating the expression — the actual access gate — lands in a
+ * later PR and reuses `buildAuthorizeProbe`. Kept light so it bundles cleanly
+ * into the package-load worker (the only non-type import is the shared
+ * `ModelCompilationError`).
+ */
+
+import { type GivenValue } from "@malloydata/malloy";
+import { ModelCompilationError } from "../errors";
+
+const SOURCE_PREFIX = "#(authorize)";
+const FILE_PREFIX = "##(authorize)";
+
+/** source name → effective authorize expressions (file-level then source-level). */
+export type AuthorizeMap = Map<string, string[]>;
+
+/**
+ * Build the synthetic probe query that evaluates a source's authorize
+ * expressions. Each expression becomes a boolean `select` column over a
+ * one-row, warehouse-independent DuckDB source (the `"duckdb"` sandbox is
+ * registered for every package, so this never touches the model's real
+ * warehouse). Compiling this probe validates the expressions against the
+ * model's `given:` block (unknown givens and source-field references surface as
+ * compile errors); running it evaluates the gate. The reserved dummy column
+ * name is deliberately obscure so a real authorize expression is unlikely to
+ * collide with it — a bare field reference in an expression is meant to fail.
+ */
+export function buildAuthorizeProbe(exprs: string[]): string {
+   const selects = exprs
+      .map((expr, i) => `__auth_${i} is (${expr})`)
+      .join("\n      ");
+   return `run: duckdb.sql("SELECT 1 AS __authorize_probe_row") -> {
+    select:
+      ${selects}
+    limit: 1
+  }`;
+}
+
+/**
+ * Strict, fail-closed truthiness for a probe result cell. DuckDB (the probe's
+ * connection) returns a native boolean, but normalize defensively: only a real
+ * `true` / SQL `1` / `"true"` grants access. null, undefined, `0`, `false`, a
+ * missing cell — anything else — denies.
+ */
+export function isProbeTrue(cell: unknown): boolean {
+   return cell === true || cell === 1 || cell === "true";
+}
+
+/** Minimal materializer surface needed to compile (not run) the probe. */
+interface AuthorizeProbeCompiler {
+   loadQuery(query: string): { getPreparedQuery(): Promise<unknown> };
+}
+
+/** Minimal materializer surface needed to run the probe (the runtime gate). */
+interface AuthorizeProbeExecutor {
+   loadQuery(query: string): {
+      run(opts: {
+         rowLimit?: number;
+         givens?: Record<string, GivenValue>;
+      }): Promise<{ data: { value: ReadonlyArray<Record<string, unknown>> } }>;
+   };
+}
+
+/**
+ * Evaluate a source's authorize disjunction against the supplied givens.
+ * Returns true if ANY expression evaluates true (OR semantics).
+ *
+ * Each expression is probed INDEPENDENTLY rather than batched into one query.
+ * That is what preserves OR semantics: an expression that can't be evaluated —
+ * e.g. it references a given the request didn't supply, so Malloy throws "no
+ * value" — counts as "does not grant" (false), and the next disjunct is still
+ * tried. Batching them would let a missing given in one unused branch throw and
+ * sink the whole request (denying an admin who matched a different branch).
+ *
+ * Per-branch failures are swallowed to false (fail closed at the branch level);
+ * access is granted only if some branch genuinely returns true. Short-circuits
+ * on the first true. Returns false (→ caller denies) if none grant.
+ */
+export async function evaluateAuthorize(
+   executor: AuthorizeProbeExecutor,
+   exprs: string[],
+   givens: Record<string, GivenValue>,
+): Promise<boolean> {
+   for (const expr of exprs) {
+      try {
+         const result = await executor
+            .loadQuery(buildAuthorizeProbe([expr]))
+            .run({ rowLimit: 1, givens });
+         const row = result?.data?.value?.[0];
+         if (row && isProbeTrue(row.__auth_0)) {
+            return true;
+         }
+      } catch {
+         // This disjunct can't be evaluated (e.g. a referenced given has no
+         // value) — treat as not-granting and try the next. It does not fail
+         // the whole request, which is what keeps OR semantics intact.
+         continue;
+      }
+   }
+   return false;
+}
+
+/** A source plus its effective authorize expressions. */
+interface SourceWithAuthorize {
+   name?: string;
+   authorize?: string[];
+}
+
+/**
+ * Translation-time validation. For each source carrying authorize expressions,
+ * compile the probe (no givens, no DB execution) so unknown givens and
+ * source-field references surface as compile errors at model load instead of
+ * first request. Type mismatches such as `$ROLE = 5` are NOT Malloy compile
+ * errors, so they are not caught here — they fail closed at the runtime gate.
+ *
+ * Throws `ModelCompilationError` naming the source on the first invalid
+ * annotation. Shared by `Model.create` and the package-load worker so both
+ * compile paths validate identically.
+ */
+export async function validateAuthorizeProbes(
+   compiler: AuthorizeProbeCompiler,
+   sources: readonly SourceWithAuthorize[],
+): Promise<void> {
+   for (const source of sources) {
+      const exprs = source.authorize;
+      if (!exprs || exprs.length === 0) continue;
+      try {
+         await compiler
+            .loadQuery(buildAuthorizeProbe(exprs))
+            .getPreparedQuery();
+      } catch (err) {
+         const detail = err instanceof Error ? err.message : String(err);
+         throw new ModelCompilationError({
+            message: `Invalid #(authorize) annotation on source "${source.name ?? "(unnamed)"}" [${exprs.join(" | ")}]: ${detail}`,
+         });
+      }
+   }
+}
+
+/**
+ * Parse a single annotation string into its authorize expression.
+ *
+ * Returns the inner expression for a well-formed `#(authorize)` / `##(authorize)`
+ * annotation, `null` if the string is not an authorize annotation at all, and
+ * throws if it looks like one but is malformed (missing quotes, mismatched
+ * quotes, or an empty body). The throw is what later compile-time validation
+ * turns into a model-load error.
+ */
+export function parseAuthorizeAnnotation(annotation: string): string | null {
+   const trimmed = annotation.trim();
+
+   let body: string;
+   // Check the file-level prefix first — `##(authorize)` also starts with `#`.
+   if (trimmed.startsWith(FILE_PREFIX)) {
+      body = trimmed.slice(FILE_PREFIX.length).trim();
+   } else if (trimmed.startsWith(SOURCE_PREFIX)) {
+      body = trimmed.slice(SOURCE_PREFIX.length).trim();
+   } else {
+      return null;
+   }
+
+   return unwrapQuotedExpression(body);
+}
+
+/**
+ * Extract authorize expressions from a list of annotation strings, preserving
+ * declaration order. Non-authorize annotations are ignored; there is no dedup —
+ * every authorize annotation is an independent gate (OR semantics), so repeats
+ * are kept. Propagates the throw from a malformed authorize annotation.
+ */
+export function collectAuthorizeExprs(annotations: string[]): string[] {
+   const exprs: string[] = [];
+   for (const annotation of annotations) {
+      const expr = parseAuthorizeAnnotation(annotation);
+      if (expr !== null) {
+         exprs.push(expr);
+      }
+   }
+   return exprs;
+}
+
+/**
+ * Strip exactly one layer of wrapping double quotes off the annotation body and
+ * return the inner expression. Inner single quotes are part of the expression
+ * and pass through untouched; `\"` and `\\` inside the string are unescaped.
+ */
+function unwrapQuotedExpression(body: string): string {
+   if (body.length < 2 || body[0] !== '"') {
+      throw new Error(
+         `authorize annotation expression must be a double-quoted string, got: ${body || "(empty)"}`,
+      );
+   }
+
+   let expr = "";
+   let i = 1;
+   let closed = false;
+   for (; i < body.length; i++) {
+      const ch = body[i];
+      if (ch === "\\" && i + 1 < body.length) {
+         const next = body[i + 1];
+         if (next === '"' || next === "\\") {
+            expr += next;
+            i++;
+            continue;
+         }
+      }
+      if (ch === '"') {
+         closed = true;
+         i++;
+         break;
+      }
+      expr += ch;
+   }
+
+   if (!closed) {
+      throw new Error(`authorize annotation has mismatched quotes: ${body}`);
+   }
+   const rest = body.slice(i).trim();
+   if (rest.length > 0) {
+      throw new Error(
+         `authorize annotation has unexpected content after the expression: ${rest}`,
+      );
+   }
+   if (expr.trim().length === 0) {
+      throw new Error("authorize annotation has an empty expression body");
+   }
+   return expr;
+}