@checkstack/backend 0.8.2 → 0.9.1

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/event-bus.test.ts

@@ -465,5 +465,57 @@ describe("EventBus", () => {
         `No local listeners for hook: ${testHook.id}`
       );
     });
+
+    it("should drop emit (not enqueue) when no listeners are registered", async () => {
+      const testHook = createHook<{ value: number }>(
+        "test.emit.no.listeners",
+      );
+
+      // Capture queue creation: getQueue is invoked lazily on enqueue.
+      const before = (mockQueueManager as any).getQueue?.mock?.calls?.length ?? 0;
+
+      await eventBus.emit(testHook, { value: 1 });
+      await eventBus.emit(testHook, { value: 2 });
+
+      const after = (mockQueueManager as any).getQueue?.mock?.calls?.length ?? 0;
+      // No queue should be created and no enqueue should occur for an
+      // entirely unsubscribed hook — otherwise jobs would pile up forever.
+      expect(after).toBe(before);
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        `Dropped hook ${testHook.id}: no listeners registered`,
+      );
+    });
+
+    it("should enqueue when at least one distributed listener is registered", async () => {
+      const testHook = createHook<{ value: number }>(
+        "test.emit.with.listener",
+      );
+      const received: number[] = [];
+      await eventBus.subscribe("test-plugin", testHook, async (payload) => {
+        received.push(payload.value);
+      });
+
+      await eventBus.emit(testHook, { value: 7 });
+      // Allow the mock queue to deliver synchronously.
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      expect(received).toContain(7);
+    });
+
+    it("should enqueue when at least one instance-local listener is registered", async () => {
+      const testHook = createHook<{ value: number }>(
+        "test.emit.with.local.listener",
+      );
+      await eventBus.subscribe("test-plugin", testHook, async () => {}, {
+        mode: "instance-local",
+      });
+
+      // emit (distributed) should still enqueue because a local listener
+      // exists — drops are based on absence of *any* listener.
+      await eventBus.emit(testHook, { value: 1 });
+      expect(mockLogger.debug).not.toHaveBeenCalledWith(
+        `Dropped hook ${testHook.id}: no listeners registered`,
+      );
+    });
   });
 });

package/src/services/event-bus.ts

