@suluk/cockpit 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/cockpit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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.",
   "type": "module",
   "main": "src/index.ts",

package/src/crosscut.ts

@@ -0,0 +1,96 @@
+/**
+ * The cross-cut (M1) — the moat. The cockpit already projects all 9 layers for ONE viewer (buildCycle's
+ * principal filter). This compares ACROSS viewers: one contract, refracted through every principal, so you can
+ * see exactly which operations are gated and who can reach them. No other tool can do this, because none owns
+ * the derivation. Pure (no host) → unit-tested; the extension renders the matrix.
+ */
+import { buildAda } from "@suluk/core";
+import type { OpenAPIv4Document, Request, SecurityRequirement } from "@suluk/core";
+
+/** A viewer to project for. `scopes: undefined` ⇒ the full/operator view; `[]` ⇒ no scopes.
+ *  `authenticated` distinguishes a logged-in viewer from a truly anonymous one — an auth-only operation
+ *  (`security: [{ bearer: [] }]`, a requirement with zero scopes) is reachable by any AUTHENTICATED viewer but
+ *  NOT by anonymous. (This is more precise than the cockpit's single-principal "View as", which keys on scopes
+ *  alone; the cross-cut is the purpose-built security view.) */
+export interface Viewer {
+  label: string;
+  scopes: string[] | undefined;
+  /** does this viewer hold a credential? defaults to "holds at least one scope". */
+  authenticated?: boolean;
+}
+export interface ViewerView {
+  label: string;
+  scopes: string[] | null;
+  visible: string[];
+  hidden: string[];
+}
+export interface GatedOp {
+  operation: string;
+  detail: string;
+  /** the scope requirements (OR of AND-groups); empty ⇒ public */
+  requiredScopes: string[][];
+  /** the labels of the viewers who CAN see it */
+  visibleTo: string[];
+}
+export interface CrossCut {
+  operations: { name: string; detail: string }[];
+  viewers: ViewerView[];
+  /** operations not visible to every viewer — the scope-gated surface */
+  gated: GatedOp[];
+}
+
+function requiredScopes(req: Request): string[][] {
+  const reqs = (req.security as SecurityRequirement[] | undefined) ?? [];
+  return reqs.map((r) => Object.values(r).flat());
+}
+function visibleTo(req: Request, viewer: Viewer): boolean {
+  if (viewer.scopes === undefined) return true; // full operator view sees all
+  const reqs = requiredScopes(req);
+  if (reqs.length === 0) return true; // genuinely public op
+  const held = new Set(viewer.scopes);
+  const authed = viewer.authenticated ?? viewer.scopes.length > 0; // holding a scope implies a credential
+  // a requirement of [] (auth-only, no scope) is satisfied iff authenticated; a scoped requirement needs its scopes
+  return reqs.some((needed) => (needed.length === 0 ? authed : needed.every((s) => held.has(s))));
+}
+
+/** Every scope referenced by any operation's security requirements (sorted, deduped). */
+export function documentScopes(doc: OpenAPIv4Document): string[] {
+  return [...new Set(buildAda(doc).operations.flatMap((o) => requiredScopes(o.request).flat()))].sort();
+}
+
+/**
+ * Sensible default viewers for a document: anonymous, one per declared scope, and the full operator view —
+ * so a single command shows the whole gated surface without the user hand-entering scope sets.
+ */
+export function defaultViewers(doc: OpenAPIv4Document): Viewer[] {
+  const ops = buildAda(doc).operations;
+  const scopes = [...new Set(ops.flatMap((o) => requiredScopes(o.request).flat()))].sort();
+  // only show a distinct "authenticated" viewer when some operation requires auth WITHOUT a scope (else its
+  // column would duplicate "anonymous" — a logged-in user with no role sees the same public + scoped surface).
+  const hasAuthOnly = ops.some((o) => requiredScopes(o.request).some((r) => r.length === 0));
+  return [
+    { label: "anonymous", scopes: [], authenticated: false },
+    ...(hasAuthOnly ? [{ label: "authenticated", scopes: [] as string[], authenticated: true }] : []),
+    ...scopes.map((s) => ({ label: s, scopes: [s], authenticated: true })),
+    { label: "full", scopes: undefined },
+  ];
+}
+
+/** Project the contract through every viewer and surface the gated operations. */
+export function crossCut(doc: OpenAPIv4Document, viewers: Viewer[]): CrossCut {
+  const ops = buildAda(doc).operations.map((o) => ({ name: o.name, detail: `${o.request.method.toUpperCase()} ${o.pathTemplate}`, req: o.request }));
+  const views: ViewerView[] = viewers.map((v) => {
+    const visible: string[] = [];
+    const hidden: string[] = [];
+    for (const o of ops) (visibleTo(o.req, v) ? visible : hidden).push(o.name);
+    return { label: v.label, scopes: v.scopes ?? null, visible, hidden };
+  });
+  const gated: GatedOp[] = [];
+  for (const o of ops) {
+    const seers = views.filter((v) => v.visible.includes(o.name)).map((v) => v.label);
+    if (seers.length !== views.length) {
+      gated.push({ operation: o.name, detail: o.detail, requiredScopes: requiredScopes(o.req), visibleTo: seers });
+    }
+  }
+  return { operations: ops.map((o) => ({ name: o.name, detail: o.detail })), viewers: views, gated };
+}

package/src/index.ts

