@absolutejs/vulnerabilities-witness 0.1.0 → 0.2.0

package/README.md

@@ -48,8 +48,9 @@ Bun.serve({ fetch, port: 3000 });
 The signing identity contains a private key and belongs in a durable secret
 broker, not PostgreSQL or source control. `service.rotate()` stores the new
 secret state before activating it and publishes the cross-signed transition in
-the registry. In a multi-replica service, the supplied secret-store integration
-must serialize rotations.
+the registry. `service.maintain()` performs the same rotation only after the
+configured maximum key age. In a multi-replica service, the supplied
+secret-store integration must serialize rotations.
 
 ## Standalone service
 
@@ -61,9 +62,33 @@ observations and accepts these deployment secrets:
 - `EVIDENCE_WITNESS_SIGNING_STATE_JSON`
 - `EVIDENCE_WITNESS_TOKENS_JSON`, an object mapping stable subjects to bearer
   tokens
+- `EVIDENCE_WITNESS_SECRETS_PATH`, the durable encrypted secret file
+- `EVIDENCE_WITNESS_SECRETS_PASSPHRASE`, the master passphrase kept outside the
+  file
+- `EVIDENCE_WITNESS_KEY_MAX_AGE_MS`, defaulting to 90 days
+- `EVIDENCE_WITNESS_MAINTENANCE_INTERVAL_MS`, defaulting to one hour
+
+The authenticated `GET /v1/status` endpoint reports the verified key registry
+and optional backup restoration evidence. Store
+`EVIDENCE_WITNESS_BACKUP_VERIFICATION_JSON` in the encrypted secret adapter
+after a drill has restored both the PostgreSQL artifact and encrypted signing
+state. The record must use the
+`absolutejs.vulnerability-evidence-witness-backup-verification/v1` contract,
+contain SHA-256 digests for both artifacts, and record both restoration times.
+
 - `PORT`, defaulting to `3000`
 
+The two JSON values bootstrap the encrypted file only when their entries do not
+already exist. Later key rotations are written atomically to the encrypted file
+before the new identity becomes active.
+
 Run independent instances under different administrative and infrastructure
 boundaries. Clients should pin each genesis witness key through an independent
 channel and require a quorum with
 `verifyEvidenceWitnessQuorum` from `@absolutejs/vulnerabilities`.
+
+The repository publishes a deployable container to
+`ghcr.io/absolutejs/vulnerabilities-witness`. See
+[`deploy/README.md`](deploy/README.md) for the independence requirements,
+bootstrap sequence, PAAS quorum configuration, and repeatable Admin drill
+workflow.

package/dist/index.js

@@ -114,6 +114,33 @@ var verifyEvidenceWitnessKeyRegistry = (input) => {
 
 // src/service.ts
 var EVIDENCE_WITNESS_REQUEST_CONTRACT = "absolutejs.vulnerability-evidence-witness-request/v1";
+var EVIDENCE_WITNESS_BACKUP_VERIFICATION_CONTRACT = "absolutejs.vulnerability-evidence-witness-backup-verification/v1";
+var EVIDENCE_WITNESS_STATUS_CONTRACT = "absolutejs.vulnerability-evidence-witness-status/v1";
+var timestamp = (value, label) => {
+  if (!Number.isFinite(Date.parse(value)))
+    throw new Error(`${label} is invalid`);
+  return value;
+};
+var digest = (value, label) => {
+  if (!/^sha256:[a-f0-9]{64}$/u.test(value))
+    throw new Error(`${label} is invalid`);
+  return value;
+};
+var parseEvidenceWitnessBackupVerification = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Evidence witness backup verification is invalid");
+  const input = value;
+  if (input.contract !== EVIDENCE_WITNESS_BACKUP_VERIFICATION_CONTRACT)
+    throw new Error("Evidence witness backup verification is unsupported");
+  return {
+    contract: input.contract,
+    databaseArtifactDigest: digest(input.databaseArtifactDigest ?? "", "Evidence witness database backup digest"),
+    databaseRestoredAt: timestamp(input.databaseRestoredAt ?? "", "Evidence witness database restore time"),
+    signingStateArtifactDigest: digest(input.signingStateArtifactDigest ?? "", "Evidence witness signing-state backup digest"),
+    signingStateRestoredAt: timestamp(input.signingStateRestoredAt ?? "", "Evidence witness signing-state restore time"),
+    verifiedAt: timestamp(input.verifiedAt ?? "", "Evidence witness backup verification time")
+  };
+};
 var createEvidenceWitnessService = (options) => {
   const origin = new URL(options.origin);
   if (origin.protocol !== "https:")
@@ -128,6 +155,12 @@ var createEvidenceWitnessService = (options) => {
     await refresh();
     return evidenceWitnessKeyRegistryFrom(state);
   };
+  const status = async () => ({
+    backup: options.loadBackupVerification ? await options.loadBackupVerification().then((value) => value === null ? null : parseEvidenceWitnessBackupVerification(value)) : null,
+    checkedAt: new Date().toISOString(),
+    contract: EVIDENCE_WITNESS_STATUS_CONTRACT,
+    registry: await registry()
+  });
   const checkpoint = async (subject, request) => {
     if (request.contract !== EVIDENCE_WITNESS_REQUEST_CONTRACT)
       throw new Error("Evidence witness request contract is unsupported");
@@ -152,7 +185,7 @@ var createEvidenceWitnessService = (options) => {
     });
     const observed = await options.store.observe({
       checkpoint: signed,
-      history: request.log.entries.map(({ digest }) => digest),
+      history: request.log.entries.map(({ digest: digest2 }) => digest2),
       subject: normalizedSubject
     });
     return {
@@ -175,7 +208,28 @@ var createEvidenceWitnessService = (options) => {
     });
     return queued;
   };
