Compare commits

..

1 Commits

Author SHA1 Message Date
Devin
d6d74f2267 Add boot-time env assertions + fix ci.yml for post-webapp layout
Some checks failed
CI / Portal Lint (pull_request) Failing after 33s
CI / Portal Type Check (pull_request) Successful in 57s
CI / Portal Build (pull_request) Failing after 33s
CI / Orchestrator Type Check (pull_request) Failing after 5s
CI / Orchestrator Build (pull_request) Failing after 5s
CI / Orchestrator Test (pull_request) Failing after 5s
CI / Contracts Compile (pull_request) Failing after 12s
CI / Contracts Test (pull_request) Failing after 7s
Code Quality / SonarQube Analysis (pull_request) Failing after 20s
Code Quality / Code Quality Checks (pull_request) Failing after 5s
Security Scan / Dependency Vulnerability Scan (pull_request) Failing after 4s
Security Scan / OWASP ZAP Scan (pull_request) Failing after 4s
Closes gap-analysis v2 §8.1 / §8.4 / §8.6 and §10.1 / §10.2.

- assertProductionEnv() in config/env.ts fails-fast in NODE_ENV=production
  when SESSION_SECRET / EVENT_BUS_HMAC_SECRET / CHAIN_138_RPC_URL /
  NOTARY_REGISTRY_ADDRESS / ORCHESTRATOR_PRIVATE_KEY / DATABASE_URL is
  missing or uses the dev placeholder. Catches the silent-degrade-to-mock
  failure mode that would turn the Ledger Anchor back into a lie.
- New EVENT_BUS_HMAC_SECRET env added to the schema.
- .github/workflows/ci.yml rewritten: portal jobs target repo root (not
  the removed webapp/ gitlink), orchestrator type-check + test job
  added, contracts jobs kept as-is.
- 7 unit tests for assertProductionEnv; full suite 87/87 green.
2026-04-22 18:06:08 +00:00
6 changed files with 287 additions and 228 deletions

View File

@@ -7,139 +7,132 @@ on:
branches: [main, develop]
jobs:
# Frontend CI
frontend-lint:
name: Frontend Lint
# -------------------------------------------------------------------------
# Portal (Vite + React, lives at repo root after the webapp/ gitlink was
# removed in PR #4)
# -------------------------------------------------------------------------
portal-lint:
name: Portal Lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v6
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "18"
node-version: "20"
cache: "npm"
cache-dependency-path: webapp/package-lock.json
- name: Install dependencies
working-directory: webapp
run: npm ci
- name: Lint
working-directory: webapp
run: npm run lint
- run: npm ci
- run: npm run lint
frontend-type-check:
name: Frontend Type Check
portal-type-check:
name: Portal Type Check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v6
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "18"
node-version: "20"
cache: "npm"
cache-dependency-path: webapp/package-lock.json
- name: Install dependencies
working-directory: webapp
run: npm ci
- name: Type check
working-directory: webapp
run: npx tsc --noEmit
- run: npm ci
- run: npx tsc --noEmit
frontend-build:
name: Frontend Build
portal-build:
name: Portal Build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v6
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "18"
node-version: "20"
cache: "npm"
cache-dependency-path: webapp/package-lock.json
- name: Install dependencies
working-directory: webapp
run: npm ci
- name: Build
working-directory: webapp
run: npm run build
- name: Upload build artifacts
uses: actions/upload-artifact@v4
- run: npm ci
- run: npm run build
- uses: actions/upload-artifact@v4
with:
name: frontend-build
path: webapp/.next
name: portal-dist
path: dist
frontend-e2e:
name: Frontend E2E Tests
# -------------------------------------------------------------------------
# Orchestrator (TypeScript + Express + Jest)
# -------------------------------------------------------------------------
orchestrator-type-check:
name: Orchestrator Type Check
runs-on: ubuntu-latest
defaults:
run:
working-directory: orchestrator
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v6
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "18"
node-version: "20"
cache: "npm"
cache-dependency-path: webapp/package-lock.json
- name: Install dependencies
working-directory: webapp
run: npm ci
- name: Install Playwright
working-directory: webapp
run: npx playwright install --with-deps
- name: Run E2E tests
working-directory: webapp
run: npm run test:e2e
- name: Upload test results
uses: actions/upload-artifact@v4
if: always()
with:
name: playwright-report
path: webapp/playwright-report/
cache-dependency-path: orchestrator/package-lock.json
- run: npm ci
- run: npx tsc --noEmit
# Orchestrator CI
orchestrator-build:
name: Orchestrator Build
runs-on: ubuntu-latest
defaults:
run:
working-directory: orchestrator
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v6
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "18"
node-version: "20"
cache: "npm"
cache-dependency-path: orchestrator/package-lock.json
- name: Install dependencies
working-directory: orchestrator
run: npm ci
- name: Build
working-directory: orchestrator
run: npm run build
- run: npm ci
- run: npm run build
# Smart Contracts CI
orchestrator-test:
name: Orchestrator Test
runs-on: ubuntu-latest
defaults:
run:
working-directory: orchestrator
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
cache-dependency-path: orchestrator/package-lock.json
- run: npm ci
- run: npm test -- --ci
# -------------------------------------------------------------------------
# Smart Contracts (Hardhat)
# -------------------------------------------------------------------------
contracts-compile:
name: Contracts Compile
runs-on: ubuntu-latest
defaults:
run:
working-directory: contracts
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v6
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "18"
node-version: "20"
cache: "npm"
cache-dependency-path: contracts/package-lock.json
- name: Install dependencies
working-directory: contracts
run: npm ci
- name: Compile contracts
working-directory: contracts
run: npm run compile
- run: npm ci
- run: npm run compile
contracts-test:
name: Contracts Test
runs-on: ubuntu-latest
defaults:
run:
working-directory: contracts
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v6
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "18"
node-version: "20"
cache: "npm"
cache-dependency-path: contracts/package-lock.json
- name: Install dependencies
working-directory: contracts
run: npm ci
- name: Run tests
working-directory: contracts
run: npm run test
- run: npm ci
- run: npm run test

