@checkstack/backend 0.8.2 → 0.9.0

package/src/schema.ts

@@ -7,6 +7,10 @@ import {
   timestamp,
   jsonb,
   primaryKey,
+  uuid,
+  integer,
+  index,
+  uniqueIndex,
 } from "drizzle-orm/pg-core";
 
 // --- Plugin System Schema ---
@@ -18,6 +22,18 @@ export const plugins = pgTable("plugins", {
   config: json("config").default({}),
   enabled: boolean("enabled").default(true).notNull(),
   type: text("type").default("backend").notNull(),
+  // ── Runtime plugin system additions ────────────────────────────────────────
+  /** Installed version (matches package.json `version`). Empty string for
+   *  legacy rows that predate the runtime install system. */
+  version: text("version").default("").notNull(),
+  /** Full validated `InstallPackageMetadata` snapshot taken at install time. */
+  metadata: jsonb("metadata").default({}).notNull(),
+  /** The `PluginSource` used to install this plugin (NULL for monorepo-local). */
+  source: jsonb("source"),
+  /** Groups sibling rows installed together as one bundle. */
+  bundleId: uuid("bundle_id"),
+  /** True on the primary row of a bundle (the row that declared the bundle). */
+  isPrimary: boolean("is_primary").default(false).notNull(),
 });
 
 // --- JWT Key Store Schema ---
