@hasna/skills 0.10.50 → 0.10.52

package/bin/maintenance.js

@@ -1909,7 +1909,7 @@ var {
 // src/server/maintenance-entry.ts
 import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "fs";
 import { createHash as createHash3 } from "crypto";
-var {SQL: SQL2 } = globalThis.Bun;
+var {SQL: SQL3 } = globalThis.Bun;
 
 // src/server/execution-grant-store.ts
 import { randomUUID } from "crypto";
@@ -3991,6 +3991,140 @@ async function inspectEnrollment(databaseUrl, input) {
   }
 }
 
+// src/server/schema-census.ts
+var {SQL: SQL2 } = globalThis.Bun;
+
+class SchemaCensusError extends Error {
+  code;
+  constructor(code) {
+    super(code);
+    this.code = code;
+    this.name = "SchemaCensusError";
+  }
+}
+var refuse2 = (code) => {
+  throw new SchemaCensusError(code);
+};
+var FIXED_SCHEMA = "public";
+var STATEMENT_TIMEOUT_MS = 5000;
+var LOCK_TIMEOUT_MS = 1000;
+var MAX_MIGRATION_VERSIONS = 128;
+var MAX_MIGRATION_VERSION_CHARS = 64;
+var MAX_IDENTIFIER_CHARS = 128;
+var MAX_SERVER_VERSION_CHARS = 256;
+var MAX_CENSUS_BYTES = 16 * 1024;
+var boundedText = (value, max) => {
+  if (typeof value !== "string" || value.length === 0 || /[\u0000-\u001f\u007f]/.test(value))
+    return refuse2("CENSUS_INVALID_RESULT");
+  if (value.length > max)
+    return refuse2("CENSUS_OUTPUT_UNBOUNDED");
+  return value;
+};
+var boundedCount = (value) => {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+    return refuse2("CENSUS_INVALID_RESULT");
+  return value;
+};
+async function inspectSchemaCensus(databaseUrl) {
+  try {
+    const url = new URL(databaseUrl);
+    if (!["postgres:", "postgresql:"].includes(url.protocol) || !url.hostname)
+      refuse2("CENSUS_POSTGRES_REQUIRED");
+  } catch {
+    refuse2("CENSUS_POSTGRES_REQUIRED");
+  }
+  let sql;
+  try {
+    sql = new SQL2(databaseUrl, { max: 1, connectionTimeout: 5, idleTimeout: 5 });
+    return await sql.begin("ISOLATION LEVEL REPEATABLE READ READ ONLY", async (tx) => {
+      await tx.unsafe("SET LOCAL statement_timeout = '5s'");
+      await tx.unsafe("SET LOCAL lock_timeout = '1s'");
+      const mode = await tx`SELECT current_setting('transaction_read_only') AS read_only,
+        current_setting('transaction_isolation') AS isolation,
+        current_setting('statement_timeout') AS statement_timeout,
+        current_setting('lock_timeout') AS lock_timeout`;
+      if (mode.length !== 1 || mode[0].read_only !== "on" || mode[0].isolation !== "repeatable read" || mode[0].statement_timeout !== "5s" || mode[0].lock_timeout !== "1s") {
+        refuse2("CENSUS_FAILED");
+      }
+      const identity = await tx`SELECT current_database() AS database, current_user AS role,
+        version() AS server_version, current_schema() AS schema`;
+      if (identity.length !== 1)
+        refuse2("CENSUS_INVALID_RESULT");
+      const database = boundedText(identity[0].database, MAX_IDENTIFIER_CHARS);
+      const role = boundedText(identity[0].role, MAX_IDENTIFIER_CHARS);
+      const serverVersion = boundedText(identity[0].server_version, MAX_SERVER_VERSION_CHARS);
+      if (identity[0].schema !== FIXED_SCHEMA)
+        refuse2("CENSUS_TARGET_MISMATCH");
+      const ledger = await tx`SELECT version FROM public.schema_migrations ORDER BY version LIMIT ${MAX_MIGRATION_VERSIONS + 1}`;
+      if (ledger.length > MAX_MIGRATION_VERSIONS)
+        refuse2("CENSUS_OUTPUT_UNBOUNDED");
+      const versions = ledger.map((row) => boundedText(row.version, MAX_MIGRATION_VERSION_CHARS));
+      const registryCount = await tx`SELECT count(*)::int AS rows FROM public.skills_registry`;
+      const versionCount = await tx`SELECT count(*)::int AS rows FROM public.skills_versions`;
+      if (registryCount.length !== 1 || versionCount.length !== 1)
+        refuse2("CENSUS_INVALID_RESULT");
+      const registryRows = boundedCount(registryCount[0].rows);
+      const versionRows = boundedCount(versionCount[0].rows);
+      const groups = await tx`SELECT lifecycle, (tombstoned_at IS NOT NULL) AS tombstoned, count(*)::int AS rows
+        FROM public.skills_registry GROUP BY 1, 2 LIMIT 5`;
+      if (groups.length > 4)
+        refuse2("CENSUS_INVALID_RESULT");
+      const lifecycle = { active: { live: 0, tombstoned: 0 }, archived: { live: 0, tombstoned: 0 } };
+      for (const group of groups) {
+        const name = group.lifecycle;
+        const tombstoned = group.tombstoned;
+        if (name !== "active" && name !== "archived" || typeof tombstoned !== "boolean")
+          return refuse2("CENSUS_INVALID_RESULT");
+        lifecycle[name][tombstoned ? "tombstoned" : "live"] = boundedCount(group.rows);
+      }
+      const epochColumn = await tx`SELECT count(*)::int AS rows FROM information_schema.columns
+        WHERE table_schema = ${FIXED_SCHEMA} AND table_name = 'skills_registry' AND column_name = 'authorization_epoch'`;
+      if (epochColumn.length !== 1)
+        refuse2("CENSUS_INVALID_RESULT");
+      const epochPresent = boundedCount(epochColumn[0].rows);
+      if (epochPresent > 1)
+        refuse2("CENSUS_INVALID_RESULT");
+      let authorizationEpoch;
+      if (epochPresent === 0)
+        authorizationEpoch = { exists: false };
+      else {
+        const epochNulls = await tx`SELECT count(*)::int AS rows FROM public.skills_registry WHERE authorization_epoch IS NULL`;
+        if (epochNulls.length !== 1)
+          refuse2("CENSUS_INVALID_RESULT");
+        authorizationEpoch = { exists: true, nullCount: boundedCount(epochNulls[0].rows) };
+      }
+      const result = {
+        status: "inspected",
+        database,
+        role,
+        serverVersion,
+        schema: FIXED_SCHEMA,
+        transaction: { readOnly: true, isolation: "repeatable read", statementTimeoutMs: STATEMENT_TIMEOUT_MS, lockTimeoutMs: LOCK_TIMEOUT_MS },
+        migrations: { count: versions.length, versions },
+        registry: { rows: registryRows },
+        versions: { rows: versionRows },
+        lifecycle,
+        authorizationEpoch
+      };
+      if (Buffer.byteLength(JSON.stringify(result), "utf8") > MAX_CENSUS_BYTES)
+        refuse2("CENSUS_OUTPUT_UNBOUNDED");
+      return result;
+    });
+  } catch (error) {
+    if (error instanceof SchemaCensusError)
+      throw error;
+    const state2 = error instanceof SQL2.PostgresError ? error.errno : undefined;
+    const code = state2 === "42P01" || state2 === "42703" ? "CENSUS_SCHEMA_UNAVAILABLE" : state2 === "42501" ? "CENSUS_ACCESS_DENIED" : state2 === "25006" ? "CENSUS_WRITE_REFUSED" : state2 === "57014" || state2 === "55P03" ? "CENSUS_TIMEOUT" : ["08000", "08001", "08003", "08004", "08006", "08007", "08P01", "28000", "28P01", "57P03"].includes(state2 ?? "") ? "CENSUS_CONNECTION_FAILED" : "CENSUS_FAILED";
+    throw new SchemaCensusError(code);
+  } finally {
+    try {
+      await sql?.close({ timeout: 1 });
+    } catch {
+      throw new SchemaCensusError("CENSUS_FAILED");
+    }
+  }
+}
+
 // src/server/maintenance-entry.ts
 class InspectionInputError extends Error {
   code;
@@ -3999,6 +4133,14 @@ class InspectionInputError extends Error {
     this.code = code;
   }
 }
