@checkstack/script-packages-store-postgres 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# @checkstack/script-packages-store-postgres
+
+## 0.2.0
+
+### Minor Changes
+
+- 270ef29: Add the two built-in blob-store plugins for script packages.
+
+  - `script-packages-store-postgres` (default, zero extra infra): persists
+    content-addressed blobs in Postgres as base64 `text` (following the
+    existing repo convention for binary columns), registered as the
+    `postgres` backend via `blobStoreExtensionPoint`.
+  - `script-packages-store-s3` (preferred when configured): S3-compatible
+    store backed by Bun's native `S3Client` (no AWS SDK). Config from env
+    (`endpoint`, `bucket`, `region`, `accessKeyId`, `secretAccessKey`,
+    `forcePathStyle`); credentials never touch the DB. Registers the `s3`
+    backend only when configured, and reports a partial-config error
+    instead of silently falling back.
+
+### Patch Changes
+
+- b995afb: Harden the script-package blob byte boundary against a raw `ArrayBuffer`.
+
+  Blob bytes can reach the content-hash and storage codecs as a raw `ArrayBuffer` (e.g. from an S3/HTTP transport's `arrayBuffer()`), and Node/Bun's `crypto.Hash.update()` rejects a bare `ArrayBuffer` ("The 'data' argument must be of type string or an instance of Buffer, TypedArray, or DataView. Received an instance of ArrayBuffer"), which would fail a real-package install with `status=error`. `blobSha256` / `verifyBlobSha256` (script-packages-backend) and `encodeBlob` (script-packages-store-postgres) now normalize `ArrayBuffer` to a `Uint8Array` view at the boundary before hashing/encoding. A view over the same bytes hashes and encodes identically, so existing content hashes and stored blobs are unchanged. Adds regression tests feeding an `ArrayBuffer` through both the hash and the Postgres codec.
+
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+  - @checkstack/backend-api@0.19.0
+  - @checkstack/script-packages-backend@0.2.0
+  - @checkstack/script-packages-common@0.2.0

package/drizzle/0000_thankful_doorman.sql

@@ -0,0 +1,6 @@
+CREATE TABLE "script_package_blob_data" (
+	"integrity" text PRIMARY KEY NOT NULL,
+	"data" text NOT NULL,
+	"size_bytes" bigint NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);

package/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,57 @@
+{
+  "id": "f78fe1fa-2d5c-410f-859b-5d200702f378",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.script_package_blob_data": {
+      "name": "script_package_blob_data",
+      "schema": "",
+      "columns": {
+        "integrity": {
+          "name": "integrity",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "data": {
+          "name": "data",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1780148042260,
+      "tag": "0000_thankful_doorman",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/schema.ts",
+  out: "./drizzle",
+  dialect: "postgresql",
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@checkstack/script-packages-store-postgres",
+  "version": "0.2.0",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "checkstack": {
+    "type": "backend"
+  },
+  "scripts": {
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "0.18.0",
+    "@checkstack/common": "0.12.0",
+    "@checkstack/script-packages-backend": "0.1.0",
+    "@checkstack/script-packages-common": "0.1.0",
+    "drizzle-orm": "^0.45.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@checkstack/scripts": "0.3.4",
+    "@checkstack/tsconfig": "0.0.7",
+    "drizzle-kit": "^0.31.10",
+    "typescript": "^5.7.2"
+  }
+}

package/src/codec.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import { encodeBlob, decodeBlob } from "./codec";
+
+describe("blob codec", () => {
+  test("round-trips arbitrary bytes", () => {
+    const bytes = new Uint8Array([0, 1, 2, 250, 255, 128, 64]);
+    expect([...decodeBlob(encodeBlob(bytes))]).toEqual([...bytes]);
+  });
+
+  test("round-trips an empty buffer", () => {
+    expect(decodeBlob(encodeBlob(new Uint8Array())).length).toBe(0);
+  });
+
+  test("round-trips a larger random payload", () => {
+    const bytes = new Uint8Array(4096);
+    for (let i = 0; i < bytes.length; i++) bytes[i] = (i * 37) % 256;
+    const decoded = decodeBlob(encodeBlob(bytes));
+    expect(decoded.length).toBe(bytes.length);
+    expect([...decoded]).toEqual([...bytes]);
+  });
+
+  // Regression: a store `put` may receive a raw ArrayBuffer from an S3/HTTP
+  // transport. `encodeBlob` must normalize it (not wrap the whole buffer) so
+  // the round-trip is byte-identical to the equivalent Uint8Array.
+  test("encodes a raw ArrayBuffer identically to its Uint8Array view", () => {
+    const u8 = new Uint8Array([0, 1, 2, 250, 255, 128, 64]);
+    const ab = u8.buffer.slice(0);
+    expect(ab).toBeInstanceOf(ArrayBuffer);
+    expect(encodeBlob(ab)).toBe(encodeBlob(u8));
+    expect([...decodeBlob(encodeBlob(ab))]).toEqual([...u8]);
+  });
+});

package/src/codec.ts

@@ -0,0 +1,24 @@
+/**
+ * Base64 codec for blob bytes stored in the `text` column.
+ *
+ * Kept as a separate, pure module so the round-trip is unit-testable
+ * without a database.
+ */
+
+/** Bytes as they arrive at the encode boundary from any blob source. */
+export type BlobBytes = Uint8Array | ArrayBuffer;
+
+/**
+ * Base64-encode blob bytes for the `text` column. Accepts a raw `ArrayBuffer`
+ * (e.g. from an S3/HTTP transport) as well as a `Uint8Array`: `Buffer.from`
+ * wraps an `ArrayBuffer` over the whole buffer, so we normalize to a view
+ * first to encode exactly the intended bytes.
+ */
+export function encodeBlob(bytes: BlobBytes): string {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  return Buffer.from(view).toString("base64");
+}
+
+export function decodeBlob(data: string): Uint8Array {
+  return new Uint8Array(Buffer.from(data, "base64"));
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
+import { blobStoreExtensionPoint } from "@checkstack/script-packages-backend";
+import { pluginMetadata } from "./plugin-metadata";
+import { createPostgresBlobStore, POSTGRES_BLOB_STORE_ID } from "./store";
+import * as schema from "./schema";
+
+/**
+ * Default blob-store plugin: persists script-package blobs in Postgres
+ * (base64 `text`). Always available; selected when no S3 is configured.
+ *
+ * The store is built in `init()` (where `database` is injected) and
+ * registered with the host's `blobStoreExtensionPoint`. The host runs its
+ * `register()` first (dep ordering), so the extension point exists by the
+ * time this init runs.
+ */
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    env.registerInit({
+      schema,
+      deps: {
+        logger: coreServices.logger,
+      },
+      init: async ({ logger, database }) => {
+        const store = createPostgresBlobStore(database);
+        env
+          .getExtensionPoint(blobStoreExtensionPoint)
+          .registerBlobStore(store, pluginMetadata);
+        logger.debug(
+          `📦 Registered "${POSTGRES_BLOB_STORE_ID}" script-package blob store.`,
+        );
+      },
+    });
+  },
+});
+
+export { createPostgresBlobStore, POSTGRES_BLOB_STORE_ID } from "./store";

package/src/plugin-metadata.ts

@@ -0,0 +1,5 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "script-packages-store-postgres",
+});

