@suluk/cockpit 0.1.13 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/cockpit",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "The pure cockpit core (cycle model · builder model · codegen · deploy planning · validate/audit/preview) shared by the vscode extension and the /superadmin web admin panel. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"

package/src/converge.ts

@@ -8,9 +8,9 @@
  */
 import { buildAda } from "@suluk/core";
 import type { OpenAPIv4Document, Request, SchemaOrRef, SecurityRequirement } from "@suluk/core";
-import { schemaRefName } from "@suluk/builder";
+import { schemaRefName, PREVIEW_ONLY_MARKER } from "@suluk/builder";
 
-export type ConvergeCode = "dangling-ref" | "undeclared-scheme" | "orphan-scope" | "empty-path" | "unreferenced-entity";
+export type ConvergeCode = "dangling-ref" | "undeclared-scheme" | "orphan-scope" | "empty-path" | "unreferenced-entity" | "preview-op-exposed";
 
 export interface ConvergeFinding {
   code: ConvergeCode;
@@ -92,5 +92,21 @@ export function convergeContract(doc: OpenAPIv4Document): ConvergeReport {
   // unreferenced entities — a schema nothing $refs (dead weight; info, not an error)
   for (const name of Object.keys(schemas)) if (!referenced.has(name)) findings.push({ code: "unreferenced-entity", severity: "info", message: `entity "${name}" is referenced by no $ref`, where: name });
 
+  // preview-only operations — a `x-suluk-preview-only` op (the /preview/login backdoor) must NEVER silently sit
+  // in a contract that gets deployed to prod. WARN (not error) so its presence is always surfaced: it is only
+  // safe behind the deploy-time SULUK_PREVIEW gate; confirm this projection is a preview, not production. Walk
+  // BOTH path operations AND webhooks — a marker hidden on a webhook is exactly the same backdoor surface.
+  const previewMarked = (req: unknown): boolean => (req as Record<string, unknown> | null | undefined)?.[PREVIEW_ONLY_MARKER] === true;
+  for (const o of buildAda(doc).operations) {
+    if (previewMarked(o.request as unknown)) {
+      findings.push({ code: "preview-op-exposed", severity: "warn", message: `operation "${o.name}" is preview-only (a role-login backdoor) — it must reach prod ONLY behind the SULUK_PREVIEW gate; confirm this is a preview deployment, not production`, where: o.name });
+    }
+  }
+  for (const [name, req] of Object.entries((doc as { webhooks?: Record<string, Request> }).webhooks ?? {})) {
+    if (previewMarked(req as unknown)) {
+      findings.push({ code: "preview-op-exposed", severity: "warn", message: `webhook "${name}" is preview-only (a role-login backdoor) — it must reach prod ONLY behind the SULUK_PREVIEW gate; confirm this is a preview deployment, not production`, where: name });
+    }
+  }
+
   return { findings, clean: !findings.some((f) => f.severity === "error") };
 }

package/src/crosscut.ts

@@ -94,3 +94,64 @@ export function crossCut(doc: OpenAPIv4Document, viewers: Viewer[]): CrossCut {
   }
   return { operations: ops.map((o) => ({ name: o.name, detail: o.detail })), viewers: views, gated };
 }