@@ -12,7 +12,13 @@ export { deployPlan, deployMarkdown } 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 } 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";
 // cost formatting, re-exported so the extension shell can render a live /cost ledger without a direct @suluk/cost dep.
 export { formatMicroUsd, summarize, type CostSummary } from "@suluk/cost";
 // modules (C021): install a contract fragment into the hub doc — the cockpit then re-projects it for free.
-export { installModule, namespaceModule, ECOMMERCE, type SulukModule, type InstallResult } from "@suluk/builder";
+export {
+  installModule, namespaceModule, previewInstall, gradeModule,
+  ECOMMERCE, CRM, BILLING, FIRST_PARTY_REGISTRY,
+  type SulukModule, type InstallResult, type ModuleEntry, type ModuleRegistry, type ModuleGrade, type InstallPreview,
+} from "@suluk/builder";

package/test/crosscut.test.ts

@@ -0,0 +1,81 @@
+import { test, expect, describe } from "bun:test";
+import { parseDocument } from "@suluk/core";
+import { crossCut, documentScopes, defaultViewers } from "../src/crosscut";
+
+// A petstore-ish contract: listPets/getPet are public; createPet/deletePet need write:pets; a read:secret op.
+const DOC = parseDocument(`openapi: 4.0.0-candidate
+info: { title: Pets, version: 1.0.0 }
+paths:
+  "pet":
+    requests:
+      listPets: { method: get, responses: { ok: { status: 200 } } }
+      createPet: { method: post, security: [ { petstore_auth: [ "write:pets" ] } ], responses: { created: { status: 201 } } }
+  "pet/{id}":
+    requests:
+      getPet: { method: get, responses: { ok: { status: 200 } } }
+      deletePet: { method: delete, security: [ { petstore_auth: [ "write:pets" ] } ], responses: { deleted: { status: 204 } } }
+      auditPet: { method: get, security: [ { petstore_auth: [ "read:secret" ] } ], responses: { ok: { status: 200 } } }
+components:
+  securitySchemes:
+    petstore_auth: { type: oauth2, flows: { implicit: { authorizationUrl: "https://x/o", scopes: { "write:pets": "w", "read:secret": "r" } } } }
+`);
+
+describe("documentScopes / defaultViewers", () => {
+  test("collects every scope referenced by an operation", () => {
+    expect(documentScopes(DOC)).toEqual(["read:secret", "write:pets"]);
+  });
+  test("default viewers = anonymous + one per scope + full", () => {
+    expect(defaultViewers(DOC).map((v) => v.label)).toEqual(["anonymous", "read:secret", "write:pets", "full"]);
+  });
+});
+
+describe("crossCut — one contract through every viewer", () => {
+  const cc = crossCut(DOC, defaultViewers(DOC));
+  const view = (label: string) => cc.viewers.find((v) => v.label === label)!;
+
+  test("anonymous sees only the public operations", () => {
+    expect(view("anonymous").visible.sort()).toEqual(["getPet", "listPets"]);
+    expect(view("anonymous").hidden.sort()).toEqual(["auditPet", "createPet", "deletePet"]);
+  });
+  test("a write:pets viewer gains create/delete but NOT the read:secret op", () => {
+    expect(view("write:pets").visible.sort()).toEqual(["createPet", "deletePet", "getPet", "listPets"]);
+    expect(view("write:pets").visible).not.toContain("auditPet");
+  });
+  test("the full operator view sees everything", () => {
+    expect(view("full").hidden).toHaveLength(0);
+    expect(view("full").visible).toHaveLength(5);
+  });
+  test("the gated surface lists exactly the scope-gated operations + who can reach them", () => {
+    const gatedOps = cc.gated.map((g) => g.operation).sort();
+    expect(gatedOps).toEqual(["auditPet", "createPet", "deletePet"]);
+    const createPet = cc.gated.find((g) => g.operation === "createPet")!;
+    expect(createPet.visibleTo).toEqual(["write:pets", "full"]); // anonymous + read:secret cannot
+    expect(createPet.requiredScopes).toEqual([["write:pets"]]);
+  });
+  test("an auth-only operation (security with no scopes) is hidden from anonymous, visible to authenticated", () => {
+    const authed = parseDocument(`openapi: 4.0.0-candidate
+info: { title: A, version: 1.0.0 }
+paths:
+  "me":
+    requests:
+      getMe: { method: get, security: [ { bearerAuth: [] } ], responses: { ok: { status: 200 } } }
+      ping:  { method: get, responses: { ok: { status: 200 } } }
+components: { securitySchemes: { bearerAuth: { type: http, scheme: bearer } } }
+`);
+    const viewers = defaultViewers(authed);
+    expect(viewers.map((v) => v.label)).toContain("authenticated"); // surfaced because of the auth-only op
+    const cc = crossCut(authed, viewers);
+    const v = (l: string) => cc.viewers.find((x) => x.label === l)!;
+    expect(v("anonymous").visible).toEqual(["ping"]); // NOT getMe
+    expect(v("authenticated").visible.sort()).toEqual(["getMe", "ping"]);
+    expect(cc.gated.map((g) => g.operation)).toEqual(["getMe"]);
+    expect(cc.gated[0].visibleTo).toEqual(["authenticated", "full"]);
+  });
+  test("a fully-public contract has an empty gated surface", () => {
+    const open = parseDocument(`openapi: 4.0.0-candidate
+info: { title: Open, version: 1.0.0 }
+paths: { "a": { requests: { listA: { method: get, responses: { ok: { status: 200 } } } } } }
+`);
+    expect(crossCut(open, defaultViewers(open)).gated).toHaveLength(0);
+  });
+});