package/src/schema.ts

@@ -0,0 +1,20 @@
+import { pgTable, text, bigint, timestamp } from "drizzle-orm/pg-core";
+
+/**
+ * Postgres blob store schema.
+ *
+ * One row per content-addressed blob, keyed by integrity. Compressed blob
+ * bytes are stored base64-encoded in a `text` column - following the
+ * existing repo convention (`core/backend/src/schema.ts` does the same for
+ * plugin tarballs) because Drizzle's `bytea` handling is awkward and base64
+ * `text` is portable. Blobs are bounded by the size guardrail and the
+ * lightweight-pure-JS regime, so the ~33% base64 overhead is acceptable for
+ * the zero-extra-infra default backend.
+ */
+export const scriptPackageBlobData = pgTable("script_package_blob_data", {
+  integrity: text("integrity").primaryKey(),
+  /** base64-encoded compressed blob bytes. */
+  data: text("data").notNull(),
+  sizeBytes: bigint("size_bytes", { mode: "number" }).notNull(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+});

package/src/store.ts

@@ -0,0 +1,65 @@
+import { eq } from "drizzle-orm";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import type { BlobStore } from "@checkstack/script-packages-backend";
+import { scriptPackageBlobData } from "./schema";
+import { encodeBlob, decodeBlob } from "./codec";
+
+export const POSTGRES_BLOB_STORE_ID = "postgres";
+
+type Schema = { scriptPackageBlobData: typeof scriptPackageBlobData };
+
+/**
+ * Postgres-backed {@link BlobStore} - the default, zero-extra-infra
+ * backend. Content-addressed: `put` of an already-present integrity is a
+ * no-op (identical bytes by definition), so we use `onConflictDoNothing`.
+ */
+export function createPostgresBlobStore(
+  db: SafeDatabase<Schema>,
+): BlobStore {
+  return {
+    id: POSTGRES_BLOB_STORE_ID,
+
+    async put({ integrity, bytes }) {
+      await db
+        .insert(scriptPackageBlobData)
+        .values({
+          integrity,
+          data: encodeBlob(bytes),
+          sizeBytes: bytes.byteLength,
+        })
+        .onConflictDoNothing({ target: scriptPackageBlobData.integrity });
+    },
+
+    async get({ integrity }) {
+      const rows = await db
+        .select({ data: scriptPackageBlobData.data })
+        .from(scriptPackageBlobData)
+        .where(eq(scriptPackageBlobData.integrity, integrity))
+        .limit(1);
+      const row = rows[0];
+      return row ? decodeBlob(row.data) : undefined;
+    },
+
+    async has({ integrity }) {
+      const rows = await db
+        .select({ integrity: scriptPackageBlobData.integrity })
+        .from(scriptPackageBlobData)
+        .where(eq(scriptPackageBlobData.integrity, integrity))
+        .limit(1);
+      return rows.length > 0;
+    },
+
+    async delete({ integrity }) {
+      await db
+        .delete(scriptPackageBlobData)
+        .where(eq(scriptPackageBlobData.integrity, integrity));
+    },
+
+    async list() {
+      const rows = await db
+        .select({ integrity: scriptPackageBlobData.integrity })
+        .from(scriptPackageBlobData);
+      return rows.map((r) => r.integrity);
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../backend-api"
+    },
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../script-packages-backend"
+    },
+    {
+      "path": "../script-packages-common"
+    }
+  ]
+}