+
+/** A principal you can preview the running app AS — derived from the contract, never hardcoded. */
+export interface PreviewRole {
+  label: string;
+  /** the role token passed to the preview deploy's /preview/login?role=… (or "anonymous"). */
+  role: string;
+  /** the scopes this role implies in the cross-cut (here, just the role itself; the runtime maps role→scopes). */
+  scopes: string[];
+  authenticated: boolean;
+}
+
+/**
+ * The previewable principals for live role-preview (the LAST roadmap slice): anonymous, then ONE per role the
+ * contract's `User.role` enum declares (the auth module ships ["user","admin","superadmin"]). Pure; degrades
+ * HONESTLY to anonymous-only when there is no User.role enum — never a hardcoded role list. The extension turns
+ * each into a deep-link to the preview deploy's own login; the cockpit never mints or holds a session.
+ */
+// the safe identifier charset a previewable role name must match — it flows into a URL, into seed.sql, AND into
+// the deployed gate's allow-list, so all three agree on exactly this set. Anything else is not previewable.
+const SAFE_ROLE = /^[A-Za-z0-9_-]{1,40}$/;
+
+export function previewRoles(doc: OpenAPIv4Document): PreviewRole[] {
+  const anonymous: PreviewRole = { label: "anonymous", role: "anonymous", scopes: [], authenticated: false };
+  const user = (doc.components?.schemas as Record<string, unknown> | undefined)?.["User"] as
+    | { properties?: { role?: { enum?: unknown } } }
+    | undefined;
+  const raw = user?.properties?.role?.enum;
+  const seen = new Set<string>();
+  const roles = (Array.isArray(raw) ? raw : [])
+    .filter((r): r is string => typeof r === "string" && r.length > 0)
+    // exclude the RESERVED "anonymous" (it is never a mintable session — login-less by definition), apply the safe
+    // charset (URL + SQL + gate safety), and DEDUP — so the previewable set == the seeded set == the gate allow-list.
+    .filter((r) => r !== "anonymous" && SAFE_ROLE.test(r))
+    .filter((r) => (seen.has(r) ? false : (seen.add(r), true)));
+  return [anonymous, ...roles.map((r) => ({ label: r, role: r, scopes: [r], authenticated: true }))];
+}
+
+/**
+ * The roles a preview may be minted AS — the authenticated principals, EXCLUDING the login-less `anonymous`. This
+ * is the ONE source for the deployed gate's allow-list AND for which demo users seed.sql seeds; keeping them equal
+ * means a role can be previewed iff it is seeded iff the gate allows it (no allow-but-unseedable divergence).
+ */
+export function previewAllowedRoles(doc: OpenAPIv4Document): string[] {
+  return previewRoles(doc).filter((r) => r.authenticated).map((r) => r.role);
+}
+
+/**
+ * Resolve the browser deep-link for previewing AS a role — the security-critical guard, made PURE so it is
+ * unit-testable (the extension package has no test harness). Hard-REFUSES any non-preview env BEFORE producing
+ * a URL (INV-08: role-preview can never target prod/local). anonymous ⇒ just the app; a role ⇒ the preview
+ * deploy's own gated /preview/login. The extension calls this, then openExternal — it never builds the URL itself.
+ */
+export function previewLaunchUrl(
+  env: { baseUrl: string; isPreview: boolean },
+  role: string,
+): { refused: true; reason: string } | { refused: false; url: string } {
+  if (!env.isPreview) return { refused: true, reason: "not a preview deployment — role-preview is refused on prod/local" };
+  const base = env.baseUrl.replace(/\/+$/, "");
+  const url = role === "anonymous" ? base : `${base}/preview/login?role=${encodeURIComponent(role)}`;
+  return { refused: false, url };
+}

package/src/deploy.ts

@@ -7,6 +7,7 @@
 import type { OpenAPIv4Document } from "@suluk/core";
 import { cloudflare, type DeployPlan } from "@suluk/deploy";
 import { entitiesFromDoc } from "./builder";
+import { previewAllowedRoles } from "./crosscut";
 
 /** Build the Cloudflare deploy plan from a v4 document (its schemas → entities). */
 export function deployPlan(doc: OpenAPIv4Document): DeployPlan {
@@ -18,6 +19,22 @@ export function deployPlan(doc: OpenAPIv4Document): DeployPlan {
   });
 }
 
+/**
+ * Build the PREVIEW deploy plan (charter-bounded role-preview): a `${slug}-preview` Worker with the two
+ * fail-closed locks + a seed.sql for the contract's roles. Terminal-gated identically to prod — Suluk holds no
+ * infra token; the USER runs wrangler. The seeded roles come from the contract (previewRoles), never hardcoded.
+ */
+export function previewDeployPlan(doc: OpenAPIv4Document): DeployPlan {
+  return cloudflare.generate({
+    name: doc.info?.title ?? "suluk-app",
+    entities: entitiesFromDoc(doc),
+    appModule: "./src/app",
+    assetsDir: "./dist/client",
+    preview: true,
+    previewRoles: previewAllowedRoles(doc), // the seedable, non-anonymous set — equals the gate's allow-list
+  });
+}
+
 /** Render the deploy plan as a DEPLOY.md the user can follow step by step. */
 export function deployMarkdown(plan: DeployPlan): string {
   const steps = plan.steps.map((s, i) => `${i + 1}. \`${s.cmd}\`\n   - ${s.note}`).join("\n");
@@ -42,3 +59,16 @@ ${notes}
 > consequential. The deployment target is swappable: this is the \`cloudflare\` provider.
 `;
 }