-  return { checkpoint, registry, rotate };
+  const maintain = (input) => {
+    if (!Number.isSafeInteger(input.maxKeyAgeMs) || input.maxKeyAgeMs < 1)
+      throw new Error("Evidence witness maximum key age is invalid");
+    const now = input.now ?? new Date;
+    const queued = mutationQueue.then(async () => {
+      await refresh();
+      const ageMs = now.getTime() - Date.parse(state.identity.createdAt);
+      if (ageMs < input.maxKeyAgeMs)
+        return evidenceWitnessKeyRegistryFrom(state);
+      const next = rotateEvidenceWitnessSigningState(state, now.toISOString());
+      await options.storeSigningState(encodeEvidenceWitnessSigningState(next));
+      state = next;
+      return evidenceWitnessKeyRegistryFrom(state);
+    });
+    mutationQueue = queued.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return queued;
+  };
+  return { checkpoint, maintain, registry, rotate, status };
 };
 
 // src/store.ts
@@ -248,6 +302,12 @@ var createEvidenceWitnessHttpHandler = (options) => async (request) => {
     return json({ status: "ok" });
   if (request.method === "GET" && url.pathname === "/v1/keys")
     return json(await options.service.registry());
+  if (request.method === "GET" && url.pathname === "/v1/status") {
+    const subject2 = await options.authenticate(bearer(request));
+    if (!subject2)
+      return json({ error: "unauthorized" }, 401);
+    return json(await options.service.status());
+  }
   if (request.method !== "POST" || url.pathname !== "/v1/checkpoints")
     return json({ error: "not_found" }, 404);
   const subject = await options.authenticate(bearer(request));
@@ -273,6 +333,7 @@ export {
   verifyEvidenceWitnessKeyRegistry,
   rotateEvidenceWitnessSigningState,
   parseEvidenceWitnessSigningState,
+  parseEvidenceWitnessBackupVerification,
   evidenceWitnessKeyRegistryFrom,
   encodeEvidenceWitnessSigningState,
   createMemoryEvidenceWitnessStore,
@@ -281,5 +342,7 @@ export {
   createEvidenceWitnessHttpHandler,
   EvidenceWitnessRollbackError,
   EvidenceWitnessEquivocationError,
-  EVIDENCE_WITNESS_REQUEST_CONTRACT
+  EVIDENCE_WITNESS_STATUS_CONTRACT,
+  EVIDENCE_WITNESS_REQUEST_CONTRACT,
+  EVIDENCE_WITNESS_BACKUP_VERIFICATION_CONTRACT
 };

package/dist/server.js

@@ -116,6 +116,33 @@ var verifyEvidenceWitnessKeyRegistry = (input) => {
 
 // src/service.ts
 var EVIDENCE_WITNESS_REQUEST_CONTRACT = "absolutejs.vulnerability-evidence-witness-request/v1";
+var EVIDENCE_WITNESS_BACKUP_VERIFICATION_CONTRACT = "absolutejs.vulnerability-evidence-witness-backup-verification/v1";
+var EVIDENCE_WITNESS_STATUS_CONTRACT = "absolutejs.vulnerability-evidence-witness-status/v1";
+var timestamp = (value, label) => {
+  if (!Number.isFinite(Date.parse(value)))
+    throw new Error(`${label} is invalid`);
+  return value;
+};
+var digest = (value, label) => {
+  if (!/^sha256:[a-f0-9]{64}$/u.test(value))
+    throw new Error(`${label} is invalid`);
+  return value;
+};
+var parseEvidenceWitnessBackupVerification = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Evidence witness backup verification is invalid");
+  const input = value;
+  if (input.contract !== EVIDENCE_WITNESS_BACKUP_VERIFICATION_CONTRACT)
+    throw new Error("Evidence witness backup verification is unsupported");
+  return {
+    contract: input.contract,
+    databaseArtifactDigest: digest(input.databaseArtifactDigest ?? "", "Evidence witness database backup digest"),
+    databaseRestoredAt: timestamp(input.databaseRestoredAt ?? "", "Evidence witness database restore time"),
+    signingStateArtifactDigest: digest(input.signingStateArtifactDigest ?? "", "Evidence witness signing-state backup digest"),
+    signingStateRestoredAt: timestamp(input.signingStateRestoredAt ?? "", "Evidence witness signing-state restore time"),
+    verifiedAt: timestamp(input.verifiedAt ?? "", "Evidence witness backup verification time")
+  };
+};
 var createEvidenceWitnessService = (options) => {
   const origin = new URL(options.origin);
   if (origin.protocol !== "https:")
@@ -130,6 +157,12 @@ var createEvidenceWitnessService = (options) => {
     await refresh();
     return evidenceWitnessKeyRegistryFrom(state);
   };
+  const status = async () => ({
+    backup: options.loadBackupVerification ? await options.loadBackupVerification().then((value) => value === null ? null : parseEvidenceWitnessBackupVerification(value)) : null,
+    checkedAt: new Date().toISOString(),
+    contract: EVIDENCE_WITNESS_STATUS_CONTRACT,
+    registry: await registry()
+  });
   const checkpoint = async (subject, request) => {
     if (request.contract !== EVIDENCE_WITNESS_REQUEST_CONTRACT)
       throw new Error("Evidence witness request contract is unsupported");
@@ -154,7 +187,7 @@ var createEvidenceWitnessService = (options) => {
     });
     const observed = await options.store.observe({
       checkpoint: signed,
-      history: request.log.entries.map(({ digest }) => digest),
+      history: request.log.entries.map(({ digest: digest2 }) => digest2),
       subject: normalizedSubject
     });
     return {
@@ -177,7 +210,28 @@ var createEvidenceWitnessService = (options) => {
     });
     return queued;
   };
-  return { checkpoint, registry, rotate };
+  const maintain = (input) => {
+    if (!Number.isSafeInteger(input.maxKeyAgeMs) || input.maxKeyAgeMs < 1)
+      throw new Error("Evidence witness maximum key age is invalid");
+    const now = input.now ?? new Date;
+    const queued = mutationQueue.then(async () => {
+      await refresh();
+      const ageMs = now.getTime() - Date.parse(state.identity.createdAt);
+      if (ageMs < input.maxKeyAgeMs)
+        return evidenceWitnessKeyRegistryFrom(state);
+      const next = rotateEvidenceWitnessSigningState(state, now.toISOString());
+      await options.storeSigningState(encodeEvidenceWitnessSigningState(next));
+      state = next;
+      return evidenceWitnessKeyRegistryFrom(state);
+    });
+    mutationQueue = queued.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return queued;
+  };
+  return { checkpoint, maintain, registry, rotate, status };
 };
 
 // src/store.ts
@@ -250,6 +304,12 @@ var createEvidenceWitnessHttpHandler = (options) => async (request) => {
     return json({ status: "ok" });
   if (request.method === "GET" && url.pathname === "/v1/keys")
     return json(await options.service.registry());
+  if (request.method === "GET" && url.pathname === "/v1/status") {
+    const subject2 = await options.authenticate(bearer(request));
+    if (!subject2)
+      return json({ error: "unauthorized" }, 401);
+    return json(await options.service.status());
+  }
   if (request.method !== "POST" || url.pathname !== "/v1/checkpoints")
     return json({ error: "not_found" }, 404);
   const subject = await options.authenticate(bearer(request));
@@ -345,25 +405,64 @@ var createPostgresEvidenceWitnessStore = (sql) => {
 
 // src/server.ts
 var {SQL } = globalThis.Bun;
+import { encryptedFileAdapter } from "@absolutejs/secrets/broker";
 var required = (name) => {
   const value = process.env[name]?.trim();
   if (!value)
     throw new Error(`Missing required environment: ${name}`);
   return value;
 };
+var positiveInteger = (name, fallback) => {
+  const encoded = process.env[name]?.trim();
+  if (!encoded)
+    return fallback;
+  const value = Number(encoded);
+  if (!Number.isSafeInteger(value) || value < 1)
+    throw new Error(`${name} must be a positive integer`);
+  return value;
+};
+var signingStateName = "EVIDENCE_WITNESS_SIGNING_STATE_JSON";
+var tokensName = "EVIDENCE_WITNESS_TOKENS_JSON";
+var backupVerificationName = "EVIDENCE_WITNESS_BACKUP_VERIFICATION_JSON";
+var masterPassphrase = required("EVIDENCE_WITNESS_SECRETS_PASSPHRASE");
+var secrets = encryptedFileAdapter({
+  key: { passphrase: masterPassphrase, type: "passphrase" },
+  path: required("EVIDENCE_WITNESS_SECRETS_PATH")
+});
+var loadOrBootstrap = async (name) => {
+  const stored = await secrets.fetch(name);
+  if (stored)
+    return stored;
+  const bootstrap = required(name);
+  if (!secrets.put)
+    throw new Error("Encrypted secret adapter is read-only");
+  await secrets.put(name, bootstrap);
+  return bootstrap;
+};
 var database = new SQL(required("DATABASE_URL"));
 await ensurePostgresEvidenceWitnessSchema(database);
-var encodedSigningState = required("EVIDENCE_WITNESS_SIGNING_STATE_JSON");
+var encodedSigningState = await loadOrBootstrap(signingStateName);
 var signingState = parseEvidenceWitnessSigningState(JSON.parse(encodedSigningState));
-var tokens = JSON.parse(required("EVIDENCE_WITNESS_TOKENS_JSON"));
+var tokens = JSON.parse(await loadOrBootstrap(tokensName));
 var subjectsByToken = new Map(Object.entries(tokens).map(([subject, token]) => [token, subject]));
 var service2 = createEvidenceWitnessService({
-  loadSigningState: async () => encodedSigningState,
+  loadBackupVerification: async () => {
+    const encoded = await secrets.fetch(backupVerificationName);
+    return encoded ? JSON.parse(encoded) : null;
+  },
+  loadSigningState: async () => {
+    const encoded = await secrets.fetch(signingStateName);
+    if (!encoded)
+      throw new Error("Evidence witness signing state is missing");
+    return encoded;
+  },
   origin: required("EVIDENCE_WITNESS_ORIGIN"),
   signingState,
   store: createPostgresEvidenceWitnessStore(database),
-  storeSigningState: async () => {
-    throw new Error("Server-managed key rotation requires a durable secret-store integration");
+  storeSigningState: async (encoded) => {
+    if (!secrets.put)
+      throw new Error("Encrypted secret adapter is read-only");
+    await secrets.put(signingStateName, encoded);
   }
 });
 var handler = createEvidenceWitnessHttpHandler({
@@ -374,3 +473,10 @@ var port = Number(process.env.PORT ?? "3000");
 if (!Number.isSafeInteger(port) || port < 1 || port > 65535)
   throw new Error("PORT must be a valid TCP port");
 Bun.serve({ fetch: handler, port });
+var dayMs = 86400000;
+var maxKeyAgeMs = positiveInteger("EVIDENCE_WITNESS_KEY_MAX_AGE_MS", 90 * dayMs);
+var maintenanceIntervalMs = positiveInteger("EVIDENCE_WITNESS_MAINTENANCE_INTERVAL_MS", 3600000);
+var maintain = () => service2.maintain({ maxKeyAgeMs }).catch((error) => console.error("Evidence witness key maintenance failed", error));
+var maintenanceTimer = setInterval(() => void maintain(), maintenanceIntervalMs);
+maintenanceTimer.unref();
+maintain();

package/dist/service.d.ts

@@ -10,7 +10,25 @@ export type EvidenceWitnessResponse = {
     checkpoint: Awaited<ReturnType<EvidenceWitnessStore["observe"]>>["checkpoint"];
     registry: EvidenceWitnessKeyRegistry;
 };
+export declare const EVIDENCE_WITNESS_BACKUP_VERIFICATION_CONTRACT: "absolutejs.vulnerability-evidence-witness-backup-verification/v1";
+export declare const EVIDENCE_WITNESS_STATUS_CONTRACT: "absolutejs.vulnerability-evidence-witness-status/v1";
+export type EvidenceWitnessBackupVerification = {
+    contract: typeof EVIDENCE_WITNESS_BACKUP_VERIFICATION_CONTRACT;
+    databaseArtifactDigest: `sha256:${string}`;
+    databaseRestoredAt: string;
+    signingStateArtifactDigest: `sha256:${string}`;
+    signingStateRestoredAt: string;
+    verifiedAt: string;
+};
+export type EvidenceWitnessStatus = {
+    backup: EvidenceWitnessBackupVerification | null;
+    checkedAt: string;
+    contract: typeof EVIDENCE_WITNESS_STATUS_CONTRACT;
+    registry: EvidenceWitnessKeyRegistry;
+};
+export declare const parseEvidenceWitnessBackupVerification: (value: unknown) => EvidenceWitnessBackupVerification;
 export declare const createEvidenceWitnessService: (options: {
+    loadBackupVerification?: () => Promise<unknown | null>;
     loadSigningState: () => Promise<string>;
     origin: string;
     signingState: EvidenceWitnessSigningState;
@@ -18,6 +36,11 @@ export declare const createEvidenceWitnessService: (options: {
     storeSigningState: (encoded: string) => Promise<void>;
 }) => {
     checkpoint: (subject: string, request: EvidenceWitnessRequest) => Promise<EvidenceWitnessResponse>;
+    maintain: (input: {
+        maxKeyAgeMs: number;
+        now?: Date;
+    }) => Promise<EvidenceWitnessKeyRegistry>;
     registry: () => Promise<EvidenceWitnessKeyRegistry>;
     rotate: (rotatedAt?: string) => Promise<EvidenceWitnessKeyRegistry>;
+    status: () => Promise<EvidenceWitnessStatus>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/vulnerabilities-witness",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Independent durable transparency witness with rollback, equivocation, key-rotation, and HTTP service primitives for AbsoluteJS vulnerability evidence.",
   "type": "module",
   "license": "BSL-1.1",
@@ -48,7 +48,7 @@
     "format": "prettier --write \"./**/*.{ts,json,md}\"",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "build": "rm -rf dist && bun build --root src src/index.ts src/postgres.ts src/server.ts src/manifest.ts --outdir dist --target=bun --external @absolutejs/manifest --external @absolutejs/vulnerabilities --external @sinclair/typebox && tsc -p tsconfig.build.json && absolute-manifest emit",
+    "build": "rm -rf dist && bun build --root src src/index.ts src/postgres.ts src/server.ts src/manifest.ts --outdir dist --target=bun --external @absolutejs/manifest --external @absolutejs/secrets --external @absolutejs/vulnerabilities --external @sinclair/typebox && tsc -p tsconfig.build.json && absolute-manifest emit",
     "check:package": "bun run format && bun run typecheck && bun run test && bun run build"
   },
   "keywords": [
@@ -61,7 +61,8 @@
   ],
   "dependencies": {
     "@absolutejs/manifest": "0.3.0",
-    "@absolutejs/vulnerabilities": "0.13.0",
+    "@absolutejs/secrets": "0.7.2",
+    "@absolutejs/vulnerabilities": "0.14.0",
     "@sinclair/typebox": "0.34.52"
   },
   "devDependencies": {