@@ -42,5 +58,67 @@ export const pluginConfigs = pgTable(
   },
   (table) => ({
     pk: primaryKey({ columns: [table.pluginId, table.configId] }),
-  })
+  }),
+);
+
+// --- Plugin Artifact Store ---
+// Tarball bytes for runtime-installed plugins. Shared across all instances
+// so a freshly spun replica can recover plugins without re-fetching from
+// the original source.
+export const pluginArtifacts = pgTable(
+  "plugin_artifacts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    pluginName: text("plugin_name").notNull(),
+    version: text("version").notNull(),
+    bundleId: uuid("bundle_id"),
+    tarball: text("tarball").notNull(), // base64-encoded bytes (drizzle bytea handling is awkward; text is portable)
+    contentHash: text("content_hash").notNull(), // sha256 hex
+    sizeBytes: integer("size_bytes").notNull(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (table) => ({
+    pluginNameVersionIdx: uniqueIndex("plugin_artifacts_name_version_idx").on(
+      table.pluginName,
+      table.version,
+    ),
+    contentHashIdx: index("plugin_artifacts_content_hash_idx").on(
+      table.contentHash,
+    ),
+  }),
+);
+
+// --- Plugin Install Events (audit + reviewable error log) ---
+export const pluginInstallEvents = pgTable(
+  "plugin_install_events",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    pluginName: text("plugin_name"),
+    bundleId: uuid("bundle_id"),
+    /** "install" | "uninstall" */
+    action: text("action").notNull(),
+    /**
+     * Phase within action:
+     *   "validate" | "persist" | "broadcast" | "in-process-load" |
+     *   "in-process-unload" | "destructive-cleanup" | "audit"
+     */
+    phase: text("phase").notNull(),
+    /** "started" | "succeeded" | "failed" */
+    status: text("status").notNull(),
+    source: jsonb("source"),
+    error: text("error"),
+    instanceId: text("instance_id").notNull(),
+    userId: text("user_id"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (table) => ({
+    pluginNameCreatedIdx: index("plugin_install_events_name_created_idx").on(
+      table.pluginName,
+      table.createdAt,
+    ),
+    statusCreatedIdx: index("plugin_install_events_status_created_idx").on(
+      table.status,
+      table.createdAt,
+    ),
+  }),
 );

package/src/services/compatibility-checker.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from "bun:test";
+import { checkCompatibility } from "./compatibility-checker";
+import type { InstallPackageMetadata } from "@checkstack/common";
+
+const minimalPkg = (
+  override: Partial<InstallPackageMetadata>,
+): InstallPackageMetadata => ({
+  name: "@scope/example",
+  version: "1.0.0",
+  description: "example",
+  author: "test",
+  license: "Elastic-2.0",
+  checkstack: { type: "backend", pluginId: "example" },
+  ...override,
+});
+
+describe("checkCompatibility", () => {
+  it("passes when every @checkstack/* dep is satisfied by loaded versions", () => {
+    const pkg = minimalPkg({
+      dependencies: {
+        "@checkstack/backend-api": "^1.0.0",
+        "@checkstack/common": "^1.0.0",
+      },
+    });
+    const issues = checkCompatibility({
+      packages: [pkg],
+      loadedVersions: new Map([
+        ["@checkstack/backend-api", "1.2.3"],
+        ["@checkstack/common", "1.5.0"],
+      ]),
+    });
+    expect(issues).toEqual([]);
+  });
+
+  it("ignores non-@checkstack deps", () => {
+    const pkg = minimalPkg({
+      dependencies: { lodash: "^4.0.0", react: "^18.0.0" },
+    });
+    const issues = checkCompatibility({
+      packages: [pkg],
+      loadedVersions: new Map(),
+    });
+    expect(issues).toEqual([]);
+  });
+
+  it("flags missing @checkstack/* dependency not in bundle", () => {
+    const pkg = minimalPkg({
+      dependencies: { "@checkstack/missing-pkg": "^1.0.0" },
+    });
+    const issues = checkCompatibility({
+      packages: [pkg],
+      loadedVersions: new Map(),
+    });
+    expect(issues).toHaveLength(1);
+    expect(issues[0].kind).toBe("missing-dependency");
+    expect(issues[0].dependency).toBe("@checkstack/missing-pkg");
+  });
+
+  it("flags semver mismatch against loaded platform version", () => {
+    const pkg = minimalPkg({
+      dependencies: { "@checkstack/backend-api": "^2.0.0" },
+    });
+    const issues = checkCompatibility({
+      packages: [pkg],
+      loadedVersions: new Map([["@checkstack/backend-api", "1.0.0"]]),
+    });
+    expect(issues).toHaveLength(1);
+    expect(issues[0].kind).toBe("version-mismatch");
+    expect(issues[0].declared).toBe("^2.0.0");
+    expect(issues[0].actual).toBe("1.0.0");
+  });
+
+  it("rejects unresolved workspace:* ranges (must be resolved at pack time)", () => {
+    const pkg = minimalPkg({
+      dependencies: { "@checkstack/backend-api": "workspace:*" },
+    });
+    const issues = checkCompatibility({
+      packages: [pkg],
+      loadedVersions: new Map([["@checkstack/backend-api", "1.0.0"]]),
+    });
+    expect(issues).toHaveLength(1);
+    expect(issues[0].kind).toBe("version-mismatch");
+    expect(issues[0].declared).toBe("workspace:*");
+  });
+
+  it("satisfies bundle-internal deps from sibling packages, not platform versions", () => {
+    const primary = minimalPkg({
+      name: "@scope/foo-backend",
+      version: "1.0.0",
+      dependencies: { "@scope/foo-common": "^1.0.0" },
+    });
+    const sibling = minimalPkg({
+      name: "@scope/foo-common",
+      version: "1.0.0",
+      checkstack: { type: "common", pluginId: "foo" },
+    });
+
+    const issues = checkCompatibility({
+      packages: [primary, sibling],
+      loadedVersions: new Map(), // platform doesn't have @scope/foo-common
+    });
+    // The dep is `@scope/foo-common`, not `@checkstack/*`, so it isn't
+    // checked at all. But verify the check would also pass for the
+    // (more interesting) `@checkstack/*` case:
+  });
+
+  it("satisfies bundle-internal @checkstack/* dep from a sibling package", () => {
+    const primary = minimalPkg({
+      name: "@checkstack/foo-backend",
+      version: "1.0.0",
+      dependencies: { "@checkstack/foo-common": "^1.0.0" },
+    });
+    const sibling = minimalPkg({
+      name: "@checkstack/foo-common",
+      version: "1.0.0",
+      checkstack: { type: "common", pluginId: "foo" },
+    });
+
+    const issues = checkCompatibility({
+      packages: [primary, sibling],
+      loadedVersions: new Map(),
+    });
+    expect(issues).toEqual([]);
+  });
+
+  it("flags bundle-internal dep when version doesn't match", () => {
+    const primary = minimalPkg({
+      name: "@checkstack/foo-backend",
+      version: "1.0.0",
+      dependencies: { "@checkstack/foo-common": "^2.0.0" },
+    });
+    const sibling = minimalPkg({
+      name: "@checkstack/foo-common",
+      version: "1.0.0",
+      checkstack: { type: "common", pluginId: "foo" },
+    });
+
+    const issues = checkCompatibility({
+      packages: [primary, sibling],
+      loadedVersions: new Map(),
+    });
+    expect(issues).toHaveLength(1);
+    expect(issues[0].kind).toBe("version-mismatch");
+    expect(issues[0].dependency).toBe("@checkstack/foo-common");
+  });
+});

package/src/services/compatibility-checker.ts

@@ -0,0 +1,137 @@
+import path from "node:path";
+import fs from "node:fs";
+import semver from "semver";
+import type { InstallPackageMetadata } from "@checkstack/common";
+import type { CompatibilityIssue } from "@checkstack/pluginmanager-common";
+import { rootLogger } from "../logger";
+
+/**
+ * Builds a snapshot of every `@checkstack/*` package the current process
+ * can resolve, with its installed `version`. Used as the source of truth
+ * for compatibility checks.
+ *
+ * We don't need a separate "core version" — every package version is its
+ * own contract.
+ */
+export function loadCheckstackPackageVersions({
+  workspaceRoot,
+  runtimeDir,
+}: {
+  workspaceRoot: string;
+  runtimeDir: string;
+}): Map<string, string> {
+  const versions = new Map<string, string>();
+
+  const walk = (dir: string) => {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const pkgJsonPath = path.join(dir, entry.name, "package.json");
+      if (!fs.existsSync(pkgJsonPath)) continue;
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+        if (
+          typeof pkg.name === "string" &&
+          pkg.name.startsWith("@checkstack/") &&
+          typeof pkg.version === "string"
+         && // First-write wins: monorepo source wins over runtime_plugins
+          !versions.has(pkg.name)) {
+            versions.set(pkg.name, pkg.version);
+          }
+      } catch (error) {
+        rootLogger.debug(`Failed to read ${pkgJsonPath}`, error);
+      }
+    }
+  };
+
+  walk(path.join(workspaceRoot, "core"));
+  walk(path.join(workspaceRoot, "plugins"));
+  walk(path.join(runtimeDir, "node_modules"));
+  walk(path.join(runtimeDir, "node_modules", "@checkstack"));
+
+  return versions;
+}
+
+/**
+ * Check that every `@checkstack/*` dep declared by a plugin (and its bundle
+ * siblings) is satisfiable from the loaded package set OR from another
+ * package in the same install bundle.
+ *
+ * Returns an empty array when compatible, a populated array of issues otherwise.
+ */
+export function checkCompatibility({
+  packages,
+  loadedVersions,
+}: {
+  packages: InstallPackageMetadata[];
+  loadedVersions: Map<string, string>;
+}): CompatibilityIssue[] {
+  const issues: CompatibilityIssue[] = [];
+
+  // Bundle-internal deps: plugins in the same install set satisfy each other.
+  const bundleVersions = new Map<string, string>();
+  for (const pkg of packages) {
+    bundleVersions.set(pkg.name, pkg.version);
+  }
+
+  for (const pkg of packages) {
+    const deps = pkg.dependencies ?? {};
+    for (const [depName, declaredRange] of Object.entries(deps)) {
+      if (!depName.startsWith("@checkstack/")) continue;
+
+      // Skip workspace ranges — these only appear in monorepo source files,
+      // never in published tarballs (the pack CLI rewrites them). If we see
+      // one here it's a sign the plugin wasn't packed via our CLI.
+      if (declaredRange.startsWith("workspace:")) {
+        issues.push({
+          pluginName: pkg.name,
+          kind: "version-mismatch",
+          dependency: depName,
+          declared: declaredRange,
+          message: `Plugin '${pkg.name}' depends on '${depName}' with unresolved 'workspace:*' range. Re-pack with '@checkstack/scripts plugin-pack' which resolves workspace ranges to concrete versions.`,
+        });
+        continue;
+      }
+
+      const bundleVersion = bundleVersions.get(depName);
+      if (bundleVersion !== undefined) {
+        if (!semver.satisfies(bundleVersion, declaredRange)) {
+          issues.push({
+            pluginName: pkg.name,
+            kind: "version-mismatch",
+            dependency: depName,
+            declared: declaredRange,
+            actual: bundleVersion,
+            message: `Plugin '${pkg.name}' requires ${depName}@${declaredRange} but the bundle ships ${bundleVersion}.`,
+          });
+        }
+        continue;
+      }
+
+      const loadedVersion = loadedVersions.get(depName);
+      if (loadedVersion === undefined) {
+        issues.push({
+          pluginName: pkg.name,
+          kind: "missing-dependency",
+          dependency: depName,
+          declared: declaredRange,
+          message: `Plugin '${pkg.name}' depends on '${depName}' which is not loaded by this platform and is not part of the install bundle.`,
+        });
+        continue;
+      }
+
+      if (!semver.satisfies(loadedVersion, declaredRange)) {
+        issues.push({
+          pluginName: pkg.name,
+          kind: "version-mismatch",
+          dependency: depName,
+          declared: declaredRange,
+          actual: loadedVersion,
+          message: `Plugin '${pkg.name}' requires ${depName}@${declaredRange} but this platform has ${loadedVersion}.`,
+        });
+      }
+    }
+  }
+
+  return issues;
+}

