@vantageos/backend-doctor 0.1.14 → 0.2.0

package/dist/target.js

@@ -0,0 +1,173 @@
+// TARGET RESOLUTION — the run judges the same backend whichever path names it.
+//
+// The defect this closes: the engine's loadTree computes every file's `rel`
+// relative to the path the CLI was given, so the SAME repository produced two
+// different trees under the two documented invocations:
+//   - `backend-doctor <repo>/convex` → rels `messages.ts` (no `convex/` segment)
+//   - `backend-doctor <repo>`        → rels `convex/messages.ts`, PLUS every other
+//     `.ts` file in the repository, including archived copies such as
+//     `_archive-v0.2/<shell>/convex/*.ts` that a `(^|/)convex/` predicate then
+//     judged as live backend source.
+// Detectors keyed on the `convex/` prefix skipped every file in the first form and
+// over-counted in the second; R-36 looked for the lockfile beside `convex/`; CR-1
+// looked for `_generated/api.d.ts` beside the repository root. Measured on vCRM
+// d47a6d4: R-16 2 vs 50 violations, R-6 could-not-judge vs 19 violations.
+//
+// The fix is ONE normalisation at the entry, never a per-detector patch:
+//   repoRoot   nearest ancestor-or-self holding package.json or .git (a `convex`
+//              dir itself is never the repo root, even when it holds a package.json)
+//   convexDir  the `convex` segment the argument names, else <repoRoot>/convex
+//   scanRoots  convexDir and <repoRoot>/mcp-server/src (the two source surfaces the
+//              detectors' own predicates name), each loaded by the ENGINE's loader
+//   rel        relative to repoRoot, so every convex file carries `convex/`
+//   tree.root  repoRoot, so repository co-artifacts (lockfile, workflows) are found
+// Both invocations therefore reduce to the same (repoRoot, convexDir, files) triple.
+import { existsSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { runDoctor } from "@vantageos/mcp-doctor";
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function hasRepoMarker(dir) {
+    return existsSync(join(dir, "package.json")) || existsSync(join(dir, ".git"));
+}
+/** The `convex` dir the argument is (or sits inside), found walking UP from it and
+ * stopping at the first repository marker — so a repository that merely lives
+ * under some `/…/convex/…` host path is never mistaken for a convex dir. */
+function namedConvexDir(p) {
+    for (let dir = p;; dir = dirname(dir)) {
+        if (basename(dir) === "convex")
+            return dir;
+        if (hasRepoMarker(dir) || dirname(dir) === dir)
+            return undefined;
+    }
+}
+/** Resolve a CLI argument to the backend it names. Pure over the filesystem. */
+export function resolveTarget(arg) {
+    const input = resolve(arg);
+    const named = namedConvexDir(input);
+    const start = named ? dirname(named) : input;
+    let repoRoot = start;
+    let repoRootBy = "no marker (argument used as-is)";
+    for (let dir = start;; dir = dirname(dir)) {
+        if (existsSync(join(dir, "package.json"))) {
+            repoRoot = dir;
+            repoRootBy = "package.json";
+            break;
+        }
+        if (existsSync(join(dir, ".git"))) {
+            repoRoot = dir;
+            repoRootBy = ".git";
+            break;
+        }
+        if (dirname(dir) === dir)
+            break;
+    }
+    const convexDir = named && isDir(named)
+        ? named
+        : isDir(join(repoRoot, "convex"))
+            ? join(repoRoot, "convex")
+            : undefined;
+    const scanRoots = [];
+    if (convexDir) {
+        scanRoots.push(convexDir);
+        const mcpSrc = join(repoRoot, "mcp-server", "src");
+        if (isDir(mcpSrc))
+            scanRoots.push(mcpSrc);
+    }
+    else {
+        // No convex dir anywhere: judge exactly what was named, never a guess.
+        scanRoots.push(input);
+    }
+    return { input, repoRoot, repoRootBy, convexDir, scanRoots };
+}
+/** Load one directory through the ENGINE's own loader (never a second traversal
+ * with its own skip list): a capture detector receives the tree runDoctor built. */
+function engineTree(root) {
+    let captured;
+    runDoctor(root, [
+        {
+            id: "target-capture",
+            run: (tree) => {
+                captured = tree;
+                return {
+                    id: "target-capture",
+                    anchor: root,
+                    state: "present",
+                    verdict: "captured",
+                };
+            },
+        },
+    ]);
+    if (captured === undefined) {
+        throw new Error(`backend-doctor: the engine loaded no tree for ${root} — refusing to judge a surface that was never read`);
+    }
+    return captured;
+}
+/** The ONE tree every detector judges: the scan roots' files, `rel` relative to
+ * the repository root, `root` = the repository root. */
+export function loadScopedTree(scope) {
+    const files = [];
+    let packageJson = null;
+    for (const root of scope.scanRoots) {
+        const t = engineTree(root);
+        packageJson ??= t.packageJson;
+        for (const f of t.files) {
+            const rel = relative(scope.repoRoot, f.path);
+            files.push({ ...f, rel: rel === "" ? basename(f.path) : rel });
+        }
+    }
+    return { root: scope.repoRoot, files, packageJson };
+}
+/** Files scanned per top-level directory (two segments under the repo root), so a
+ * reader sees WHAT was judged — an empty or surprising surface is visible. */
+export function coverageInventory(tree) {
+    const inv = new Map();
+    for (const f of tree.files) {
+        const parts = f.rel.split("/");
+        const key = parts.length > 2
+            ? `${parts[0]}/${parts[1]}`
+            : parts.length === 2
+                ? parts[0]
+                : ".";
+        inv.set(key, (inv.get(key) ?? 0) + 1);
+    }
+    return new Map([...inv.entries()].sort((a, b) => a[0].localeCompare(b[0])));
+}
+export function describeScope(scope, tree) {
+    const lines = [
+        `TARGET: ${scope.input}`,
+        `  repo root: ${scope.repoRoot} (by ${scope.repoRootBy})`,
+        `  convex dir: ${scope.convexDir ?? "NONE — no convex/ dir under the repo root; judging the argument as given"}`,
+        `COVERAGE INVENTORY (files scanned per dir, rel to repo root; ${tree.files.length} total):`,
+    ];
+    const inv = coverageInventory(tree);
+    if (inv.size === 0)
+        lines.push("  scanned NOTHING — every source rule below abstains on an empty scan");
+    for (const [dir, n] of inv)
+        lines.push(`  scanned ${dir}: ${n}`);
+    return lines.join("\n");
+}
+/** Wrap detectors so each judges the scoped tree instead of the engine's
+ * per-argument tree. runDoctor still owns the loud-fail contract. */
+export function onScopedTree(tree, detectors) {
+    return detectors.map((d) => ({ ...d, run: () => d.run(tree) }));
+}
+/** Absolute convex dir for a scoped tree (tree.root = repo root) or for a tree
+ * rooted AT a convex dir (direct detector tests). `prefix` is what the tree's
+ * rels carry in front of a convex-relative path. */
+export function convexRootOf(tree) {
+    if (existsSync(join(tree.root, "_generated")) ||
+        basename(tree.root) === "convex") {
+        return { dir: tree.root, prefix: "" };
+    }
+    const dir = join(tree.root, "convex");
+    if (isDir(dir))
+        return { dir, prefix: "convex/" };
+    return { dir: tree.root, prefix: "" };
+}

package/fixtures/cr1-classes/_generated/api.d.ts

@@ -0,0 +1,24 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility — a MINIMAL, hand-kept replica of the shape
+ * `npx convex dev` emits, so CR-1's population parser is exercised on the real
+ * artefact shape (the `import type * as` map plus the `fullApi` member list) without
+ * this repository depending on the Convex CLI. See fixtures/cr1-classes/surface.ts.
+ * @module
+ */
+
+import type * as surface from "../surface.js";
+
+declare const fullApi: ApiFromModules<{
+  surface: typeof surface;
+}>;
+
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;

package/fixtures/cr1-classes/surface.ts

@@ -0,0 +1,206 @@
+// CR-1's BIPOLAR PER-CLASS fixture. One member of each of the four classes, plus one
+// `internalQuery` whose exclusion CR-1 must prove from the builder token at its own
+// site. Every member is deliberately minimal: exactly one discriminator distinguishes
+// it from its neighbouring class, so tests/caller-resolution.test.ts can delete that
+// one discriminator and watch the member MIGRATE. Do not "tidy" this file — each line
+// that looks redundant is a pole.
+
+// ─── the tree's own helpers, which CR-1 derives (never a name list) ───────────
+
+/** A GATE: consults the verified principal and REFUSES on its absent path. */
+async function requireCaller(ctx: Ctx): Promise<void> {
+	const identity = await ctx.auth.getUserIdentity();
+	if (!identity) {
+		throw new Error("RBAC_DENIED: no verified principal.");
+	}
+}
+
+/** A RESOLVER: consults the principal and RETURNS a scope; the absent path is a
+ *  typed empty scope, so the handler that calls it must use what it returns. */
+async function resolveScope(ctx: Ctx): Promise<{ orgSlug: string | null }> {
+	const identity = await ctx.auth.getUserIdentity();
+	if (!identity) {
+		return { orgSlug: null };
+	}
+	return { orgSlug: String(identity.organizationSlug) };
+}
+
+// ─── RESOLVES — a gate refuses on the absent-identity path before any read ────
+
+export const resolvesMember = query({
+	args: {},
+	handler: async (ctx) => {
+		await requireCaller(ctx);
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+// ─── FAIL-OPEN — the resolver's result is bound and never read again ──────────
+
+export const failOpenMember = query({
+	args: {},
+	handler: async (ctx) => {
+		// biome-ignore lint/correctness/noUnusedVariables: the UNUSED binding IS the pole —
+		// this fixture member exists to be a resolved principal that is then discarded.
+		// Renaming it `_scope` would delete the discriminator the FAIL-OPEN class is about.
+		const scope = await resolveScope(ctx);
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+// ─── NO-IDENTITY — serves data, consults no principal, no justification ──────
+
+export const noIdentityMember = query({
+	args: {},
+	handler: async (ctx) => {
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+// ─── NO-DATA — touches no data, and says why, in this source ──────────────────
+
+// allow-no-caller-resolution: returns the deployment's build constant only; it
+// reads no table, no storage and no other function, so there is no caller-scoped
+// datum for a principal to scope.
+export const noDataMember = query({
+	args: {},
+	handler: async () => {
+		return { build: "fixture" };
+	},
+});
+
+// ─── RESOLVES through a DECLARE-THEN-ASSIGN gate, the shape a reviewer's ──────
+// ─── probe caught the matcher failing to read ─────────────────────────────────
+//
+// ORIGIN, cited rather than invented: this is the shape of
+// `requireServiceAccount` in vantageos-agency/vantage-peers
+// convex/oauth.ts @ 40c71cb55721d99d3bed17058fdc10281103b158 — the local is
+// DECLARED on its own line precisely so the resolution can sit inside a `try`
+// and re-raise naming its own door, then the authority test follows.
+//
+// The matcher originally required the `=` to follow the declarator on one
+// statement, so every gate written this way read as ABSENT and SEVEN correctly
+// service-account-gated oauth handlers were classed FAIL-OPEN. Measured on that
+// same tree: FAIL-OPEN 11 -> 4 and RESOLVES 139 -> 146 once the shape is read,
+// with the classified total unchanged at 179.
+//
+// This site asserts RESOLVES. It is a fixture rather than a unit assertion
+// because the defect was in the POPULATION-wide read, not in one predicate.
+
+export const resolvesViaDeclareThenAssignGate = query({
+	args: {},
+	handler: async (ctx) => {
+		await requireServiceAccountShim(ctx, "fixture:resolvesViaDeclareThenAssignGate");
+		// It must TOUCH DATA, or CR-1 classes it NO-DATA and the gate question is
+		// moot — which is what happened on the first draft of this fixture, and
+		// is itself the instrument behaving correctly.
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+async function requireServiceAccountShim(
+	ctx: Ctx,
+	registration: string,
+): Promise<void> {
+	let scope: { isMaster: boolean } | undefined;
+	try {
+		scope = await resolveScopeShim(ctx);
+	} catch (err: unknown) {
+		throw new Error(`RBAC_DENIED: "${registration}" unresolved-caller`);
+	}
+	if (!scope?.isMaster) {
+		throw new Error(`RBAC_DENIED: "${registration}" not-the-service-account`);
+	}
+}
+
+async function resolveScopeShim(ctx: Ctx): Promise<{ isMaster: boolean }> {
+	const identity = await ctx.auth.getUserIdentity();
+	return { isMaster: identity !== null };
+}
+
+// ─── FAIL-OPEN in the SAME declare-then-assign shape — the WIDENING pole ──────
+//
+// WHY THIS EXISTS, and it is the pole that decides whether the shape above is a
+// fix or a hole. `resolvesViaDeclareThenAssignGate` proves the matcher READS
+// declare-then-assign. It does NOT prove the matcher still REFUSES when such a
+// binding is never tested. A reviewer's mutant made every declare-then-assign
+// binding count as a gate regardless of any refusal, and it SURVIVED the whole
+// suite — 465/465, and the real-tree FAIL-OPEN count unmoved at 4. So
+//   let s; s = await resolver(ctx); return ctx.db…
+// with no test of `s` would have read as RESOLVES.
+//
+// The widening direction of a security detector is the direction that hides a
+// leak, and it was the untested one. This site is identical to its sibling in
+// SHAPE and differs only in the thing that matters: the resolved value decides
+// NOTHING before the data is served. It must class FAIL-OPEN and appear in
+// violations().
+
+export const failsOpenViaDeclareThenAssignNoTest = query({
+	args: {},
+	handler: async (ctx) => {
+		// Declared on its own line, assigned inside a try — the shape the matcher
+		// now reads — and then the binding is simply never consulted.
+		let scope: { isMaster: boolean } | undefined;
+		try {
+			scope = await resolveScopeShim(ctx);
+		} catch {
+			// swallowed: not a refusal. The caller is resolved and discarded.
+		}
+		void scope;
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+// ─── the pole that actually kills the widening mutant ─────────────────────────
+//
+// WHY THE PREVIOUS POLE WAS NOT ENOUGH, measured rather than guessed. The
+// reviewer's mutant W makes any declare-then-assign binding count as a REFUSAL,
+// which promotes the enclosing function to a GATE. `failsOpenViaDeclareThenAssign
+// NoTest` above is classed FAIL-OPEN on its own body and stays FAIL-OPEN under W,
+// so it does not bite: W's damage lands on whoever TRUSTS a wrongly-promoted
+// gate, not on the promoted function itself.
+//
+// So the pole has to be the site that DELEGATES its authority to such a helper.
+// `pretendGateDeclareThenAssignNoTest` below is in the declare-then-assign shape
+// and never tests what it resolved — it is not a gate. A registration whose only
+// authority is that helper is therefore FAIL-OPEN. Under W the helper is promoted
+// and the registration reads RESOLVES: a leak classified as safe, which is the
+// single outcome a security detector must never produce.
+
+export const failsOpenBehindAPretendGate = query({
+	args: {},
+	handler: async (ctx) => {
+		await pretendGateDeclareThenAssignNoTest(ctx);
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+async function pretendGateDeclareThenAssignNoTest(ctx: Ctx): Promise<void> {
+	// Declared on its own line, assigned inside a try — the shape the matcher now
+	// reads — and then NEVER consulted. Resolving is not refusing.
+	let scope: { isMaster: boolean } | undefined;
+	try {
+		scope = await resolveScopeShim(ctx);
+	} catch {
+		// swallowed on purpose: there is no refusal anywhere in this function.
+	}
+	void scope;
+}
+
+// ─── excluded — and the exclusion is proven by the builder token on THIS line ──
+
+export const internalMember = internalQuery({
+	args: {},
+	handler: async (ctx) => {
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+// ─── minimal ambient shims so this fixture is readable TypeScript on its own ──
+
+interface Ctx {
+	auth: { getUserIdentity: () => Promise<Record<string, unknown> | null> };
+	db: { query: (t: string) => { collect: () => Promise<unknown[]> } };
+}
+declare function query<T>(config: T): T;
+declare function internalQuery<T>(config: T): T;

package/fixtures/cr1-empty/nothing.ts

@@ -0,0 +1 @@
+export const nothing = 1;

package/fixtures/cr1-refusal-on-resolved/_generated/api.d.ts

@@ -0,0 +1,24 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility — a MINIMAL, hand-kept replica of the shape
+ * `npx convex dev` emits (see fixtures/cr1-classes/_generated/api.d.ts). Only
+ * `doors` is listed: `lib/auth.ts` registers no public function, exactly as the
+ * product tree's `lib/auth` exposes none to CR-1's population.
+ * @module
+ */
+
+import type * as doors from "../doors.js";
+
+declare const fullApi: ApiFromModules<{
+  doors: typeof doors;
+}>;
+
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;

package/fixtures/cr1-refusal-on-resolved/doors.ts

@@ -0,0 +1,180 @@
+// CR-1 fixture — public doors gated the way vantage-peers 58ed649 gates the OKF
+// export/import doors (okfBundleNode.ts:244-276, okfBundleDurable.ts:110-132,
+// okfBundleNode.ts:783-793), plus the negative poles that must stay FAIL-OPEN.
+// Each member is a pole for tests/cr1-refusal-on-resolved.test.ts.
+import {
+	requireMasterDirect,
+	requireNamespaceSometimes,
+	requireNonEmpty,
+	requireTenantNamespace,
+	withOrgScope,
+} from "./lib/auth";
+
+// ─── helpers, product-shaped ─────────────────────────────────────────────────
+
+/** ACTION side (okfBundleNode.ts:assertCanExportNamespace): binding through
+ *  ctx.runQuery(internal.…resolveOrgScopeForAction), refusal through a
+ *  TRANSITIVE value refuser. */
+async function assertCanExportNamespace(
+	ctx: ActionCtx,
+	namespace: string,
+	door: string,
+): Promise<void> {
+	if (namespace.includes("..")) {
+		throw new Error(`OKF_NAMESPACE_INVALID: "${namespace}"`);
+	}
+	const scope = await ctx.runQuery(
+		internal.lib.auth.resolveOrgScopeForAction,
+		{},
+	);
+	requireTenantNamespace(scope, namespace, door);
+}
+
+/** okfBundleNode.ts:assertCanImport — reaches the gate one call deeper. */
+async function assertCanImport(
+	ctx: ActionCtx,
+	namespace: string,
+): Promise<void> {
+	await assertCanExportNamespace(ctx, namespace, "doors:importBundle");
+}
+
+/** V8 side (okfBundleDurable.ts:assertCanExportNamespaceV8): binding through
+ *  withOrgScope, refusal through the same TRANSITIVE value refuser. */
+async function assertCanExportNamespaceV8(
+	ctx: MutationCtx,
+	namespace: string,
+	door: string,
+): Promise<void> {
+	const scope = await withOrgScope(ctx, { refuseWithoutThrow: true });
+	requireTenantNamespace(scope, namespace, door);
+}
+
+/** binding through withOrgScope, refusal through a DIRECT (one-level) refuser. */
+async function assertMasterDirect(
+	ctx: MutationCtx,
+	door: string,
+): Promise<void> {
+	const scope = await withOrgScope(ctx);
+	requireMasterDirect(scope, door);
+}
+
+/** NEGATIVE 1 — same resolution, result IGNORED: the refuser is handed the
+ *  namespace, never the resolved scope. */
+async function assertIgnored(
+	ctx: ActionCtx,
+	namespace: string,
+	door: string,
+): Promise<void> {
+	// biome-ignore lint/correctness/noUnusedVariables: the UNUSED binding IS the pole.
+	const scope = await ctx.runQuery(
+		internal.lib.auth.resolveOrgScopeForAction,
+		{},
+	);
+	requireNonEmpty(namespace, door);
+}
+
+/** NEGATIVE 2 — the old okfBundleNode.ts:assertCanValidate shape: the
+ *  absent-identity branch is a bare `return;`, whatever follows it. */
+async function assertCanValidateOld(
+	ctx: ActionCtx,
+	namespace: string,
+	door: string,
+): Promise<void> {
+	const identity = await ctx.auth.getUserIdentity();
+	if (identity === null || identity === undefined) {
+		return;
+	}
+	const scope = await ctx.runQuery(
+		internal.lib.auth.resolveOrgScopeForAction,
+		{},
+	);
+	requireTenantNamespace(scope, namespace, door);
+}
+
+/** NEGATIVE 3 — the refuser proceeds silently on a caller-supplied value. */
+async function assertSometimes(
+	ctx: MutationCtx,
+	namespace: string,
+	door: string,
+): Promise<void> {
+	const scope = await withOrgScope(ctx);
+	requireNamespaceSometimes(scope, namespace, door);
+}
+
+export const readRows = internalQuery({
+	args: { namespace: v.string() },
+	handler: async (ctx, args) => {
+		return await ctx.db
+			.query("rows")
+			.withIndex("by_namespace", (q) => q.eq("namespace", args.namespace))
+			.collect();
+	},
+});
+
+// ─── POSITIVE — RESOLVES ─────────────────────────────────────────────────────
+
+export const exportBundle = action({
+	args: { namespace: v.string() },
+	handler: async (ctx, args) => {
+		await assertCanExportNamespace(ctx, args.namespace, "doors:exportBundle");
+		return await ctx.runQuery(internal.doors.readRows, {
+			namespace: args.namespace,
+		});
+	},
+});
+
+export const importBundle = action({
+	args: { namespace: v.string() },
+	handler: async (ctx, args) => {
+		await assertCanImport(ctx, args.namespace);
+		return await ctx.runQuery(internal.doors.readRows, {
+			namespace: args.namespace,
+		});
+	},
+});
+
+export const startExport = mutation({
+	args: { namespace: v.string() },
+	handler: async (ctx, args) => {
+		await assertCanExportNamespaceV8(ctx, args.namespace, "doors:startExport");
+		return await ctx.db.insert("jobs", { namespace: args.namespace });
+	},
+});
+
+export const directDoor = mutation({
+	args: { namespace: v.string() },
+	handler: async (ctx, args) => {
+		await assertMasterDirect(ctx, "doors:directDoor");
+		return await ctx.db.insert("jobs", { namespace: args.namespace });
+	},
+});
+
+// ─── NEGATIVE — FAIL-OPEN ────────────────────────────────────────────────────
+
+export const ignoredDoor = action({
+	args: { namespace: v.string() },
+	handler: async (ctx, args) => {
+		await assertIgnored(ctx, args.namespace, "doors:ignoredDoor");
+		return await ctx.runQuery(internal.doors.readRows, {
+			namespace: args.namespace,
+		});
+	},
+});
+
+export const validateDoor = action({
+	args: { namespace: v.string() },
+	handler: async (ctx, args) => {
+		await assertCanValidateOld(ctx, args.namespace, "doors:validateDoor");
+		return await ctx.runQuery(internal.doors.readRows, {
+			namespace: args.namespace,
+		});
+	},
+});
+
+export const sometimesDoor = mutation({
+	args: { namespace: v.string() },
+	handler: async (ctx, args) => {
+		await assertSometimes(ctx, args.namespace, "doors:sometimesDoor");
+		return await ctx.db.insert("jobs", { namespace: args.namespace });
+	},
+});