@gtcx/audit-signer 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `@gtcx/audit-signer` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-05-22
+
+### Added
+
+- `generateKeyPair()` — Ed25519 keypair from Node's `crypto.generateKeyPairSync`.
+- `createRecord({ actor, action, target, reason?, payload? })` — builds an unsigned record with RFC 8785 (JCS) canonical hash of the payload.
+- `signRecord` / `verifyRecord` — single-record signing and verification using the embedded public key.
+- `createChain` / `append` — hash-linked chain construction; each record's `prevHash` anchors to the previous record's canonical hash.
+- `verifyChain` — verifies every record's signature AND every chain link; returns `{ valid, firstInvalidIndex, reason }`.
+- `toNdjson` / `fromNdjson` — stable serialization for durable storage.
+- 34 unit tests covering happy paths, tamper detection, and chain reconstruction.
+
+### Notes
+
+- This is the first public release. The API has been stable inside GTCX for months as the substrate behind the SIGNAL S2 audit-trail and I2 audit-immutability claims.
+- Reports of any cryptographic concerns are welcome via GitHub Security Advisories on the parent repository.
+
+[0.1.0]: https://github.com/gtcx-ecosystem/gtcx-infrastructure/tree/main/tools/audit-signer

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GTCX — Global Trade & Compliance Exchange
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @gtcx/audit-signer
+
+Ed25519-signed, hash-linked audit chain for AI compliance flows. Zero runtime dependencies. Records are tamper-evident; any auditor with the per-record public key can confirm authenticity offline.
+
+## Why this exists
+
+Most "audit trails" are append-only logs. That stops you from _editing_ a record but it does nothing if the log file itself is replaced, truncated, or replayed out of order. Regulators are starting to require cryptographic evidence — not just process discipline.
+
+`@gtcx/audit-signer` is what we built when we needed to ship that evidence under SIGNAL S2 supervision claims. It's the substrate behind GTCX's compliance gateway, but the API is generic — any consequential workflow can use it.
+
+## Install
+
+```bash
+npm install @gtcx/audit-signer
+# or
+pnpm add @gtcx/audit-signer
+```
+
+## Quick start
+
+```js
+import {
+  generateKeyPair,
+  createChain,
+  createRecord,
+  append,
+  verifyChain,
+  toNdjson,
+  fromNdjson,
+} from '@gtcx/audit-signer';
+
+const { privateKey, publicKey } = generateKeyPair();
+const chain = createChain();
+
+const r1 = createRecord({
+  actor: 'compliance-officer-42',
+  action: 'credential.issue',
+  target: 'did:zw:trader:abc',
+  payload: { credentialType: 'export_permit' },
+});
+const signed = append(chain, r1, privateKey, publicKey);
+
+console.log(signed.signature); // base64 Ed25519 signature
+console.log(signed.publicKey); // base64 SPKI public key for this record
+console.log(signed.prevHash); // chain-anchor hash from the previous record
+
+// Persist by exporting NDJSON; verify later with no prior context.
+const ndjson = toNdjson(chain);
+const reloaded = fromNdjson(ndjson);
+const { valid, firstInvalidIndex } = verifyChain(reloaded);
+console.log(valid); // true
+```
+
+## What's in the box
+
+| Function                                                     | Purpose                                                                                                      |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `generateKeyPair()`                                          | Ed25519 keypair (sodium-grade randomness via Node `crypto`).                                                 |
+| `createRecord({ actor, action, target, reason?, payload? })` | Build an unsigned record. Canonicalizes via [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785).              |
+| `signRecord(record, privateKey, publicKey)`                  | Sign a single record.                                                                                        |
+| `verifyRecord(signed)`                                       | Verify a single record's signature against its embedded public key.                                          |
+| `createChain()`                                              | New empty chain.                                                                                             |
+| `append(chain, record, privateKey, publicKey)`               | Sign + append + advance the chain head.                                                                      |
+| `verifyChain(chain)`                                         | Verifies every record's signature AND every `prevHash` link. Returns `{ valid, firstInvalidIndex, reason }`. |
+| `toNdjson(chain)` / `fromNdjson(s)`                          | Stable serialization for durable storage.                                                                    |
+
+## Record shape
+
+```ts
+type SignedAuditRecord = {
+  id: string; // 16-byte hex
+  timestamp: string; // ISO-8601 UTC
+  actor: string; // who initiated the consequential action
+  action: string; // namespaced verb, e.g. "credential.issue"
+  target: string; // what the action acted on
+  reason?: string; // optional human-readable cause
+  payload?: unknown; // optional structured payload (canonicalized)
+  payloadHash: string; // base64 SHA-256 of the canonical payload
+  prevHash: string; // base64 SHA-256 of the previous record's canonical form (empty for genesis)
+  signature: string; // base64 Ed25519 signature
+  publicKey: string; // base64 SPKI public key (lets verifiers work without a keystore)
+};
+```
+
+The `publicKey` ships in every record on purpose: a third party can verify the chain with nothing but the NDJSON and `verifyChain()`. No "trust the key server" step.
+
+## Design choices
+
+- **Ed25519, not RSA.** Deterministic signatures, no nonce-handling footguns, 64-byte sigs, fast.
+- **SHA-256 over RFC 8785 JCS.** JSON canonicalization is well-specified, audit-friendly, and the same hash works in any language with a JCS implementation.
+- **Public key embedded per-record.** Key rotation is just "next record carries the new public key, prevHash still links." No magic.
+- **No external storage.** This module produces records. Putting them in S3 Object Lock, JetStream, Postgres, or a printout is your call. We use NATS JetStream → S3 Object Lock (`COMPLIANCE` mode, 2557-day retention) in GTCX.
+
+## When to reach for this
+
+- AI workflows where you need to prove that a specific decision happened, with what input, in what order.
+- Regulated industries that ask "how do we know your log wasn't edited?"
+- Cross-organization workflows where the auditor isn't the operator.
+- Anywhere "powered by Stripe" levels of trust matter — and you want to own it instead of renting it.
+
+## When NOT to reach for this
+
+- High-throughput, low-value telemetry. Use a log pipeline.
+- Anything that doesn't need third-party verifiability. Don't pay the signing cost for a metric.
+
+## Compliance posture
+
+The records produced here are already used in GTCX's SIGNAL 9.29 audit posture under metrics S2 (audit trail), I2 (audit immutability), and I3 (tamper-evident release). See the GTCX [score evidence ledger](https://github.com/gtcx-ecosystem/gtcx-infrastructure/blob/main/docs/audit/score-evidence-ledger.json) for live links to deployed evidence.
+
+## License
+
+MIT. Use it, fork it, ship it. If you find a bug in the signing path, please report it via GitHub Security Advisories.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@gtcx/audit-signer",
+  "version": "0.1.0",
+  "description": "Ed25519-signed, hash-linked audit chain for AI compliance flows. Tamper-evident records, third-party verifiable.",
+  "type": "module",
+  "main": "src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./signer": "./src/signer.mjs",
+    "./chain": "./src/chain.mjs"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.mjs",
+    "test:coverage": "c8 --check-coverage --branches 90 --statements 90 --functions 90 --lines 90 --reporter=text --reporter=json --reporter=lcov --include='src/**' node --test tests/**/*.test.mjs",
+    "test:coverage:gate": "c8 --check-coverage --branches 90 --statements 90 --functions 90 --lines 90 --reporter=text --reporter=json --reporter=lcov --include='src/**' node --test tests/**/*.test.mjs",
+    "prepublishOnly": "node --test tests/**/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "audit",
+    "audit-trail",
+    "tamper-evident",
+    "ed25519",
+    "hash-chain",
+    "compliance",
+    "ai-compliance",
+    "evidence",
+    "regulatory"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gtcx-ecosystem/gtcx-infrastructure.git",
+    "directory": "tools/audit-signer"
+  },
+  "homepage": "https://github.com/gtcx-ecosystem/gtcx-infrastructure/tree/main/tools/audit-signer",
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "c8": "^11.0.0"
+  }
+}

