rastack 0.0.50 → 0.0.52

package/src/plugin/core.ts

@@ -0,0 +1,236 @@
+/**
+ * The dev-server schema compiler — the way around "classes need a compile
+ * step".
+ *
+ * Class/interface entities have no runtime shape (TypeScript erases their
+ * types), so *something* must run the `ts.Program` + `TypeChecker` to read
+ * fields, `DbConfig` brands and FK types off them. The insight is that it
+ * doesn't have to be a command the developer runs: this module packages the
+ * same `analyzeProject`/`compile` pass the CLI uses so it can live **inside
+ * the dev server that is already running** — a bundler plugin
+ * (`rastackPlugin`, Vite/Rollup-compatible) or a bare filesystem watcher
+ * (`startRastackWatcher`, for anything else). The schema recompiles on every
+ * save, the app imports it as the `virtual:rastack-manifest` module, and
+ * `rastack-env.d.ts` is rewritten so string-key row types stay fresh — the
+ * developer never runs `rastack compile`.
+ *
+ * Design mirrors the rest of `tools/src`: the decisions live here as pure
+ * (or thin-IO) functions, tested in `tools/test/plugin.spec.ts`; the plugin
+ * object in `./index.ts` is a shell over {@link createSchemaState}.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { analyzeProject, buildManifest, compile } from "../compile";
+import type { EntityDiagnostic, Manifest } from "../compile";
+
+/** The module id apps import the live manifest from. */
+export const VIRTUAL_MANIFEST_ID = "virtual:rastack-manifest";
+
+/** The resolved (bundler-internal) id — Rollup convention: `\0` prefix. */
+export const RESOLVED_MANIFEST_ID = "\0" + VIRTUAL_MANIFEST_ID;
+
+/**
+ * The auto-registration module the plugin injects into `index.html`: it sets
+ * `globalThis.__RASTACK_MANIFEST__` before the app boots, which is what lets
+ * `<RAStackProvider mode="local">` (and bare `useData(Airport)`) run with
+ * **no manifest wiring in app code at all**. Kept un-prefixed (no `\0`) so
+ * its dev-server URL is a plain `/@id/…`.
+ */
+export const VIRTUAL_REGISTER_ID = "virtual:rastack-manifest/register";
+
+/** The key the register module assigns (mirrored in `rastack/hooks`). */
+export const GLOBAL_MANIFEST_KEY = "__RASTACK_MANIFEST__";
+
+export interface RastackPluginOptions {
+  /**
+   * Directory (or single file) scanned for entities — classes, interfaces
+   * and `resource()` calls alike, recursively (co-located definitions work).
+   * Default `"resources"`; pass `"src"` (or `"."`) for co-located entities.
+   */
+  resourcesDir?: string;
+  /**
+   * Where the artifacts land: `schema.rastack.json`, `openapi.json`,
+   * `rastack-env.d.ts` (the string-key type registry) and
+   * `rastack-plugin.d.ts` (types for the virtual module). Default
+   * `".rastack"` — include it in `tsconfig.json` once.
+   */
+  outDir?: string;
+  /** Skip writing the artifacts to disk (virtual module only). Default false. */
+  emitFiles?: boolean;
+  /** Where compile problems are reported. Default `console.error`. */
+  onError?: (error: unknown) => void;
+}
+
+export interface ResolvedPluginOptions {
+  resourcesDir: string;
+  outDir: string;
+  emitFiles: boolean;
+  onError: (error: unknown) => void;
+}
+
+export function resolveOptions(
+  options: RastackPluginOptions = {},
+  root: string = process.cwd(),
+): ResolvedPluginOptions {
+  return {
+    resourcesDir: path.resolve(root, options.resourcesDir ?? "resources"),
+    outDir: path.resolve(root, options.outDir ?? ".rastack"),
+    emitFiles: options.emitFiles !== false,
+    onError:
+      options.onError ??
+      ((error) =>
+        console.error(
+          `[rastack] schema compile failed — serving the last good manifest\n` +
+            `${error instanceof Error ? error.message : String(error)}`,
+        )),
+  };
+}
+
+/**
+ * Whether a changed file should trigger a schema recompile: a `.ts`/`.tsx`
+ * source under the scanned directory that is not itself an emitted artifact.
+ */
+export function isEntitySource(
+  file: string,
+  options: Pick<ResolvedPluginOptions, "resourcesDir" | "outDir">,
+): boolean {
+  const resolved = path.resolve(file);
+  if (!/\.tsx?$/.test(resolved) || resolved.endsWith(".d.ts")) return false;
+  if (within(resolved, options.outDir)) return false;
+  return (
+    within(resolved, options.resourcesDir) || resolved === options.resourcesDir
+  );
+}
+
+function within(file: string, dir: string): boolean {
+  const rel = path.relative(dir, file);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+/** The virtual module's source — the manifest as a plain ES module. */
+export function manifestModuleCode(manifest: Manifest): string {
+  const json = JSON.stringify(manifest);
+  return (
+    `// virtual:rastack-manifest — compiled by the rastack dev-server plugin.\n` +
+    `const manifest = ${json};\n` +
+    `export default manifest;\n` +
+    `export { manifest };\n`
+  );
+}
+
+/**
+ * The register module's source: import the live manifest, publish it on the
+ * global the runtime falls back to. A separate module (rather than a side
+ * effect of the manifest module) so explicit `virtual:rastack-manifest`
+ * importers stay side-effect-free.
+ */
+export function registerModuleCode(): string {
+  return (
+    `// ${VIRTUAL_REGISTER_ID} — auto-injected by the rastack plugin.\n` +
+    `import manifest from ${JSON.stringify(VIRTUAL_MANIFEST_ID)};\n` +
+    `globalThis.${GLOBAL_MANIFEST_KEY} = manifest;\n` +
+    `export default manifest;\n`
+  );
+}
+
+/** Types for the virtual module, written once beside `rastack-env.d.ts`. */
+export function virtualModuleDts(): string {
+  return (
+    "// Generated by the rastack plugin — do not edit.\n" +
+    `declare module "${VIRTUAL_MANIFEST_ID}" {\n` +
+    '  const manifest: import("rastack/define").Manifest;\n' +
+    "  export default manifest;\n" +
+    "  export { manifest };\n" +
+    "}\n"
+  );
+}
+
+export interface SchemaState {
+  /**
+   * The virtual module's current source. Compiles (lazily) when stale; on a
+   * compile error reports via `onError` and keeps serving the last good
+   * manifest — a half-typed entity must not blank the running app.
+   */
+  code(): string;
+  /** The current manifest (same laziness/fallback as {@link code}). */
+  manifest(): Manifest;
+  /** Mark the schema stale — the next `code()`/`manifest()` recompiles. */
+  invalidate(): void;
+  /** The error from the most recent failed compile, if it is still failing. */
+  error(): unknown;
+  /** Non-error diagnostics from the last successful compile. */
+  diagnostics(): EntityDiagnostic[];
+  options: ResolvedPluginOptions;
+}
+
+/**
+ * The plugin's whole brain: lazy compile, invalidation, keep-last-good.
+ * Both the bundler plugin and the bare watcher drive this one object.
+ */
+export function createSchemaState(
+  options: RastackPluginOptions = {},
+  root?: string,
+): SchemaState {
+  const resolved = resolveOptions(options, root);
+  let current: { manifest: Manifest; diagnostics: EntityDiagnostic[] } | null =
+    null;
+  let stale = true;
+  let lastError: unknown = undefined;
+
+  const recompile = (): void => {
+    try {
+      const result = runCompile(resolved);
+      current = { manifest: result.manifest, diagnostics: result.diagnostics };
+      lastError = undefined;
+    } catch (error) {
+      lastError = error;
+      resolved.onError(error);
+      if (!current) throw error; // no last-good manifest to fall back to
+    } finally {
+      stale = false;
+    }
+  };
+
+  const ensure = (): { manifest: Manifest; diagnostics: EntityDiagnostic[] } => {
+    if (stale || !current) recompile();
+    return current!;
+  };
+
+  return {
+    code: () => manifestModuleCode(ensure().manifest),
+    manifest: () => ensure().manifest,
+    invalidate: () => {
+      stale = true;
+    },
+    error: () => lastError,
+    diagnostics: () => ensure().diagnostics,
+    options: resolved,
+  };
+}
+
+/**
+ * One compile pass: the same artifacts `rastack compile` writes (manifest,
+ * OpenAPI, `rastack-env.d.ts`), plus the virtual module's type declaration.
+ * With `emitFiles: false` it only analyses (nothing touches disk).
+ */
+export function runCompile(options: ResolvedPluginOptions): {
+  manifest: Manifest;
+  diagnostics: EntityDiagnostic[];
+} {
+  if (!options.emitFiles) {
+    // compile() always writes to disk; the analyse-only path applies the
+    // same error gate without touching the filesystem.
+    const { resources, diagnostics } = analyzeProject(options.resourcesDir);
+    const errors = diagnostics.filter((d) => d.severity === "error");
+    if (errors.length) throw new Error(errors.map((e) => e.message).join("\n"));
+    return { manifest: buildManifest(resources), diagnostics };
+  }
+
+  const result = compile(options.resourcesDir, options.outDir);
+  const dtsPath = path.join(options.outDir, "rastack-plugin.d.ts");
+  if (!fs.existsSync(dtsPath)) {
+    fs.writeFileSync(dtsPath, virtualModuleDts());
+  }
+  return { manifest: result.manifest, diagnostics: result.diagnostics };
+}

package/src/plugin/index.ts

@@ -0,0 +1,243 @@
+/**
+ * `rastack/plugin` — the schema compiles itself inside your dev server.
+ *
+ * Class and interface entities are pure types, so the manifest has to be
+ * derived by the TypeScript checker — but not by a command you run. Add the
+ * plugin to the bundler you already use and the whole `rastack compile`
+ * pass disappears into the dev loop:
+ *
+ * ```ts
+ * // vite.config.ts
+ * import { rastackPlugin } from "rastack/plugin";
+ * export default defineConfig({
+ *   plugins: [rastackPlugin({ resourcesDir: "src/entities" })],
+ * });
+ * ```
+ *
+ * ```tsx
+ * // app — the manifest is a live import, recompiled on every save
+ * import manifest from "virtual:rastack-manifest";
+ * <RAStackProvider mode="local" manifest={manifest}>…</RAStackProvider>
+ * ```
+ *
+ * What it does on your behalf, on every relevant file save:
+ * - recompiles the entity graph (classes, interfaces, `resource()` calls);
+ * - serves the manifest as the `virtual:rastack-manifest` module and
+ *   hot-invalidates it;
+ * - rewrites `.rastack/rastack-env.d.ts` (string-key row types) and
+ *   `schema.rastack.json`/`openapi.json`, so the committed artifacts and the
+ *   registry never go stale;
+ * - on a broken in-progress edit, reports the error and keeps serving the
+ *   last good manifest.
+ *
+ * The plugin object is Vite/Rollup-compatible (Vite-specific hooks are
+ * ignored by plain Rollup). For dev servers with other plugin systems
+ * (Next/webpack, Metro/Expo), `startRastackWatcher` does the same
+ * recompile-on-save against the filesystem — call it once from your config —
+ * and `rastack dev` remains the zero-config path.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import {
+  createSchemaState,
+  isEntitySource,
+  registerModuleCode,
+  RESOLVED_MANIFEST_ID,
+  VIRTUAL_MANIFEST_ID,
+  VIRTUAL_REGISTER_ID,
+  type RastackPluginOptions,
+  type SchemaState,
+} from "./core";
+
+export {
+  createSchemaState,
+  GLOBAL_MANIFEST_KEY,
+  isEntitySource,
+  manifestModuleCode,
+  registerModuleCode,
+  resolveOptions,
+  RESOLVED_MANIFEST_ID,
+  runCompile,
+  VIRTUAL_MANIFEST_ID,
+  VIRTUAL_REGISTER_ID,
+  virtualModuleDts,
+} from "./core";
+export type {
+  RastackPluginOptions,
+  ResolvedPluginOptions,
+  SchemaState,
+} from "./core";
+
+/** One HTML tag descriptor in Vite's `transformIndexHtml` shape. */
+export interface HtmlTagDescriptor {
+  tag: string;
+  attrs?: Record<string, string>;
+  children?: string;
+  injectTo?: "head" | "head-prepend" | "body" | "body-prepend";
+}
+
+/** The minimal bundler-plugin surface we emit (Vite superset of Rollup). */
+export interface RastackBundlerPlugin {
+  name: string;
+  buildStart(): void;
+  resolveId(id: string): string | undefined;
+  load(id: string): string | undefined;
+  watchChange(id: string): void;
+  /**
+   * Vite-only: auto-register the schema. Injects a module script that sets
+   * `globalThis.__RASTACK_MANIFEST__` before the app boots, so the provider
+   * and hooks need no `manifest` wiring at all. Object form with
+   * `order: "pre"` — the tag must be injected *before* Vite scans the HTML
+   * entry, or the build ships the virtual import verbatim.
+   */
+  transformIndexHtml: {
+    order: "pre";
+    handler(html: string, ctx?: { server?: unknown }): HtmlTagDescriptor[];
+  };
+  /** Vite-only: recompile + hot-invalidate the virtual manifest module. */
+  handleHotUpdate(ctx: {
+    file: string;
+    server: {
+      moduleGraph: {
+        getModuleById(id: string): unknown;
+        invalidateModule(mod: any): void;
+      };
+    };
+    modules: unknown[];
+  }): unknown[] | void;
+  /** The live schema state — exposed for tests and advanced callers. */
+  api: SchemaState;
+}
+
+/**
+ * The bundler plugin. Works as-is in Vite and Rollup; the returned object is
+ * plain data + closures, so any bundler with resolve/load/watch hooks can
+ * adapt it.
+ */
+export function rastackPlugin(
+  options: RastackPluginOptions = {},
+): RastackBundlerPlugin {
+  const state = createSchemaState(options);
+
+  return {
+    name: "rastack",
+
+    buildStart() {
+      // Compile eagerly so authoring errors surface at server start, and the
+      // artifacts (env.d.ts, schema.rastack.json) exist before first load.
+      state.manifest();
+    },
+
+    resolveId(id: string) {
+      if (id === VIRTUAL_MANIFEST_ID) return RESOLVED_MANIFEST_ID;
+      if (id === VIRTUAL_REGISTER_ID) return VIRTUAL_REGISTER_ID;
+      return undefined;
+    },
+
+    load(id: string) {
+      if (id === RESOLVED_MANIFEST_ID) return state.code();
+      if (id === VIRTUAL_REGISTER_ID) return registerModuleCode();
+      return undefined;
+    },
+
+    watchChange(id: string) {
+      if (isEntitySource(id, state.options)) state.invalidate();
+    },
+
+    handleHotUpdate(ctx) {
+      if (!isEntitySource(ctx.file, state.options)) return;
+      state.invalidate();
+      const mod = ctx.server.moduleGraph.getModuleById(RESOLVED_MANIFEST_ID);
+      if (mod) {
+        ctx.server.moduleGraph.invalidateModule(mod);
+        return [...ctx.modules, mod];
+      }
+    },
+
+    transformIndexHtml: {
+      order: "pre",
+      handler(_html: string, ctx?: { server?: unknown }) {
+        // Dev serves resolved ids at /@id/<id>; build gets an inline module
+        // script that (because this runs `pre`, before Vite scans the HTML
+        // entry) is bundled, its import resolving back through
+        // resolveId/load above.
+        const attrs: Record<string, string> = { type: "module" };
+        const tag: HtmlTagDescriptor = ctx?.server
+          ? {
+              tag: "script",
+              attrs: { ...attrs, src: `/@id/${VIRTUAL_REGISTER_ID}` },
+            }
+          : {
+              tag: "script",
+              attrs,
+              children: `import ${JSON.stringify(VIRTUAL_REGISTER_ID)};`,
+            };
+        return [{ ...tag, injectTo: "head-prepend" }];
+      },
+    },
+
+    api: state,
+  };
+}
+
+/** Alias so `import { rastack } from "rastack/plugin"` reads naturally. */
+export const rastack = rastackPlugin;
+
+export interface RastackWatcher {
+  /** Stop watching. */
+  close(): void;
+  /** The live schema state (same object the recompiles flow through). */
+  state: SchemaState;
+}
+
+/**
+ * The plugin for everything that isn't Rollup-shaped: watch the resources
+ * directory and rewrite the artifacts (`schema.rastack.json`,
+ * `openapi.json`, `rastack-env.d.ts`) on every save. Call once from any
+ * Node-side config (next.config.js, metro.config.js, a dev script):
+ *
+ * ```js
+ * // next.config.js
+ * const { startRastackWatcher } = require("rastack/plugin");
+ * if (process.env.NODE_ENV === "development") startRastackWatcher();
+ * ```
+ *
+ * The app then imports `.rastack/schema.rastack.json` directly (a plain JSON
+ * import every bundler hot-reloads) instead of the virtual module.
+ */
+export function startRastackWatcher(
+  options: RastackPluginOptions = {},
+): RastackWatcher {
+  const state = createSchemaState(options);
+  state.manifest(); // initial compile (writes the artifacts)
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const watcher = fs.watch(
+    state.options.resourcesDir,
+    { recursive: true },
+    (_event, filename) => {
+      // fs.watch reports paths relative to the watched directory.
+      const file = filename
+        ? path.join(state.options.resourcesDir, String(filename))
+        : undefined;
+      if (!file || !isEntitySource(file, state.options)) {
+        return;
+      }
+      state.invalidate();
+      // Debounce bursts (editors write twice, git checkouts touch many files).
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        state.manifest();
+      }, 100);
+    },
+  );
+
+  return {
+    close: () => {
+      if (timer) clearTimeout(timer);
+      watcher.close();
+    },
+    state,
+  };
+}