package/src/services/dev-auth.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "bun:test";
+import { createDevAuthService } from "./dev-auth";
+
+describe("createDevAuthService", () => {
+  it("authenticate() returns a stable RealUser identity", async () => {
+    const svc = createDevAuthService({ getAllAccessRules: () => [] });
+    const user = await svc.authenticate(new Request("http://x"));
+    expect(user).toBeDefined();
+    if (!user || user.type !== "user") {
+      throw new Error("expected RealUser");
+    }
+    expect(user.id).toBe("dev-user");
+    expect(user.email).toBe("dev@checkstack.local");
+    expect(user.name).toBe("Dev User");
+    expect(user.roles).toEqual(["admin"]);
+    expect(user.teamIds).toEqual([]);
+  });
+
+  it("populates accessRules from the registered set", async () => {
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [
+        { id: "catalog.system.read" },
+        { id: "catalog.system.manage" },
+      ],
+    });
+    const user = await svc.authenticate(new Request("http://x"));
+    if (!user || user.type !== "user") throw new Error("expected RealUser");
+    expect(user.accessRules).toEqual([
+      "catalog.system.read",
+      "catalog.system.manage",
+    ]);
+  });
+
+  it("re-reads access rules on each authenticate (rules registered later still apply)", async () => {
+    const rules = [{ id: "first.rule" }];
+    const svc = createDevAuthService({ getAllAccessRules: () => rules });
+
+    const before = await svc.authenticate(new Request("http://x"));
+    if (!before || before.type !== "user") throw new Error("expected RealUser");
+    expect(before.accessRules).toEqual(["first.rule"]);
+
+    rules.push({ id: "second.rule" });
+    const after = await svc.authenticate(new Request("http://x"));
+    if (!after || after.type !== "user") throw new Error("expected RealUser");
+    expect(after.accessRules).toEqual(["first.rule", "second.rule"]);
+  });
+
+  it("getAnonymousAccessRules returns an empty list (anonymous gets nothing in dev)", async () => {
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [{ id: "x" }, { id: "y" }],
+    });
+    expect(await svc.getAnonymousAccessRules()).toEqual([]);
+  });
+
+  it("getCredentials returns an empty headers object", async () => {
+    const svc = createDevAuthService({ getAllAccessRules: () => [] });
+    expect(await svc.getCredentials()).toEqual({ headers: {} });
+  });
+
+  it("checkResourceTeamAccess always grants", async () => {
+    const svc = createDevAuthService({ getAllAccessRules: () => [] });
+    expect(
+      await svc.checkResourceTeamAccess({
+        userId: "x",
+        userType: "user",
+        resourceType: "system",
+        resourceId: "abc",
+        action: "manage",
+        hasGlobalAccess: false,
+      }),
+    ).toEqual({ hasAccess: true });
+  });
+
+  it("getAccessibleResourceIds returns the input list unfiltered", async () => {
+    const svc = createDevAuthService({ getAllAccessRules: () => [] });
+    expect(
+      await svc.getAccessibleResourceIds({
+        userId: "x",
+        userType: "user",
+        resourceType: "system",
+        resourceIds: ["one", "two", "three"],
+        action: "read",
+        hasGlobalAccess: false,
+      }),
+    ).toEqual(["one", "two", "three"]);
+  });
+});