View File

@@ -22,6 +22,10 @@ const envSchema = z.object({
CHAIN_138_CHAIN_ID: z.string().regex(/^\d+$/).optional(),
NOTARY_REGISTRY_ADDRESS: z.string().regex(/^0x[0-9a-fA-F]{40}$/).optional(),
ORCHESTRATOR_PRIVATE_KEY: z.string().regex(/^0x[0-9a-fA-F]{64}$/).optional(),
// Event bus signing (arch §7 + §13 non-repudiation). Defaults to a
// dev placeholder; boot-time assertion refuses this placeholder in
// NODE_ENV=production.
EVENT_BUS_HMAC_SECRET: z.string().min(32).optional(),
});
/**
@@ -44,8 +48,78 @@ export const env = envSchema.parse({
CHAIN_138_CHAIN_ID: process.env.CHAIN_138_CHAIN_ID,
NOTARY_REGISTRY_ADDRESS: process.env.NOTARY_REGISTRY_ADDRESS,
ORCHESTRATOR_PRIVATE_KEY: process.env.ORCHESTRATOR_PRIVATE_KEY,
EVENT_BUS_HMAC_SECRET: process.env.EVENT_BUS_HMAC_SECRET,
});
/**
* Dev-mode placeholders that must never be used in NODE_ENV=production.
* Kept in sync with the `||` / `??` fallbacks sprinkled through the
* codebase (env.ts, eventBus.ts, …) — if those placeholders change,
* update this list too.
*/
const DEV_PLACEHOLDERS: readonly string[] = [
"dev-secret-change-in-production-min-32-chars",
"dev-event-bus-secret-change-in-production",
];
/**
* Boot-time assertion (arch §13 + gap-analysis v2 §8.1 / §8.4).
*
* Catches the silent-degrade failure mode where a production deployment
* is missing one of the critical envs and ends up:
* - using the dev placeholder for SESSION_SECRET / EVENT_BUS_HMAC_SECRET
* (no non-repudiation), or
* - writing tamper-evident anchors only to the mock notary
* (NotaryRegistry envs absent — Ledger Anchor is a lie again).
*
* Fails fast with process.exit(1) when NODE_ENV=production and any of
* these conditions hold. Called from src/index.ts on startup.
*/
export function assertProductionEnv(): void {
if ((process.env.NODE_ENV ?? "development") !== "production") return;
const failures: string[] = [];
const sessionSecret = process.env.SESSION_SECRET ?? "";
if (!sessionSecret || DEV_PLACEHOLDERS.includes(sessionSecret)) {
failures.push("SESSION_SECRET is unset or using the dev placeholder");
}
const eventSecret =
process.env.EVENT_BUS_HMAC_SECRET ?? process.env.SESSION_SECRET ?? "";
if (!eventSecret || DEV_PLACEHOLDERS.includes(eventSecret)) {
failures.push(
"EVENT_BUS_HMAC_SECRET is unset or using the dev placeholder — " +
"events would be signed with a known key (arch §7)",
);
}
const notaryEnvs = [
["CHAIN_138_RPC_URL", process.env.CHAIN_138_RPC_URL],
["NOTARY_REGISTRY_ADDRESS", process.env.NOTARY_REGISTRY_ADDRESS],
["ORCHESTRATOR_PRIVATE_KEY", process.env.ORCHESTRATOR_PRIVATE_KEY],
] as const;
const missingNotary = notaryEnvs.filter(([, v]) => !v).map(([k]) => k);
if (missingNotary.length > 0) {
failures.push(
`NotaryRegistry anchor would degrade to mock — missing: ${missingNotary.join(", ")} (arch §4.5)`,
);
}
if (!process.env.DATABASE_URL) {
failures.push("DATABASE_URL is required in production");
}
if (failures.length > 0) {
console.error("❌ Production boot-time env assertions failed:");
failures.forEach((f) => console.error(` - ${f}`));
console.error(
"Set the missing envs or run with NODE_ENV=development for the mock/dev fallback path.",
);
process.exit(1);
}
}
/**
* Validate environment on startup
*/