@@ -185,9 +185,35 @@ export class EventBus implements IEventBus {
   }
 
   /**
-   * Emit a hook
+   * Emit a hook.
+   *
+   * Skips the underlying queue enqueue when no listener has been
+   * registered for the hook in this process. Without this guard, hooks
+   * with no subscribers (e.g. `core.plugin.initialized` when no plugin
+   * has registered a listener) would accumulate jobs in the in-memory
+   * queue forever — they'd be enqueued, no consumer group exists to
+   * process them, and `processNext` short-circuits before its cleanup
+   * pass when `consumerGroups.size === 0`.
+   *
+   * Note: this checks listeners in the *local process*. In distributed
+   * deployments with a Redis-backed queue, a subscriber on another
+   * replica would never see the event under this rule. Callers that
+   * need cross-process delivery must therefore ensure at least one
+   * listener registers on every replica that should receive the hook.
    */
   async emit<T>(hook: Hook<T>, payload: T): Promise<void> {
+    const hasDistributedListeners =
+      (this.listeners.get(hook.id)?.length ?? 0) > 0;
+    const hasLocalListeners =
+      (this.localListeners.get(hook.id)?.length ?? 0) > 0;
+
+    if (!hasDistributedListeners && !hasLocalListeners) {
+      this.logger.debug(
+        `Dropped hook ${hook.id}: no listeners registered`,
+      );
+      return;
+    }
+
     let channel = this.queueChannels.get(hook.id);
 
     // Create channel lazily if not exists

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

package/src/services/plugin-bundle-resolver.ts

@@ -0,0 +1,76 @@
+import type {
+  PluginInstallerRegistry,
+  PluginSource,
+  FetchedTarball,
+  NpmPluginSource,
+} from "@checkstack/backend-api";
+
+/**
+ * Given a `PluginSource`, fetch the primary tarball and recursively resolve
+ * any bundle siblings into a single normalized list.
+ *
+ * - npm: bundle siblings are *separate* npm packages; for each, we issue a
+ *   second `fetchTarball` call against the same registry.
+ * - tarball / github: bundle siblings are *inline* in the outer tarball
+ *   (per the `bundle.json` manifest); the per-source installer already
+ *   extracted them.
+ *
+ * Returns the primary first, then siblings in declared order.
+ */
+export async function resolveBundle({
+  source,
+  installerRegistry,
+}: {
+  source: PluginSource;
+  installerRegistry: PluginInstallerRegistry;
+}): Promise<{
+  primary: FetchedTarball;
+  packages: FetchedTarball[];
+  bundleId?: string;
+}> {
+  const primary = await installerRegistry.fetchTarball(source);
+  const packages: FetchedTarball[] = [primary];
+
+  // Inline bundle (tarball / github)
+  if (primary.bundle) {
+    for (const sib of primary.bundle.siblings) {
+      if (sib.packageJson.name === primary.packageJson.name) continue;
+      packages.push({ tarball: sib.tarball, packageJson: sib.packageJson });
+    }
+    return { primary, packages };
+  }
+
+  // Cross-package bundle for npm: declared via primary's checkstack.bundle
+  const declared = primary.packageJson.checkstack.bundle;
+  if (declared && declared.length > 0) {
+    if (source.type !== "npm") {
+      // Already-inline bundles are handled above; if a non-npm source
+      // declared `checkstack.bundle` without inlining, refuse — the
+      // expectation is the pack CLI produces a bundle tarball.
+      throw new Error(
+        `Plugin ${primary.packageJson.name} declares 'checkstack.bundle' but the source ` +
+          `(${source.type}) did not ship sibling tarballs. Use the GitHub release / tarball ` +
+          `source with a --bundle-mode tarball, or remove 'checkstack.bundle'.`,
+      );
+    }
+    for (const siblingName of declared) {
+      const siblingSource: NpmPluginSource = {
+        type: "npm",
+        packageName: siblingName,
+        // Pin sibling version to primary's exact version — bundles are
+        // released atomically and identical-versioned by convention.
+        version: primary.packageJson.version,
+        registry: source.registry,
+      };
+      const fetched = await installerRegistry.fetchTarball(siblingSource);
+      if (fetched.bundle) {
+        throw new Error(
+          `Sibling '${siblingName}' itself ships a bundle — bundles cannot nest.`,
+        );
+      }
+      packages.push(fetched);
+    }
+  }
+
+  return { primary, packages };
+}

package/src/services/plugin-event-recorder.ts

@@ -0,0 +1,87 @@
+import { desc, eq } from "drizzle-orm";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import type { PluginSource } from "@checkstack/common";
+import type {
+  InstallEvent,
+  InstallEventAction,
+  InstallEventPhase,
+  InstallEventStatus,
+} from "@checkstack/pluginmanager-common";
+import { pluginInstallEvents } from "../schema";
+
+/**
+ * Persist install/uninstall lifecycle events.
+ *
+ * Every step of the install/uninstall flow writes a row here:
+ *   - originator: validate / persist / broadcast / destructive-cleanup / audit
+ *   - receiving instances: in-process-load / in-process-unload
+ *
+ * Failures are kept (status="failed") so the admin Events page can surface
+ * partial state for manual remediation. The originator dying mid-flight
+ * leaves a "started" row that never transitions — the UI flags those.
+ */
+export class PluginEventRecorder {
+  constructor(
+    private readonly db: SafeDatabase<Record<string, unknown>>,
+    private readonly instanceId: string,
+  ) {}
+
+  async record(input: {
+    pluginName?: string | null;
+    bundleId?: string | null;
+    action: InstallEventAction;
+    phase: InstallEventPhase;
+    status: InstallEventStatus;
+    source?: PluginSource | null;
+    error?: string | null;
+    userId?: string | null;
+  }): Promise<void> {
+    // Drizzle writes `null` as a real NULL column and `undefined` as
+    // "skip this column"; both map to NULL on insert here, but normalize
+    // to `null` so the row's shape matches the schema-declared
+    // nullable columns.
+    await this.db.insert(pluginInstallEvents).values({
+      pluginName: input.pluginName ?? null,
+      bundleId: input.bundleId ?? null,
+      action: input.action,
+      phase: input.phase,
+      status: input.status,
+      source: input.source ?? null,
+      error: input.error ?? null,
+      instanceId: this.instanceId,
+      userId: input.userId ?? null,
+    });
+  }
+
+  async list(input?: {
+    pluginName?: string;
+    limit?: number;
+  }): Promise<InstallEvent[]> {
+    const limit = input?.limit ?? 100;
+    const where = input?.pluginName
+      ? eq(pluginInstallEvents.pluginName, input.pluginName)
+      : undefined;
+
+    const rows = await this.db
+      .select()
+      .from(pluginInstallEvents)
+      .where(where)
+      .orderBy(desc(pluginInstallEvents.createdAt))
+      .limit(limit);
+
+    return rows.map((row) => ({
+      id: row.id,
+      pluginName: row.pluginName,
+      bundleId: row.bundleId,
+      action: row.action as InstallEventAction,
+      phase: row.phase as InstallEventPhase,
+      status: row.status as InstallEventStatus,
+      source: row.source as PluginSource | null,
+      error: row.error,
+      instanceId: row.instanceId,
+      userId: row.userId,
+      createdAt: row.createdAt.toISOString(),
+    }));
+  }
+
+}

package/src/services/plugin-installers/catalog-installer.ts

@@ -0,0 +1,33 @@
+import type {
+  PluginInstaller,
+  PluginSource,
+  FetchedTarball,
+  InstalledArtifact,
+} from "@checkstack/backend-api";
+import { PluginInstallError } from "./plugin-install-error";
+
+/**
+ * Stub for the future Checkstack catalog/marketplace.
+ *
+ * Surfaces in the UI as a "Coming Soon" tab; calling the install endpoint
+ * with a `catalog` source returns an explicit not-implemented error.
+ */
+export class CatalogPluginInstaller implements PluginInstaller {
+  async fetchTarball(_source: PluginSource): Promise<FetchedTarball> {
+    throw new PluginInstallError(
+      "NOT_IMPLEMENTED",
+      "The Checkstack plugin catalog isn't available yet. Install via npm, GitHub release, or tarball upload in the meantime.",
+    );
+  }
+
+  async installFromArtifact(_input: {
+    tarball: Uint8Array;
+    pluginName: string;
+    allowInstallScripts?: boolean;
+  }): Promise<InstalledArtifact> {
+    throw new PluginInstallError(
+      "NOT_IMPLEMENTED",
+      "The Checkstack plugin catalog isn't available yet.",
+    );
+  }
+}