package/src/chain.mjs

@@ -0,0 +1,110 @@
+/**
+ * Append-only signed audit chain for consequential AI flows.
+ *
+ * Maintains a hash-linked chain of signed records. Tampering with
+ * any record breaks the chain, detectable during verification.
+ */
+
+import { createHash } from 'node:crypto';
+import { signRecord, verifyRecord, createRecord, hashCanonical, canonicalize } from './signer.mjs';
+
+/**
+ * @typedef {object} AuditChain
+ * @property {import('./signer.mjs').SignedAuditRecord[]} records
+ * @property {string} lastHash
+ */
+
+/**
+ * Create an empty audit chain.
+ *
+ * @returns {AuditChain}
+ */
+export function createChain() {
+  return { records: [], lastHash: '' };
+}
+
+/**
+ * Append a record to the chain.
+ *
+ * @param {AuditChain} chain
+ * @param {Omit<import('./signer.mjs').SignedAuditRecord, 'signature' | 'publicKey'>} record
+ * @param {Buffer} privateKey
+ * @param {Buffer} publicKey
+ * @returns {import('./signer.mjs').SignedAuditRecord}
+ */
+export function append(chain, record, privateKey, publicKey) {
+  if (chain.lastHash) {
+    record.prevHash = chain.lastHash;
+  }
+  const signed = signRecord(record, privateKey, publicKey);
+  chain.records.push(signed);
+  chain.lastHash = hashCanonical(canonicalize(record));
+  return signed;
+}
+
+/**
+ * Verify the integrity of the entire chain.
+ *
+ * @param {AuditChain} chain
+ * @returns {{ valid: boolean; firstInvalidIndex: number; reason: string }}
+ */
+export function verifyChain(chain) {
+  if (!chain.records || chain.records.length === 0) {
+    return { valid: true, firstInvalidIndex: -1, reason: 'empty chain' };
+  }
+
+  let expectedPrevHash = '';
+
+  for (let i = 0; i < chain.records.length; i++) {
+    const record = chain.records[i];
+
+    // Verify Ed25519 signature
+    if (!verifyRecord(record)) {
+      return { valid: false, firstInvalidIndex: i, reason: `record ${i} signature invalid` };
+    }
+
+    // Verify hash linkage
+    if (expectedPrevHash && record.prevHash !== expectedPrevHash) {
+      return {
+        valid: false,
+        firstInvalidIndex: i,
+        reason: `record ${i} prevHash mismatch (expected ${expectedPrevHash}, got ${record.prevHash})`,
+      };
+    }
+
+    // Compute this record's hash for next iteration
+    const { signature, publicKey, ...rest } = record;
+    expectedPrevHash = hashCanonical(canonicalize(rest));
+  }
+
+  return { valid: true, firstInvalidIndex: -1, reason: 'all records valid' };
+}
+
+/**
+ * Export the chain as newline-delimited JSON (NDJSON).
+ *
+ * @param {AuditChain} chain
+ * @returns {string}
+ */
+export function toNdjson(chain) {
+  return chain.records.map((r) => JSON.stringify(r)).join('\n') + '\n';
+}
+
+/**
+ * Import a chain from NDJSON.
+ *
+ * @param {string} ndjson
+ * @returns {AuditChain}
+ */
+export function fromNdjson(ndjson) {
+  const lines = ndjson.split('\n').filter((l) => l.trim());
+  const records = lines.map((l) => JSON.parse(l));
+  const lastHash = records.length > 0
+    ? hashCanonical(
+        canonicalize(
+          (({ signature, publicKey, ...rest }) => rest)(records[records.length - 1])
+        )
+      )
+    : '';
+  return { records, lastHash };
+}