package/test/auth.spec.ts

@@ -0,0 +1,207 @@
+/**
+ * Tests for the `rastack/auth` core — the client-side mirror of the access
+ * rules `rastack-api-core` enforces (see `rust/rastack-api-core/tests/access.rs`
+ * for the server side of the same matrix). The semantics here must track the
+ * Rust `check_permission` / `enforced_owner` exactly: `can()` answers "would
+ * the server accept this request?", so the components can limit the paths they
+ * expose instead of surfacing 401s.
+ */
+
+import {
+  anonymousAuth,
+  authFromClaims,
+  bypassesRls,
+  can,
+  canActOnRow,
+  isAdmin,
+  ownsRow,
+  policyFromManifest,
+  policyFromOpenApi,
+  trustedAuth,
+  userAuth,
+  type ResourcePolicy,
+} from "../auth/core";
+
+const rls: ResourcePolicy = {
+  permission: "authenticated",
+  access: { ownerField: "owner", scope: "owner", adminGroups: ["staff"] },
+};
+
+describe("rastack/auth — the permission gate (can)", () => {
+  it("defaults to authenticated — secure by default, like the server", () => {
+    expect(can(anonymousAuth(), {}, "list")).toBe(false);
+    expect(can(anonymousAuth(), undefined, "create")).toBe(false);
+    expect(can(userAuth("u1"), {}, "list")).toBe(true);
+    expect(can(userAuth("u1"), undefined, "delete")).toBe(true);
+  });
+
+  it("public admits everyone, for every action", () => {
+    const policy: ResourcePolicy = { permission: "public" };
+    for (const action of [
+      "list",
+      "retrieve",
+      "create",
+      "update",
+      "delete",
+    ] as const) {
+      expect(can(anonymousAuth(), policy, action)).toBe(true);
+    }
+  });
+
+  it("authenticatedOrReadOnly admits anonymous reads but not writes", () => {
+    const policy: ResourcePolicy = { permission: "authenticatedOrReadOnly" };
+    expect(can(anonymousAuth(), policy, "list")).toBe(true);
+    expect(can(anonymousAuth(), policy, "retrieve")).toBe(true);
+    expect(can(anonymousAuth(), policy, "create")).toBe(false);
+    expect(can(anonymousAuth(), policy, "update")).toBe(false);
+    expect(can(anonymousAuth(), policy, "delete")).toBe(false);
+    expect(can(userAuth("u1"), policy, "delete")).toBe(true);
+  });
+
+  it("row-secured resources need a subject (the server answers 401 without one)", () => {
+    // Authenticated but subject-less — e.g. a machine token without `sub`.
+    const noSub = { authenticated: true, groups: [] };
+    expect(can(noSub, rls, "list")).toBe(false);
+    expect(can(userAuth("u1"), rls, "list")).toBe(true);
+    // A configured admin group bypasses row-level security.
+    expect(can({ ...noSub, groups: ["staff"] }, rls, "list")).toBe(true);
+  });
+
+  it("trusted contexts (dev without auth) pass everything", () => {
+    expect(can(trustedAuth(), rls, "delete")).toBe(true);
+  });
+
+  it("a missing identity gates nothing — the server stays the enforcer", () => {
+    expect(can(undefined, rls, "delete")).toBe(true);
+    expect(can(null, { permission: "authenticated" }, "create")).toBe(true);
+  });
+});
+
+describe("rastack/auth — row-level security helpers", () => {
+  const mine = { id: 1, owner: "u1" };
+  const theirs = { id: 2, owner: "u2" };
+
+  it("owners own their rows; others don't", () => {
+    expect(ownsRow(userAuth("u1"), rls, mine)).toBe(true);
+    expect(ownsRow(userAuth("u1"), rls, theirs)).toBe(false);
+  });
+
+  it("admin groups and trusted contexts bypass the owner filter", () => {
+    expect(bypassesRls(userAuth("u1", ["staff"]), rls)).toBe(true);
+    expect(ownsRow(userAuth("u1", ["staff"]), rls, theirs)).toBe(true);
+    expect(ownsRow(trustedAuth(), rls, theirs)).toBe(true);
+    expect(bypassesRls(userAuth("u1", ["other"]), rls)).toBe(false);
+  });
+
+  it("unsecured resources are owned by everyone", () => {
+    expect(ownsRow(userAuth("u1"), {}, theirs)).toBe(true);
+  });
+
+  it("canActOnRow combines the gate and ownership", () => {
+    expect(canActOnRow(userAuth("u1"), rls, "update", mine)).toBe(true);
+    expect(canActOnRow(userAuth("u1"), rls, "update", theirs)).toBe(false);
+    expect(canActOnRow(anonymousAuth(), rls, "update", mine)).toBe(false);
+  });
+});
+
+describe("rastack/auth — group-owned datasets", () => {
+  // A group dataset: rows belong to a team, physically partitioned per group.
+  const grouped: ResourcePolicy = {
+    permission: "authenticated",
+    access: { groupField: "team", scope: "group", adminGroups: ["staff"] },
+  };
+  const blueRow = { id: 1, team: "blue" };
+
+  it("members read; identities in no group can read (empty) but never write", () => {
+    const dana = userAuth("dana", ["blue"]);
+    const loner = userAuth("lonnie", []);
+    expect(can(dana, grouped, "list")).toBe(true);
+    expect(can(dana, grouped, "create")).toBe(true);
+    // Reads outside any group just come back empty — but a write can never
+    // succeed, so the UI shouldn't offer it.
+    expect(can(loner, grouped, "list")).toBe(true);
+    expect(can(loner, grouped, "create")).toBe(false);
+    expect(can(loner, grouped, "delete")).toBe(false);
+  });
+
+  it("row membership mirrors the server's group guard", () => {
+    expect(ownsRow(userAuth("dana", ["blue"]), grouped, blueRow)).toBe(true);
+    expect(ownsRow(userAuth("erin", ["green"]), grouped, blueRow)).toBe(false);
+    expect(
+      canActOnRow(userAuth("erin", ["green"]), grouped, "update", blueRow),
+    ).toBe(false);
+    // adminGroups members act across groups.
+    expect(ownsRow(userAuth("sam", ["staff"]), grouped, blueRow)).toBe(true);
+  });
+
+  it("owner + group guards both apply when a policy carries both", () => {
+    const both: ResourcePolicy = {
+      access: { ownerField: "owner", groupField: "team" },
+    };
+    const row = { id: 1, owner: "dana", team: "blue" };
+    expect(ownsRow(userAuth("dana", ["blue"]), both, row)).toBe(true);
+    expect(ownsRow(userAuth("dana", ["green"]), both, row)).toBe(false);
+    expect(ownsRow(userAuth("erin", ["blue"]), both, row)).toBe(false);
+  });
+
+  it("isAdmin is the scope-driven admin role", () => {
+    expect(isAdmin(userAuth("sam", ["staff"]), grouped)).toBe(true);
+    expect(isAdmin(userAuth("dana", ["blue"]), grouped)).toBe(false);
+    expect(isAdmin(trustedAuth(), grouped)).toBe(true);
+  });
+});
+
+describe("rastack/auth — building an identity", () => {
+  it("authFromClaims reads sub and cognito:groups from a decoded token", () => {
+    const auth = authFromClaims({
+      sub: "u1",
+      "cognito:groups": ["staff", 42],
+      email: "x@y.z",
+    });
+    expect(auth).toEqual({ authenticated: true, sub: "u1", groups: ["staff"] });
+    expect(authFromClaims({}).authenticated).toBe(false);
+  });
+});
+
+describe("rastack/auth — policy lookup", () => {
+  const manifest = {
+    resources: [
+      { app: "airports", model: "airport", fields: [] },
+      {
+        app: "airports",
+        model: "itinerary",
+        fields: [],
+        permission: "authenticated",
+        access: { ownerField: "owner", scope: "owner", adminGroups: ["staff"] },
+      },
+    ],
+  };
+
+  it("policyFromManifest extracts permission + access", () => {
+    expect(policyFromManifest(manifest, "airports.itinerary")).toEqual(rls);
+    expect(
+      policyFromManifest(manifest, { app: "airports", model: "airport" }),
+    ).toEqual({});
+    expect(policyFromManifest(manifest, "airports.missing")).toBeUndefined();
+    // Accepts the JSON string form the provider may hold.
+    expect(
+      policyFromManifest(JSON.stringify(manifest), "airports.itinerary"),
+    ).toEqual(rls);
+  });
+
+  it("policyFromOpenApi reads the x-rastack-permission / x-rastack-access stamps", () => {
+    const doc = {
+      paths: {
+        "/api/airports/v1/itinerary/": {
+          get: {
+            operationId: "listItinerary",
+            "x-rastack-permission": "authenticated",
+            "x-rastack-access": rls.access,
+          },
+        },
+      },
+    };
+    expect(policyFromOpenApi(doc, "airports.itinerary")).toEqual(rls);
+    expect(policyFromOpenApi(doc, "airports.airport")).toBeUndefined();
+  });
+});