View File

@@ -1,7 +1,7 @@
import "dotenv/config";
import express from "express";
import cors from "cors";
import { validateEnv } from "./config/env";
import { validateEnv, assertProductionEnv } from "./config/env";
import {
apiLimiter,
securityHeaders,
@@ -22,6 +22,7 @@ import { runMigration } from "./db/migrations";
// Validate environment on startup
validateEnv();
assertProductionEnv();
const app = express();
const PORT = process.env.PORT || 8080;

View File

@@ -85,63 +85,3 @@ export const ROLE_FOR_TRANSITION: Readonly<Record<string, ActorRole>> = {
"VALIDATING->COMMITTED": "approver",
"ABORTED->UNWIND_PENDING": "exception_manager",
};
/**
* Per-state phase timeouts (arch §12.1 timing exceptions, gap v2 §7.6 / §10.7).
*
* Each state has its own watchdog: if a plan sits in `state` for longer than
* `PHASE_TIMEOUTS[state]` ms, the exception manager raises a timing exception
* from arch §12.1 and transitions the plan toward ABORTED (or whatever the
* policy dictates for that state).
*
* Terminal states (COMMITTED → CLOSED path; CLOSED) have no timeout — they
* are end-of-lifecycle and not supposed to be aged out.
*
* Values are defaults. Each entry can be individually overridden via env:
* PHASE_TIMEOUT_<STATE>=<ms>
* e.g. PHASE_TIMEOUT_EXECUTING=180000. Unit: milliseconds.
*
* Rationale for defaults:
* DRAFT — long; plans can sit in draft for days.
* INITIATED — short; identity + terms hashing is deterministic.
* PRECONDITIONS_PENDING — long; human KYC / control approvals.
* READY_FOR_PREPARE — short; just awaits programmatic prepare.
* PREPARED — medium; both legs confirm readiness.
* EXECUTING — medium; dispatch timeouts from arch §12.1.
* PARTIALLY_EXECUTED — medium; waits for the lagging leg.
* VALIDATING — medium; reconciliation + ack/settle evidence.
* ABORTED — short; decision of unwind-vs-close should be prompt.
* UNWIND_PENDING — long; recovery procedures can be slow/manual.
*/
export const DEFAULT_PHASE_TIMEOUTS: Readonly<Record<TransactionState, number | null>> = {
DRAFT: 24 * 60 * 60 * 1000, // 24 h
INITIATED: 5 * 60 * 1000, // 5 min
PRECONDITIONS_PENDING: 4 * 60 * 60 * 1000, // 4 h
READY_FOR_PREPARE: 15 * 60 * 1000, // 15 min
PREPARED: 30 * 60 * 1000, // 30 min
EXECUTING: 10 * 60 * 1000, // 10 min (dispatch_timeout §12.1)
PARTIALLY_EXECUTED: 15 * 60 * 1000, // 15 min (settlement_timeout §12.1)
VALIDATING: 10 * 60 * 1000, // 10 min
COMMITTED: 60 * 60 * 1000, // 1 h (waiting to be CLOSED)
ABORTED: 10 * 60 * 1000, // 10 min
UNWIND_PENDING: 12 * 60 * 60 * 1000, // 12 h
CLOSED: null, // terminal
};
/**
* Read the effective timeout (ms) for a given state, honouring per-state
* env overrides (`PHASE_TIMEOUT_<STATE>`). Returns `null` when the state
* has no timeout (terminal / explicitly disabled via override of "0").
*/
export function getPhaseTimeoutMs(state: TransactionState): number | null {
const override = process.env[`PHASE_TIMEOUT_${state}`];
if (override !== undefined) {
const parsed = Number(override);
if (!Number.isFinite(parsed) || parsed < 0) {
// Fall through to default when env value is invalid.
return DEFAULT_PHASE_TIMEOUTS[state];
}
return parsed === 0 ? null : parsed;
}
return DEFAULT_PHASE_TIMEOUTS[state];
}

View File

@@ -0,0 +1,126 @@
/**
* Tests for `assertProductionEnv` — arch §13 + gap-analysis v2 §8.1 / §8.4.
*
* These tests exercise the boot-time env assertion in isolation: they
* snapshot `process.env`, stub `process.exit`, flip envs, call the
* assertion, and restore.
*/
import { assertProductionEnv } from "../../src/config/env";
describe("assertProductionEnv", () => {
const savedEnv = { ...process.env };
let exitSpy: jest.SpyInstance;
let errorSpy: jest.SpyInstance;
beforeEach(() => {
process.env = { ...savedEnv };
exitSpy = jest
.spyOn(process, "exit")
.mockImplementation(((code?: number | string | null) => {
throw new Error(`process.exit(${code})`);
}) as never);
errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
});
afterEach(() => {
exitSpy.mockRestore();
errorSpy.mockRestore();
process.env = { ...savedEnv };
});
it("does nothing when NODE_ENV is not production", () => {
process.env.NODE_ENV = "development";
expect(() => assertProductionEnv()).not.toThrow();
expect(exitSpy).not.toHaveBeenCalled();
});
it("fails fast when SESSION_SECRET is missing in production", () => {
process.env.NODE_ENV = "production";
delete process.env.SESSION_SECRET;
process.env.EVENT_BUS_HMAC_SECRET = "x".repeat(40);
process.env.CHAIN_138_RPC_URL = "https://rpc.example.com";
process.env.NOTARY_REGISTRY_ADDRESS =
"0x" + "a".repeat(40);
process.env.ORCHESTRATOR_PRIVATE_KEY = "0x" + "b".repeat(64);
process.env.DATABASE_URL = "postgres://localhost/db";
expect(() => assertProductionEnv()).toThrow("process.exit(1)");
const output = errorSpy.mock.calls.flat().join(" ");
expect(output).toMatch(/SESSION_SECRET/);
});
it("fails fast when SESSION_SECRET is the dev placeholder", () => {
process.env.NODE_ENV = "production";
process.env.SESSION_SECRET =
"dev-secret-change-in-production-min-32-chars";
process.env.EVENT_BUS_HMAC_SECRET = "x".repeat(40);
process.env.CHAIN_138_RPC_URL = "https://rpc.example.com";
process.env.NOTARY_REGISTRY_ADDRESS = "0x" + "a".repeat(40);
process.env.ORCHESTRATOR_PRIVATE_KEY = "0x" + "b".repeat(64);
process.env.DATABASE_URL = "postgres://localhost/db";
expect(() => assertProductionEnv()).toThrow("process.exit(1)");
expect(errorSpy.mock.calls.flat().join(" ")).toMatch(
/SESSION_SECRET.*dev placeholder/,
);
});
it("fails fast when NotaryRegistry envs are absent", () => {
process.env.NODE_ENV = "production";
process.env.SESSION_SECRET = "s".repeat(40);
process.env.EVENT_BUS_HMAC_SECRET = "x".repeat(40);
process.env.DATABASE_URL = "postgres://localhost/db";
delete process.env.CHAIN_138_RPC_URL;
delete process.env.NOTARY_REGISTRY_ADDRESS;
delete process.env.ORCHESTRATOR_PRIVATE_KEY;
expect(() => assertProductionEnv()).toThrow("process.exit(1)");
const output = errorSpy.mock.calls.flat().join(" ");
expect(output).toMatch(/NotaryRegistry/);
expect(output).toMatch(/CHAIN_138_RPC_URL/);
expect(output).toMatch(/NOTARY_REGISTRY_ADDRESS/);
expect(output).toMatch(/ORCHESTRATOR_PRIVATE_KEY/);
});
it("fails fast when EVENT_BUS_HMAC_SECRET falls back to dev placeholder", () => {
process.env.NODE_ENV = "production";
process.env.SESSION_SECRET = "s".repeat(40);
delete process.env.EVENT_BUS_HMAC_SECRET;
process.env.CHAIN_138_RPC_URL = "https://rpc.example.com";
process.env.NOTARY_REGISTRY_ADDRESS = "0x" + "a".repeat(40);
process.env.ORCHESTRATOR_PRIVATE_KEY = "0x" + "b".repeat(64);
process.env.DATABASE_URL = "postgres://localhost/db";
// eventSecret falls back to SESSION_SECRET which is valid, so this
// path should *succeed* — SESSION_SECRET is a legitimate source of
// signing material per the getSigningSecret fallback chain.
expect(() => assertProductionEnv()).not.toThrow();
});
it("passes when all envs are set to real values in production", () => {
process.env.NODE_ENV = "production";
process.env.SESSION_SECRET = "s".repeat(40);
process.env.EVENT_BUS_HMAC_SECRET = "e".repeat(40);
process.env.CHAIN_138_RPC_URL = "https://rpc.example.com";
process.env.NOTARY_REGISTRY_ADDRESS = "0x" + "a".repeat(40);
process.env.ORCHESTRATOR_PRIVATE_KEY = "0x" + "b".repeat(64);
process.env.DATABASE_URL = "postgres://localhost/db";
expect(() => assertProductionEnv()).not.toThrow();
expect(exitSpy).not.toHaveBeenCalled();
});
it("reports DATABASE_URL missing in production", () => {
process.env.NODE_ENV = "production";
process.env.SESSION_SECRET = "s".repeat(40);
process.env.EVENT_BUS_HMAC_SECRET = "e".repeat(40);
process.env.CHAIN_138_RPC_URL = "https://rpc.example.com";
process.env.NOTARY_REGISTRY_ADDRESS = "0x" + "a".repeat(40);
process.env.ORCHESTRATOR_PRIVATE_KEY = "0x" + "b".repeat(64);
delete process.env.DATABASE_URL;
expect(() => assertProductionEnv()).toThrow("process.exit(1)");
expect(errorSpy.mock.calls.flat().join(" ")).toMatch(/DATABASE_URL/);
});
});

View File

@@ -1,75 +0,0 @@
/**
* Tests for per-state phase timeouts (arch §12.1 / gap v2 §7.6 / §10.7).
*/
import {
DEFAULT_PHASE_TIMEOUTS,
TRANSACTION_STATES,
getPhaseTimeoutMs,
} from "../../src/types/transactionState";
describe("PHASE_TIMEOUTS", () => {
const savedEnv = { ...process.env };
afterEach(() => {
process.env = { ...savedEnv };
});
it("has a mapping for every declared transaction state", () => {
for (const s of TRANSACTION_STATES) {
expect(DEFAULT_PHASE_TIMEOUTS).toHaveProperty(s);
}
});
it("CLOSED is the only state without a timeout", () => {
const nullStates = TRANSACTION_STATES.filter(
(s) => DEFAULT_PHASE_TIMEOUTS[s] === null,
);
expect(nullStates).toEqual(["CLOSED"]);
});
it("all non-terminal timeouts are strictly positive integers", () => {
for (const s of TRANSACTION_STATES) {
const v = DEFAULT_PHASE_TIMEOUTS[s];
if (v === null) continue;
expect(v).toBeGreaterThan(0);
expect(Number.isInteger(v)).toBe(true);
}
});
it("getPhaseTimeoutMs honours a valid env override", () => {
process.env.PHASE_TIMEOUT_EXECUTING = "123456";
expect(getPhaseTimeoutMs("EXECUTING")).toBe(123456);
});
it("getPhaseTimeoutMs treats override '0' as 'no timeout' (null)", () => {
process.env.PHASE_TIMEOUT_EXECUTING = "0";
expect(getPhaseTimeoutMs("EXECUTING")).toBeNull();
});
it("getPhaseTimeoutMs falls back to default when override is invalid", () => {
process.env.PHASE_TIMEOUT_EXECUTING = "not-a-number";
expect(getPhaseTimeoutMs("EXECUTING")).toBe(
DEFAULT_PHASE_TIMEOUTS.EXECUTING,
);
});
it("getPhaseTimeoutMs falls back to default when override is negative", () => {
process.env.PHASE_TIMEOUT_PREPARED = "-1";
expect(getPhaseTimeoutMs("PREPARED")).toBe(
DEFAULT_PHASE_TIMEOUTS.PREPARED,
);
});
it("returns the default when no env override exists", () => {
delete process.env.PHASE_TIMEOUT_VALIDATING;
expect(getPhaseTimeoutMs("VALIDATING")).toBe(
DEFAULT_PHASE_TIMEOUTS.VALIDATING,
);
});
it("CLOSED stays null even with no env override", () => {
delete process.env.PHASE_TIMEOUT_CLOSED;
expect(getPhaseTimeoutMs("CLOSED")).toBeNull();
});
});