+
+/** Render a PREVIEW deploy plan as a PREVIEW-DEPLOY.md — same steps, but headed with the role-preview safety. */
+export function previewDeployMarkdown(plan: DeployPlan): string {
+  const body = deployMarkdown(plan).replace(
+    "# Deploy to Cloudflare — CANDIDATE (generated by Suluk)",
+    "# Deploy a PREVIEW (role-preview) — CANDIDATE (generated by Suluk)\n\n" +
+      "> This is an EPHEMERAL preview deployment. It mounts a `/preview/login?role=…` backdoor that logs you in\n" +
+      "> as a seeded demo user — gated, fail-closed, behind TWO independent locks (the `SULUK_PREVIEW` var AND the\n" +
+      "> `PREVIEW_DB` binding). A production deploy sets neither, so the backdoor is inert there. **Tear the preview\n" +
+      "> down when finished** (`wrangler delete`) — a standing preview is a live credentialed surface.",
+  );
+  return body;
+}

package/src/index.ts

@@ -8,12 +8,12 @@ export { validateSource, auditSource, previewHtml, looksLikeV4, type Diagnostic
 export { buildCycle, docChecks, cycleSummary, type CycleModel, type CycleLayer, type CycleItem, type LayerStatus, type Principal, type DocCheck } from "./cycle";
 export { buildBuilderModel, builderTree, entitiesFromDoc, generateAppFiles, generateRegistryJson, type BuilderModel, type BuilderNode, type GeneratedFile } from "./builder";
 export { entityNames, generateForm, generateTable, generateStoresModule, exportV4Json } from "./codegen";
-export { deployPlan, deployMarkdown } from "./deploy";
+export { deployPlan, deployMarkdown, previewDeployPlan, previewDeployMarkdown } from "./deploy";
 export type { DeployPlan, DeployStep, DeployProvider } from "@suluk/deploy";
 // drift (OBSERVE): compare a LOCAL contract against a DEPLOYED one — the "what's drifted in prod" view (C020).
 export { diffContracts, canonical, type ContractDiff, type ChangedOp, type OpRef, type ProviderDelta, type ProviderChange } from "./drift";
 // cross-cut (M1): one contract refracted through every viewer — the scope-gated surface, the moat.
-export { crossCut, documentScopes, defaultViewers, type Viewer, type ViewerView, type GatedOp, type CrossCut } from "./crosscut";
+export { crossCut, documentScopes, defaultViewers, previewRoles, previewAllowedRoles, previewLaunchUrl, type Viewer, type ViewerView, type GatedOp, type CrossCut, type PreviewRole } from "./crosscut";
 // converge: a coherence audit over a whole contract — the cross-cutting contradictions a clean merge leaves behind.
 export { convergeContract, type ConvergeReport, type ConvergeFinding, type ConvergeCode } from "./converge";
 // diagrams: D2 source for views of the contract (ERD / the declarative cycle / the operation surface) — another projection.

package/src/lifecycle.ts

@@ -53,6 +53,18 @@ export function contractGates(doc: OpenAPIv4Document, baseline: Baseline): Gate[
     action: errs ? "suluk.convergeContract" : undefined,
   });
 
+  // 2b. no preview backdoor — a contract carrying an x-suluk-preview-only op (a role-login backdoor) must be
+  // deployed ONLY as a preview, never prod. WARN-status so it counts against ready (shipSummary blocks on warn):
+  // a clean contract reads ready; one with the backdoor reads NOT ready until the user confirms it is a preview.
+  // (Fixes the supply-chain hole where a smuggled preview op was hard-filtered out of the error-only coherent gate.)
+  const previewOps = conv.findings.filter((f) => f.code === "preview-op-exposed");
+  gates.push({
+    id: "noBackdoor", title: "No preview backdoor in prod",
+    status: previewOps.length ? "warn" : "ok",
+    detail: previewOps.length ? `${previewOps.length} preview-only op${previewOps.length === 1 ? "" : "s"} (${previewOps.map((f) => f.where).filter(Boolean).join(", ")}) — deploy ONLY as a preview, never to production` : "no preview-only operations",
+    action: previewOps.length ? "suluk.convergeContract" : undefined,
+  });
+
   // 3. pixel-confident components
   const cr = componentReport(doc, baseline);
   const pending = cr.confidence.missing.length + cr.confidence.drifted.length;

package/test/preview.test.ts