+
+class SchemaCensusInputError extends Error {
+  code;
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+}
 var MAX_MANIFEST_BYTES = 32 * 1024;
 function sha256(value) {
   return createHash3("sha256").update(value).digest("hex");
@@ -4109,6 +4251,41 @@ function readInspectionManifest(path, receiptPath) {
   }
   return parsed;
 }
+function readSchemaCensusManifest(path, receiptPath) {
+  let input;
+  let parsed;
+  try {
+    input = readBoundedJson(path);
+    const value = input.value;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw new Error;
+    const fields = ["app", "operation", "manifestVersion", "operationId", "stationId", "keyId", "orgId", "expiresAt", "manifestDigest"];
+    if (Object.keys(value).length !== fields.length || fields.some((field) => !Object.hasOwn(value, field)))
+      throw new Error;
+    if (value.app !== "skills" || value.operation !== "inspect-schema" || value.manifestVersion !== 1)
+      throw new Error;
+    for (const field of ["operationId", "stationId", "keyId", "orgId"]) {
+      const item = value[field];
+      if (typeof item !== "string" || item.trim().length === 0 || item.length > 256 || /[\u0000-\u001f\u007f]/.test(item))
+        throw new Error;
+    }
+    if (typeof value.expiresAt !== "string" || value.expiresAt.length > 64 || !Number.isFinite(Date.parse(value.expiresAt)) || Date.parse(value.expiresAt) <= Date.now())
+      throw new Error;
+    if (typeof value.manifestDigest !== "string" || !/^[a-f0-9]{64}$/.test(value.manifestDigest))
+      throw new Error;
+    if (sha256(canonical(value)) !== value.manifestDigest)
+      throw new Error;
+    parsed = value;
+  } catch {
+    throw new SchemaCensusInputError("INVALID_CENSUS_MANIFEST");
+  }
+  try {
+    verifyOperatorReceipt(input, readBoundedJson(receiptPath).value);
+  } catch {
+    throw new SchemaCensusInputError("INVALID_OPERATOR_RECEIPT");
+  }
+  return parsed;
+}
 function registerMaintenance(parent) {
   const maintenance = parent.command("maintenance").description("Run protected, metadata-only Skills maintenance operations");
   maintenance.command("inspect-enrollment").description("Inspect one enrollment with a database-enforced read-only snapshot").requiredOption("--manifest <path>", "Fresh inspection authorization supplied by the protected task wrapper").requiredOption("--operator-receipt <path>", "Verified actor receipt written by the protected task wrapper").option("--json", "Output a safe JSON receipt", false).action(async (options) => {
@@ -4133,6 +4310,26 @@ function registerMaintenance(parent) {
       process.exitCode = 1;
     }
   });
+  maintenance.command("inspect-schema").description("Census the fixed Skills schema and migration ledger with a database-enforced read-only snapshot").requiredOption("--manifest <path>", "Fresh census authorization supplied by the protected task wrapper").requiredOption("--operator-receipt <path>", "Verified actor receipt written by the protected task wrapper").option("--json", "Output a safe JSON receipt", false).action(async (options) => {
+    try {
+      const manifest = readSchemaCensusManifest(options.manifest, options.operatorReceipt);
+      const census = await inspectSchemaCensus(process.env.HASNA_SKILLS_DATABASE_URL ?? "");
+      console.log(JSON.stringify({
+        ...census,
+        operationId: manifest.operationId,
+        keyId: manifest.keyId,
+        orgId: manifest.orgId,
+        stationId: manifest.stationId
+      }));
+    } catch (error) {
+      const code = error instanceof SchemaCensusInputError || error instanceof SchemaCensusError ? error.code : "CENSUS_FAILED";
+      if (options.json || !process.stdout.isTTY)
+        console.log(JSON.stringify({ status: "failed", code }));
+      else
+        console.error(code);
+      process.exitCode = 1;
+    }
+  });
   maintenance.command("enroll-publish").requiredOption("--manifest <path>", "Bounded target manifest supplied by the protected task wrapper").requiredOption("--operator-receipt <path>", "Verified actor receipt written by the protected task wrapper").option("--apply", "Commit the bounded scope update; defaults to dry-run", false).option("--json", "Output a safe JSON receipt", false).action(async (options) => {
     let manifest;
     let store;
@@ -4167,7 +4364,7 @@ function registerMaintenance(parent) {
       process.exitCode = 1;
     } catch (error) {
       const message = error instanceof Error ? error.message : "";
-      const state2 = error instanceof SQL2.PostgresError ? error.errno : undefined;
+      const state2 = error instanceof SQL3.PostgresError ? error.errno : undefined;
       const code = state2 === "42P01" || state2 === "42703" ? "MAINTENANCE_SCHEMA_UNAVAILABLE" : state2 === "42501" ? "MAINTENANCE_ACCESS_DENIED" : state2 === "25006" ? "MAINTENANCE_WRITE_REFUSED" : state2 === "57014" || state2 === "55P03" ? "MAINTENANCE_TIMEOUT" : ["08000", "08001", "08003", "08004", "08006", "08007", "08P01", "28000", "28P01", "57P03"].includes(state2 ?? "") ? "MAINTENANCE_CONNECTION_FAILED" : message.includes("expired") || message.includes("expiry") ? "INVALID_EXPIRY" : message.includes("receipt") || message.includes("operator") ? "INVALID_OPERATOR_RECEIPT" : message.includes("manifest") || message.includes("input") ? "INVALID_MANIFEST" : message.includes("database") || message.includes("store") ? "STORE_UNAVAILABLE" : "MAINTENANCE_FAILED";
       if (options.json || !process.stdout.isTTY)
         console.log(JSON.stringify({ status: "failed", code }));