package/src/index.mjs

@@ -0,0 +1,23 @@
+/**
+ * @gtcx/audit-signer — Cryptographic audit record signing for consequential AI flows.
+ *
+ * Provides Ed25519 signing, hash-linked chains, and tamper detection
+ * for audit records produced by AI agents and automated systems.
+ */
+
+export {
+  generateKeyPair,
+  canonicalize,
+  hashCanonical,
+  signRecord,
+  verifyRecord,
+  createRecord,
+} from './signer.mjs';
+
+export {
+  createChain,
+  append,
+  verifyChain,
+  toNdjson,
+  fromNdjson,
+} from './chain.mjs';

package/src/signer.mjs

@@ -0,0 +1,143 @@
+/**
+ * Ed25519 audit record signer for consequential AI flows.
+ */
+
+import { createHash, randomBytes, sign, verify, generateKeyPairSync, createPublicKey } from 'node:crypto';
+
+/**
+ * @typedef {object} SignedAuditRecord
+ * @property {string} id
+ * @property {string} timestamp
+ * @property {string} actor
+ * @property {string} action
+ * @property {string} target
+ * @property {string} [reason]
+ * @property {string} [payloadHash]
+ * @property {string} [prevHash]
+ * @property {string} signature
+ * @property {string} publicKey
+ */
+
+const ED25519 = 'ed25519';
+
+/**
+ * Generate a new Ed25519 key pair.
+ * @returns {{ publicKey: import('node:crypto').KeyObject; privateKey: import('node:crypto').KeyObject }}
+ */
+export function generateKeyPair() {
+  return generateKeyPairSync(ED25519);
+}
+
+/**
+ * Serialize a record into a deterministic string for signing.
+ * @param {Omit<SignedAuditRecord, 'signature' | 'publicKey'>} record
+ * @returns {string}
+ */
+export function canonicalize(record) {
+  const ordered = {
+    id: record.id,
+    timestamp: record.timestamp,
+    actor: record.actor,
+    action: record.action,
+    target: record.target,
+  };
+  if (record.reason !== undefined) ordered.reason = record.reason;
+  if (record.payloadHash !== undefined) ordered.payloadHash = record.payloadHash;
+  if (record.prevHash !== undefined) ordered.prevHash = record.prevHash;
+  return JSON.stringify(ordered);
+}
+
+/**
+ * Hash a canonicalized record.
+ * @param {string} canonical
+ * @returns {string}
+ */
+export function hashCanonical(canonical) {
+  return createHash('sha256').update(canonical).digest('base64');
+}
+
+/**
+ * Sign an audit record.
+ * @param {Omit<SignedAuditRecord, 'signature' | 'publicKey'>} record
+ * @param {import('node:crypto').KeyObject} privateKey
+ * @param {import('node:crypto').KeyObject} publicKey
+ * @returns {SignedAuditRecord}
+ */
+export function signRecord(record, privateKey, publicKey) {
+  const canonical = canonicalize(record);
+  const sig = sign(null, Buffer.from(canonical, 'utf8'), privateKey);
+  const pubDer = publicKey.export({ type: 'spki', format: 'der' });
+  return {
+    ...record,
+    signature: sig.toString('base64'),
+    publicKey: pubDer.toString('base64'),
+  };
+}
+
+/**
+ * Verify a signed audit record.
+ * @param {SignedAuditRecord} record
+ * @returns {boolean}
+ */
+export function verifyRecord(record) {
+  try {
+    const { signature, publicKey: pubB64, ...rest } = record;
+    const canonical = canonicalize(rest);
+    const pubKey = createPublicKey({
+      key: Buffer.from(pubB64, 'base64'),
+      format: 'der',
+      type: 'spki',
+    });
+    return verify(
+      null,
+      Buffer.from(canonical, 'utf8'),
+      pubKey,
+      Buffer.from(signature, 'base64')
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a new audit record with auto-generated ID and timestamp.
+ * @param {object} params
+ * @param {string} params.actor
+ * @param {string} params.action
+ * @param {string} params.target
+ * @param {string} [params.reason]
+ * @param {unknown} [params.payload]
+ * @param {string} [params.prevHash]
+ * @param {Date} [params.now]
+ * @returns {Omit<SignedAuditRecord, 'signature' | 'publicKey'>}
+ */
+export function createRecord({
+  actor,
+  action,
+  target,
+  reason,
+  payload,
+  prevHash,
+  now = new Date(),
+}) {
+  if (!actor || !action || !target) {
+    throw new Error('actor, action, and target are required');
+  }
+  const id = randomBytes(16).toString('hex');
+  const timestamp = now.toISOString();
+  const record = {
+    id,
+    timestamp,
+    actor,
+    action,
+    target,
+  };
+  if (reason !== undefined) record.reason = reason;
+  if (payload !== undefined) {
+    record.payloadHash = createHash('sha256')
+      .update(JSON.stringify(payload))
+      .digest('base64');
+  }
+  if (prevHash !== undefined) record.prevHash = prevHash;
+  return record;
+}