@vantageos/backend-doctor 0.1.14 → 0.3.0

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 });
+	},
+});

package/fixtures/cr1-refusal-on-resolved/lib/auth.ts

@@ -0,0 +1,104 @@
+// CR-1 fixture — the RESOLVER and REFUSER helpers, shaped after vantage-peers
+// 58ed649 `convex/lib/auth.ts` (withOrgScope, requireResolvedCaller,
+// isNamespaceAllowedForScope, requireTenantNamespace, resolveOrgScopeForAction).
+// Each helper below is a pole for tests/cr1-refusal-on-resolved.test.ts. Do not
+// "tidy" it: a line that looks redundant is a discriminator.
+
+/** RESOLVER (not a gate): an absent identity returns an anonymous scope. */
+export async function withOrgScope(ctx: Ctx, opts?: Opts): Promise<Scope> {
+	const identity = await ctx.auth.getUserIdentity();
+	if (identity === null || identity === undefined) {
+		return { isMaster: false, orgSlug: null, anonymous: true, refused: true };
+	}
+	const row = await ctx.db
+		.query("client_org_mapping")
+		.withIndex("by_clerk_slug", (q) => q.eq("clerkSlug", identity.org_slug))
+		.unique();
+	if (row === null || opts?.refuseWithoutThrow) {
+		return { isMaster: false, orgSlug: null, anonymous: false, refused: true };
+	}
+	return {
+		isMaster: false,
+		orgSlug: row.orgSlug,
+		anonymous: false,
+		refused: false,
+	};
+}
+
+/** VALUE REFUSER, direct: refuses an anonymous scope by raising. */
+export function requireResolvedCaller(
+	scope: Pick<Scope, "isMaster" | "orgSlug" | "anonymous" | "refused">,
+	registration: string,
+	opts?: { masterOnly?: boolean },
+): void {
+	if (scope.isMaster) return;
+	if (scope.anonymous) {
+		throw new ConvexError(
+			`RBAC_DENIED: no credential presented to "${registration}"`,
+		);
+	}
+	if (opts?.masterOnly) {
+		throw new ConvexError(
+			`RBAC_DENIED: "${registration}" admits the fleet master only`,
+		);
+	}
+}
+
+/** a PREDICATE on the resolved scope — returns a boolean, refuses nothing. */
+export function isNamespaceAllowedForScope(
+	scope: Pick<Scope, "isMaster" | "orgSlug">,
+	namespace: string,
+): boolean {
+	if (scope.isMaster) return true;
+	if (scope.orgSlug === null) return false;
+	return namespace.startsWith(`team/${scope.orgSlug}`);
+}
+
+/** VALUE REFUSER, TRANSITIVE: no throw of its own — it allows on a test of the
+ *  RESOLVED scope and otherwise hands that scope to requireResolvedCaller. */
+export function requireTenantNamespace(
+	scope: Pick<Scope, "isMaster" | "orgSlug" | "anonymous" | "refused">,
+	namespace: string,
+	door: string,
+): void {
+	if (isNamespaceAllowedForScope(scope, namespace)) return;
+	requireResolvedCaller(scope, door, { masterOnly: true });
+}
+
+/** VALUE REFUSER, direct, one level: throws on a test of the resolved scope. */
+export function requireMasterDirect(scope: Scope, door: string): void {
+	if (!scope.isMaster) {
+		throw new ConvexError(
+			`RBAC_DENIED: "${door}" admits the fleet master only`,
+		);
+	}
+}
+
+/** NOT a refuser of `scope`: it PROCEEDS on a test of a caller-supplied argument
+ *  before any test of the resolved value — every principal, none included, whose
+ *  namespace starts `public/` is waved through. */
+export function requireNamespaceSometimes(
+	scope: Pick<Scope, "isMaster" | "orgSlug" | "anonymous" | "refused">,
+	namespace: string,
+	door: string,
+): void {
+	if (namespace.startsWith("public/")) return;
+	requireResolvedCaller(scope, door, { masterOnly: true });
+}
+
+/** a refuser of its OWN argument (a namespace), never of a principal. */
+export function requireNonEmpty(namespace: string, door: string): void {
+	if (namespace.length === 0) {
+		throw new Error(`OKF_NAMESPACE_INVALID at "${door}"`);
+	}
+}
+
+/** the ONE way an action resolves its caller — reached as
+ *  `internal.lib.auth.resolveOrgScopeForAction`, never by bare name. */
+export const resolveOrgScopeForAction = internalQuery({
+	args: {},
+	handler: async (ctx) => {
+		const scope = await withOrgScope(ctx, { refuseWithoutThrow: true });
+		return scope;
+	},
+});

package/fixtures/r34-vp-auth-30e821b/auth-805-812.ts.txt

@@ -0,0 +1,8 @@
+// verified token here is forwarded verbatim to Convex as `clerkJwt` below,
+// and Convex's own auth.config already requires aud === "convex", so binding
+// the same value here (Critical Rule 14 element 5: aud + iss binding) closes
+// the cross-tenant/cross-resource replay gap without rejecting any token a
+// correctly-configured Clerk "convex" JWT template mints.
+const CLERK_JWT_AUDIENCE = process.env.CLERK_JWT_AUDIENCE ?? "convex";
+
+// Lazy singleton — createRemoteJWKSet caches JWKS in-process (10-min TTL).

package/fixtures/r34-vp-auth-30e821b/auth-878-890.ts.txt

@@ -0,0 +1,13 @@
+ * that DOES require the fallback).
+ */
+async function tryVerifyClerkJwt(token: string): Promise<ClerkJwtResult> {
+	try {
+		const { payload } = await jwtVerify(token, clerkJwks(), {
+			issuer: CLERK_DOMAIN,
+			audience: CLERK_JWT_AUDIENCE,
+		});
+		// Verification succeeded — this IS the caller's own Clerk identity.
+		// `sub`/`exp` absence here would be a session-token shape violation
+		// (not the org concern this function types), so it is still
+		// "not-clerk" (try next layer) rather than "no-org".
+		const sub = payload.sub;