@@ -0,0 +1,135 @@
+import { test, expect, describe } from "bun:test";
+import type { OpenAPIv4Document } from "@suluk/core";
+import { installModule, PREVIEW } from "@suluk/builder";
+import { previewRoles, previewAllowedRoles, previewLaunchUrl } from "../src/crosscut";
+import { convergeContract } from "../src/converge";
+import { contractGates, shipSummary } from "../src/lifecycle";
+import { previewDeployPlan, deployPlan } from "../src/deploy";
+
+const docWithRoles = (): OpenAPIv4Document => ({
+  openapi: "4.0.0-candidate",
+  info: { title: "Shop", version: "1.0.0" },
+  paths: { user: { requests: { listUser: { method: "get", responses: { ok: { status: 200, contentType: "application/json", contentSchema: { $ref: "#/components/schemas/User" } } } } } } },
+  components: { schemas: { User: { type: "object", properties: { id: { type: "integer" }, role: { type: "string", enum: ["user", "admin", "superadmin"] } } } } },
+});
+
+describe("previewRoles — contract-sourced principals (never hardcoded)", () => {
+  test("derives anonymous + one per User.role enum value", () => {
+    const roles = previewRoles(docWithRoles());
+    expect(roles.map((r) => r.role)).toEqual(["anonymous", "user", "admin", "superadmin"]);
+    expect(roles[0]).toMatchObject({ role: "anonymous", authenticated: false });
+    expect(roles[2]).toMatchObject({ role: "admin", authenticated: true, scopes: ["admin"] });
+  });
+  test("degrades HONESTLY to anonymous-only when there is no User.role enum", () => {
+    const noRole: OpenAPIv4Document = { openapi: "4.0.0-candidate", info: { title: "X", version: "1.0.0" }, paths: {}, components: { schemas: {} } };
+    expect(previewRoles(noRole).map((r) => r.role)).toEqual(["anonymous"]);
+    // and when there's no User at all it does not throw
+    const bare: OpenAPIv4Document = { openapi: "4.0.0-candidate", info: { title: "X", version: "1.0.0" }, paths: {} };
+    expect(previewRoles(bare).map((r) => r.role)).toEqual(["anonymous"]);
+  });
+  test("a reserved/unsafe/duplicate enum is reconciled — anonymous appears exactly once, unsafe roles dropped", () => {
+    const messy: OpenAPIv4Document = {
+      openapi: "4.0.0-candidate", info: { title: "X", version: "1.0.0" }, paths: {},
+      components: { schemas: { User: { type: "object", properties: { role: { type: "string", enum: ["admin", "anonymous", "admin", "ev:il", "x".repeat(50), 42 as unknown as string] } } } } },
+    };
+    expect(previewRoles(messy).map((r) => r.role)).toEqual(["anonymous", "admin"]); // dedup + reserved + unsafe/long/non-string all dropped
+    expect(previewRoles(messy).filter((r) => r.role === "anonymous")).toHaveLength(1);
+  });
+  test("previewAllowedRoles is the seedable set — authenticated only, NEVER anonymous (the gate's allow-list)", () => {
+    expect(previewAllowedRoles(docWithRoles())).toEqual(["user", "admin", "superadmin"]);
+    expect(previewAllowedRoles(docWithRoles())).not.toContain("anonymous");
+  });
+});
+
+describe("previewLaunchUrl — the preview-only guard + deep-link (INV-08, pure & testable)", () => {
+  test("REFUSES a non-preview env before producing any URL", () => {
+    const r = previewLaunchUrl({ baseUrl: "https://prod.example.com", isPreview: false }, "admin");
+    expect(r.refused).toBe(true);
+    if (r.refused) expect(r.reason).toContain("refused");
+  });
+  test("a preview env + a role ⇒ the deploy's own gated /preview/login, role URL-encoded", () => {
+    const r = previewLaunchUrl({ baseUrl: "https://app-preview.example.com/", isPreview: true }, "super admin");
+    expect(r.refused).toBe(false);
+    if (!r.refused) expect(r.url).toBe("https://app-preview.example.com/preview/login?role=super%20admin");
+  });
+  test("anonymous ⇒ just the app, no login route, no query", () => {
+    const r = previewLaunchUrl({ baseUrl: "https://app-preview.example.com", isPreview: true }, "anonymous");
+    expect(r.refused).toBe(false);
+    if (!r.refused) expect(r.url).toBe("https://app-preview.example.com");
+  });
+});
+
+describe("converge — surfaces the preview-only backdoor (it must never sit silently in a projection)", () => {
+  test("a contract carrying the preview op gets a preview-op-exposed WARN", () => {
+    const installed = installModule(docWithRoles(), PREVIEW);
+    expect(installed.installed).toBe(true);
+    const report = convergeContract(installed.doc);
+    const f = report.findings.find((x) => x.code === "preview-op-exposed");
+    expect(f).toBeDefined();
+    expect(f!.severity).toBe("warn");
+    expect(f!.where).toBe("previewLogin");
+    expect(report.clean).toBe(true); // a WARN is not an error — it does not fail coherence, only flags
+  });
+  test("a contract WITHOUT the preview op has no such finding", () => {
+    expect(convergeContract(docWithRoles()).findings.some((x) => x.code === "preview-op-exposed")).toBe(false);
+  });
+  test("a marker hidden on a WEBHOOK is ALSO surfaced (no false negative)", () => {
+    const wh: OpenAPIv4Document = {
+      openapi: "4.0.0-candidate", info: { title: "X", version: "1.0.0" }, paths: {},
+      webhooks: { sneaky: { method: "post", responses: { ok: { status: 200, description: "x" } }, "x-suluk-preview-only": true } },
+    } as unknown as OpenAPIv4Document;
+    const f = convergeContract(wh).findings.find((x) => x.code === "preview-op-exposed");
+    expect(f).toBeDefined();
+    expect(f!.where).toBe("sneaky");
+  });
+});
+
+describe("ship gate — a contract carrying the backdoor is NOT 'ready to ship' (supply-chain fix)", () => {
+  test("contractGates adds a 'noBackdoor' warn that blocks readiness when a preview op is present", () => {
+    const installed = installModule(docWithRoles(), PREVIEW).doc;
+    const gates = contractGates(installed, {});
+    const g = gates.find((x) => x.id === "noBackdoor")!;
+    expect(g.status).toBe("warn");
+    expect(g.detail).toContain("previewLogin");
+    expect(shipSummary(gates).ready).toBe(false); // the smuggled-backdoor contract can no longer read 'ready'
+  });
+  test("a clean contract has noBackdoor 'ok'", () => {
+    const gates = contractGates(docWithRoles(), {});
+    expect(gates.find((x) => x.id === "noBackdoor")!.status).toBe("ok");
+  });
+});
+
+describe("previewDeployPlan — the two locks + the seed, terminal-gated", () => {
+  const plan = previewDeployPlan(docWithRoles());
+  const wrangler = plan.files.find((f) => f.path === "wrangler.jsonc")!.content;
+  test("names a -preview Worker with BOTH locks: the SULUK_PREVIEW var and a PREVIEW_DB binding", () => {
+    expect(wrangler).toContain("-preview");
+    expect(wrangler).toContain('"SULUK_PREVIEW": "1"');
+    expect(wrangler).toContain('"binding": "PREVIEW_DB"');
+  });
+  test("seeds one throwaway demo user per non-anonymous role", () => {
+    const seed = plan.files.find((f) => f.path === "seed.sql")!.content;
+    expect(seed).toContain("preview-admin");
+    expect(seed).toContain("preview-superadmin");
+    expect(seed).not.toContain("preview-anonymous"); // anonymous is never seeded
+  });
+  test("includes a teardown step (a standing preview is a live credentialed surface)", () => {
+    expect(plan.steps.some((s) => s.cmd.includes("wrangler delete"))).toBe(true);
+  });
+  test("a hostile role enum value never reaches seed.sql (filtered at previewAllowedRoles — no SQL injection)", () => {
+    const evil: OpenAPIv4Document = {
+      openapi: "4.0.0-candidate", info: { title: "Evil", version: "1.0.0" }, paths: {},
+      components: { schemas: { User: { type: "object", properties: { role: { type: "string", enum: ["admin", "x'); DROP TABLE user;--"] } } } } },
+    };
+    const seed = previewDeployPlan(evil).files.find((f) => f.path === "seed.sql")!.content;
+    expect(seed).toContain("preview-admin");          // the safe role is seeded
+    expect(seed).not.toContain("DROP TABLE");          // the hostile role is filtered out upstream, never emitted
+  });
+  test("the PROD plan sets NO preview flag — the backdoor is inert there", () => {
+    const prod = deployPlan(docWithRoles());
+    const prodWrangler = prod.files.find((f) => f.path === "wrangler.jsonc")!.content;
+    expect(prodWrangler).not.toContain("SULUK_PREVIEW");
+    expect(prodWrangler).not.toContain("PREVIEW_DB");
+    expect(prod.files.some((f) => f.path === "seed.sql")).toBe(false);
+  });
+});