package/src/services/dev-auth.ts

@@ -0,0 +1,56 @@
+import type { AuthService, RealUser } from "@checkstack/backend-api";
+
+/**
+ * Dev-only auth service.
+ *
+ * Used by `bunx @checkstack/scripts dev` so plugin authors don't have to
+ * deal with login flows / cookie state while iterating. Returns a
+ * synthetic user that has every registered access rule, so any procedure
+ * (regardless of the access guards on it) authorizes.
+ *
+ * NEVER register this in production. The runtime gates installation
+ * behind a `CHECKSTACK_DEV_AUTH=true` env var that we set explicitly in
+ * the dev server entry point.
+ *
+ * The user identity is stable (`dev-user`) so plugin code that derives
+ * UI / data from `user.id` behaves consistently across reloads.
+ */
+export function createDevAuthService({
+  getAllAccessRules,
+}: {
+  getAllAccessRules: () => Array<{ id: string }>;
+}): AuthService {
+  const devUser: RealUser = {
+    type: "user",
+    id: "dev-user",
+    email: "dev@checkstack.local",
+    name: "Dev User",
+    accessRules: [], // populated lazily below
+    roles: ["admin"],
+    teamIds: [],
+  };
+
+  return {
+    async authenticate(_request) {
+      // Always grant every access rule the platform currently knows about.
+      // We resolve this lazily so rules registered by plugins after auth
+      // construction (the normal flow) still apply.
+      devUser.accessRules = getAllAccessRules().map((r) => r.id);
+      return devUser;
+    },
+    async getCredentials() {
+      return { headers: {} };
+    },
+    async getAnonymousAccessRules() {
+      // Anonymous users get nothing; the dev user is the only authenticated
+      // identity in dev mode.
+      return [];
+    },
+    async checkResourceTeamAccess() {
+      return { hasAccess: true };
+    },
+    async getAccessibleResourceIds({ resourceIds }) {
+      return resourceIds;
+    },
+  };
+}

package/src/services/plugin-artifact-store.ts

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+import { eq, and } from "drizzle-orm";
+import type {
+  PluginArtifactStore,
+  SafeDatabase,
+} from "@checkstack/backend-api";
+import { pluginArtifacts } from "../schema";
+
+/**
+ * Postgres-backed artifact store.
+ *
+ * Tarball bytes are stored as base64-encoded `text` (drizzle's `bytea`
+ * support is awkward and this keeps the column portable). The 33% size
+ * overhead is fine at our hard cap (50 MB per artifact).
+ *
+ * Sharing the row across instances means a freshly spun replica can
+ * recover any runtime-installed plugin from the same Postgres the rest
+ * of the platform already depends on — no new infra.
+ */
+const MAX_ARTIFACT_SIZE = 50 * 1024 * 1024;
+
+export class PostgresPluginArtifactStore implements PluginArtifactStore {
+  readonly maxArtifactSize = MAX_ARTIFACT_SIZE;
+
+  constructor(
+    private readonly db: SafeDatabase<Record<string, unknown>>,
+  ) {}
+
+  async store({
+    pluginName,
+    version,
+    bundleId,
+    tarball,
+  }: {
+    pluginName: string;
+    version: string;
+    bundleId?: string | null;
+    tarball: Uint8Array;
+  }): Promise<{ artifactId: string; contentHash: string }> {
+    if (tarball.byteLength > MAX_ARTIFACT_SIZE) {
+      throw new Error(
+        `Artifact exceeds maximum size: ${tarball.byteLength} > ${MAX_ARTIFACT_SIZE} bytes`,
+      );
+    }
+    const contentHash = sha256Hex(tarball);
+    const encoded = Buffer.from(tarball).toString("base64");
+
+    // Upsert by (plugin_name, version): reinstalling the same version
+    // overwrites — useful for replacing a corrupted artifact, harmless
+    // when bytes are identical.
+    const inserted = await this.db
+      .insert(pluginArtifacts)
+      .values({
+        pluginName,
+        version,
+        bundleId: bundleId ?? null,
+        tarball: encoded,
+        contentHash,
+        sizeBytes: tarball.byteLength,
+      })
+      .onConflictDoUpdate({
+        target: [pluginArtifacts.pluginName, pluginArtifacts.version],
+        set: {
+          tarball: encoded,
+          contentHash,
+          sizeBytes: tarball.byteLength,
+          bundleId: bundleId ?? null,
+        },
+      })
+      .returning({ id: pluginArtifacts.id });
+
+    return { artifactId: inserted[0].id, contentHash };
+  }
+
+  async fetch({
+    pluginName,
+    version,
+  }: {
+    pluginName: string;
+    version: string;
+  }): Promise<{ tarball: Uint8Array; contentHash: string } | undefined> {
+    const rows = await this.db
+      .select()
+      .from(pluginArtifacts)
+      .where(
+        and(
+          eq(pluginArtifacts.pluginName, pluginName),
+          eq(pluginArtifacts.version, version),
+        ),
+      )
+      .limit(1);
+    if (rows.length === 0) return undefined;
+    return {
+      tarball: new Uint8Array(Buffer.from(rows[0].tarball, "base64")),
+      contentHash: rows[0].contentHash,
+    };
+  }
+
+  async fetchById(artifactId: string) {
+    const rows = await this.db
+      .select()
+      .from(pluginArtifacts)
+      .where(eq(pluginArtifacts.id, artifactId))
+      .limit(1);
+    if (rows.length === 0) return;
+    return {
+      tarball: new Uint8Array(Buffer.from(rows[0].tarball, "base64")),
+      contentHash: rows[0].contentHash,
+      pluginName: rows[0].pluginName,
+      version: rows[0].version,
+    };
+  }
+
+  async delete({ pluginName }: { pluginName: string }): Promise<void> {
+    await this.db
+      .delete(pluginArtifacts)
+      .where(eq(pluginArtifacts.pluginName, pluginName));
+  }
+
+  async deleteByBundle({ bundleId }: { bundleId: string }): Promise<void> {
+    await this.db
+      .delete(pluginArtifacts)
+      .where(eq(pluginArtifacts.bundleId, bundleId));
+  }
+}
+
+function sha256Hex(bytes: Uint8Array): string {
+  const h = createHash("sha256");
+  h.update(bytes);
+  return h.digest("hex");
+}