Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(np08): close low-risk evidence and auth follow-ups

Alfredo Lopez09421d02d84f
diff --git a/.github/workflows/ci-public.yml b/.github/workflows/ci-public.yml
index 523f1dbf1..2f964e94d 100644
--- a/.github/workflows/ci-public.yml
+++ b/.github/workflows/ci-public.yml
@@ -511,6 +511,9 @@ jobs:
- name: Test NP-08 Host clients have no v1 fallback
run: bash scripts/tests/test-np08-v1-reference-inventory.sh
+ - name: Test NP-08 evidence scanner fails closed
+ run: bash scripts/tests/test-np08-evidence-scanner.sh
+
- name: Test NP-08 deployed E2E cleanup and provenance guards
run: bash scripts/tests/test-np08-e2e-guards.sh
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 3aef21c65..2b3b57e0e 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.474",
+ "version": "0.1.475",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.474",
+ "version": "0.1.475",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/image-policy": "file:../packages/image-policy",
diff --git a/control-api/package.json b/control-api/package.json
index a9605158b..6c4b4cf04 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.474",
+ "version": "0.1.475",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/utils/auth/mcpHostJwtToken.ts b/control-api/src/utils/auth/mcpHostJwtToken.ts
index 28fae32b8..e3f28922a 100644
--- a/control-api/src/utils/auth/mcpHostJwtToken.ts
+++ b/control-api/src/utils/auth/mcpHostJwtToken.ts
@@ -17,6 +17,12 @@ const EXPIRED_REFRESH_REISSUE_GRACE_SECONDS = 5 * 60
export const MCP_HOST_WORKFLOW_AUDIENCE = 'workflow-approvals'
export const MCP_HOST_HCC_AUDIENCE = 'host-context-controller'
export const MCP_HOST_CREDENTIAL_CAPABILITY = 'mcp:credential:read'
+/**
+ * HCC's access-token verifier accepts at most ten minutes. Keep the issuer
+ * fail-closed if an operator raises the shared workflow access TTL without
+ * first changing the HCC security contract.
+ */
+export const MCP_HOST_HCC_ACCESS_MAX_TTL_SECONDS = 600
const HCC_HOST_NAME_RE = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/
type McpHostCredentialLineage = {
@@ -214,6 +220,10 @@ function issueToken(
if (hccCredential) {
assertHccCredentialLineage(recipeNamespace, recipeName, hostRefs, hccCredential)
}
+ const effectiveTtlSec =
+ hccCredential && scope === 'workflow:approval:request'
+ ? Math.min(ttlSec, MCP_HOST_HCC_ACCESS_MAX_TTL_SECONDS)
+ : ttlSec
const token = jwt.sign(
{
sub: `${recipeNamespace}/${recipeName}`,
@@ -237,10 +247,10 @@ function issueToken(
? [MCP_HOST_WORKFLOW_AUDIENCE, MCP_HOST_HCC_AUDIENCE]
: MCP_HOST_WORKFLOW_AUDIENCE,
jwtid: randomUUID(),
- expiresIn: ttlSec,
+ expiresIn: effectiveTtlSec,
}
)
- return { token, expiresInSeconds: ttlSec }
+ return { token, expiresInSeconds: effectiveTtlSec }
}
export function issueMcpHostAccessJwt(
diff --git a/control-api/test/mcpHostJwtToken.hostRefs.test.ts b/control-api/test/mcpHostJwtToken.hostRefs.test.ts
index 9bc462266..b15474411 100644
--- a/control-api/test/mcpHostJwtToken.hostRefs.test.ts
+++ b/control-api/test/mcpHostJwtToken.hostRefs.test.ts
@@ -4,6 +4,7 @@ import { config } from '../src/config.js'
import {
ALL_MCP_HOST_CONTROL_SCOPES,
MCP_HOST_CREDENTIAL_CAPABILITY,
+ MCP_HOST_HCC_ACCESS_MAX_TTL_SECONDS,
MCP_HOST_HCC_AUDIENCE,
MCP_HOST_WORKFLOW_AUDIENCE,
type McpHostAccessClaims,
@@ -74,6 +75,26 @@ describe('mcpHostJwtToken — hostRefs JWT claim', () => {
})
})
+ it('clamps an HCC access token to the verifier ceiling without changing WRC TTLs', () => {
+ const previousAccessTtl = config.mcpHostJwtAccessTtlSec
+ config.mcpHostJwtAccessTtlSec = MCP_HOST_HCC_ACCESS_MAX_TTL_SECONDS + 300
+ try {
+ const hcc = issueMcpHostAccessJwt(config.hostsNamespace, 'standalone', ['chatllm'], {
+ hccCredential: { hostUid: 'host-uid-chatllm' },
+ })
+ const workflow = issueMcpHostAccessJwt('sandbox-recipes', 'recipe')
+ const hccClaims = jwt.decode(hcc.token) as Record<string, unknown>
+
+ expect(hcc.expiresInSeconds).toBe(MCP_HOST_HCC_ACCESS_MAX_TTL_SECONDS)
+ expect((hccClaims.exp as number) - (hccClaims.iat as number)).toBe(
+ MCP_HOST_HCC_ACCESS_MAX_TTL_SECONDS
+ )
+ expect(workflow.expiresInSeconds).toBe(previousAccessTtl + 300)
+ } finally {
+ config.mcpHostJwtAccessTtlSec = previousAccessTtl
+ }
+ })
+
it('rejects workflow-only tokens that inject HCC-only claims', () => {
const token = jwt.sign(
{
diff --git a/docs/testing/minikube-t2-runbook.md b/docs/testing/minikube-t2-runbook.md
index 0d7211e35..bc3673c61 100644
--- a/docs/testing/minikube-t2-runbook.md
+++ b/docs/testing/minikube-t2-runbook.md
@@ -91,18 +91,40 @@ use `CONTROL_API_REAL_PG_ADMIN_URL` unchanged.
## T0, T1, and T2 boundaries
-* **T0** — shell syntax/ShellCheck where available, contract tests, affected
+- **T0** — shell syntax/ShellCheck where available, contract tests, affected
package builds/typechecks, and `git diff --check`.
-* **T1** — the Real PostgreSQL suites execute against the validated local
+- **T1** — the Real PostgreSQL suites execute against the validated local
`control-postgres`; the lane reports `PASS`, `FAIL`, `SKIPPED`, and `NOT_RUN`
separately and fails on an unavailable DSN or zero executed tests.
-* **T2** — the exact worktree/`HEAD` is deployed to the owned profile, the
+- **T2** — the exact worktree/`HEAD` is deployed to the owned profile, the
cluster is healthy, readiness and health checks pass, and applicable
Control UI/Desktop journeys are run through their user-visible paths.
CI, static tests, T1, T2, and Playwright are separate evidence lanes. A green
CI job or unit suite is not proof of T2 runtime behavior.
+## NP-08 security evidence gates
+
+The NP-08 runtime conformance helpers are intentionally branch-owned, local
+T2 adjuncts rather than shared CI jobs. They require an explicit Minikube
+context and must never target GKE, Clerum-dev, Clerum-prod, or a shared
+profile:
+
+- `scripts/security/verify-np08-hcc-authz.sh` is the read-only deployment
+ conformance check (Gate F). Invoke it with
+ `--context <profile-context> --read-only --redact-identifiers`.
+- `scripts/security/run-np08-synthetic-gate.sh` runs the repository-owned
+ two-Context authorization matrix without Kubernetes writes (Gate E). Give it
+ the same explicit context and a summary path below the ignored run directory.
+- `scripts/security/scan-np08-evidence.sh` scans already-redacted API/log
+ evidence. Its fixture regression runs in public CI; production-like evidence
+ is scanned only after a local T2 run and must never contain Secret values.
+
+The canonical T2 journey remains
+`scripts/e2e/e2e-np08-hcc-authorization.sh`; these helpers do not replace it.
+Their manual status must be recorded as `PASS`, `FAIL`, or `NOT_RUN` in the
+sanitized run evidence rather than inferred from unit or CI results.
+
## Recovery and retry
Every phase has a bounded timeout. Failures name the first failing precondition,
@@ -136,3 +158,22 @@ or private PostgreSQL URLs as well as other sensitive runtime artifacts.
If ownership, scope, or redaction cannot be proved, stop and preserve the
reported code; do not widen the command to another cluster.
+
+### Deferred NP-08 hardening
+
+The following items are deliberately deferred because they change a security
+contract or require a separate rollout. They remain tracked follow-ups and are
+not evidence that PR1's credential disclosure fix is incomplete.
+
+| Follow-up | Owner / scope | Required completion evidence |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Preserve HCC lineage through refresh/reissue without carrying `aud=host-context-controller` or `mcp:credential:read` on the longer-lived refresh token | Control API + HCC, separate auth-contract change | Issuance, refresh, reissue, expiry, and wrong-route negative tests; explicit rollout/rollback matrix; HCC accepts only the short-lived access credential. |
+| Replace the anonymous global metadata inventory with an authenticated system principal for `mcp-proxy`, then retire the v1 route | HCC + gateway + mcp-proxy, PR2 | A dedicated service identity and least-privilege route; no Host access; destination-bound grant/revision; proxy migration and v1 tombstone tests; both rendered and live policy proofs. |
+| Add bounded rate limiting to unauthenticated diagnostic/metadata routes without breaking readiness, metrics, or the retained proxy compatibility lane | HCC/gateway operations | Per-route load/availability tests, probe compatibility evidence, normalized 429 contract, and a rollback-safe gateway rollout. |
+
+The first item is intentionally not a follow-up patch in PR1: changing refresh
+claims changes token consumers and revocation semantics. The second is the
+accepted PR2 residual: the current global response is metadata-only and must
+not be described as a credential-disclosure path. The third is deferred rather
+than guessed because an overly broad limiter could take down health probes or
+the still-supported inventory consumer.
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 0bc895135..1d8ebec3c 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.272",
+ "version": "0.1.273",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.272",
+ "version": "0.1.273",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 2d6ed468f..e8f570de9 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.272",
+ "version": "0.1.273",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/contextMapperClient.ts b/mcp-host/src/contextMapperClient.ts
index c017def74..6374e33ca 100644
--- a/mcp-host/src/contextMapperClient.ts
+++ b/mcp-host/src/contextMapperClient.ts
@@ -66,7 +66,8 @@ export function isContextMapperInventoryAuthorityRevocation(error: unknown): boo
export interface ContextMapperAuthentication {
getAccessToken(): string
refreshOnUnauthorized(): Promise<void>
- onCallerAuthorizationFailure?(status: 401 | 403): void
+ /** Required so every authenticated client has a synchronous revocation hook. */
+ onCallerAuthorizationFailure(status: 401 | 403): void
}
export interface ContextMapperClientOptions {
@@ -203,7 +204,7 @@ export class ContextMapperClient {
// revoke any already-published fleet before returning to the caller.
}
if (!token) {
- this.authentication?.onCallerAuthorizationFailure?.(401)
+ this.authentication?.onCallerAuthorizationFailure(401)
throw new ContextMapperRequestError(401, kind, true)
}
return token
@@ -230,14 +231,14 @@ export class ContextMapperClient {
try {
await this.authentication.refreshOnUnauthorized()
} catch {
- this.authentication.onCallerAuthorizationFailure?.(401)
+ this.authentication.onCallerAuthorizationFailure(401)
throw new ContextMapperRequestError(401, kind, true)
}
continue
}
if (response.status === 401 || response.status === 403) {
- this.authentication?.onCallerAuthorizationFailure?.(response.status)
+ this.authentication?.onCallerAuthorizationFailure(response.status)
throw new ContextMapperRequestError(response.status, kind, true)
}
if (!response.ok) {
diff --git a/mcp-host/src/mcp/__tests__/authorityLifecycle.test.ts b/mcp-host/src/mcp/__tests__/authorityLifecycle.test.ts
index 3a3f0c2bf..9ed78b8a5 100644
--- a/mcp-host/src/mcp/__tests__/authorityLifecycle.test.ts
+++ b/mcp-host/src/mcp/__tests__/authorityLifecycle.test.ts
@@ -236,6 +236,7 @@ describe('MCP authority lifecycle', () => {
authentication: {
getAccessToken: () => 'host-access-token',
refreshOnUnauthorized: vi.fn(),
+ onCallerAuthorizationFailure: vi.fn(),
},
})
const error = await captureError(() => client.pollServers())
diff --git a/scripts/e2e/e2e-hcc-mcp-context-readiness.sh b/scripts/e2e/e2e-hcc-mcp-context-readiness.sh
index cccb17538..d4b0e6664 100755
--- a/scripts/e2e/e2e-hcc-mcp-context-readiness.sh
+++ b/scripts/e2e/e2e-hcc-mcp-context-readiness.sh
@@ -716,19 +716,24 @@ function get(path) {
}
(async () => {
const ready = await get('/ready');
- const scoped = await get('/api/v1/mcpservers/context/' + encodeURIComponent(context));
- const body = JSON.parse(scoped.body);
- const fixture = body.servers?.find(server => server.name === expected);
+ const inventory = await get('/api/v1/mcpservers');
+ const body = JSON.parse(inventory.body);
+ const fixture = body.servers?.find(
+ server => server.name === expected && server.contextRef === context
+ );
if (ready.status !== 200 || JSON.parse(ready.body).ready !== true) {
throw new Error('readiness regressed: ' + ready.status + ' ' + ready.body);
}
- if (scoped.status !== 200 || !fixture || fixture.status?.ready !== true) {
- throw new Error('latest Context did not converge in discovery: ' + scoped.status + ' ' + scoped.body);
+ if (inventory.status !== 200 || !fixture || fixture.status?.ready !== true) {
+ throw new Error(
+ 'latest Context did not converge in global metadata inventory: ' +
+ inventory.status + ' ' + inventory.body
+ );
}
console.log(JSON.stringify({
readyStatus: ready.status,
- scopedDiscoveryStatus: scoped.status,
- contextRef: body.contextRef,
+ globalInventoryStatus: inventory.status,
+ contextRef: fixture.contextRef,
fixture: fixture.name,
fixtureReady: fixture.status.ready
}));
@@ -1773,10 +1778,10 @@ wait_until 300 "all peer MCP/Context runtimes to converge after releasing the he
hcc_identity_is_stable ||
die "HCC restarted instead of completing the released background convergence"
final_probe="$(probe_hcc_final_context)" ||
- die "HCC final Context-scoped discovery did not expose the converged fixture"
+ die "HCC final global metadata inventory did not expose the converged fixture in its Context"
echo "$final_probe" | jq -e \
--arg fixture "$MCP_NAME" --arg context "$CONTEXT_NAME" '
- .readyStatus == 200 and .scopedDiscoveryStatus == 200 and
+ .readyStatus == 200 and .globalInventoryStatus == 200 and
.fixture == $fixture and .fixtureReady == true and .contextRef == $context
' >/dev/null ||
die "HCC final probe returned an invalid result: ${final_probe}"
diff --git a/scripts/security/scan-np08-evidence.sh b/scripts/security/scan-np08-evidence.sh
index 6d5bd8985..d0152516f 100755
--- a/scripts/security/scan-np08-evidence.sh
+++ b/scripts/security/scan-np08-evidence.sh
@@ -5,6 +5,11 @@ set -euo pipefail
# lines. API/log inputs must already be redacted; rendered manifests are a
# separate scope and may contain Secret references, but never credential values.
+command -v rg >/dev/null 2>&1 || {
+ echo 'FAIL: ripgrep (rg) is required for NP-08 evidence scanning' >&2
+ exit 1
+}
+
tmpdir="$(mktemp -d "${TMPDIR:-/tmp}/np08-evidence.XXXXXX")"
trap 'rm -rf "${tmpdir}"' EXIT
@@ -61,8 +66,15 @@ scan_scope() {
local input
for input in "$@"; do
local hits="${tmpdir}/${scope}-${count}.hits"
+ local rg_status
if rg -n -I -i --no-messages -e "${pattern}" "${input}" >"${hits}"; then
count=$((count + $(wc -l <"${hits}")))
+ else
+ rg_status=$?
+ if [[ "${rg_status}" -ne 1 ]]; then
+ echo "FAIL: rg could not scan ${scope} evidence (exit ${rg_status})" >&2
+ return 2
+ fi
fi
done
echo "${scope}_violations=${count}"
diff --git a/scripts/tests/test-hcc-watch-recovery-gate.sh b/scripts/tests/test-hcc-watch-recovery-gate.sh
index 379d362e6..5a2620513 100755
--- a/scripts/tests/test-hcc-watch-recovery-gate.sh
+++ b/scripts/tests/test-hcc-watch-recovery-gate.sh
@@ -1613,6 +1613,24 @@ else
fail "MCP readiness gate duplicates ownership or retains a deadline, pod-absence, or port edge"
fi
+# The caller-selected v1 Context route is a 410 tombstone. This readiness gate
+# may use the temporary PR 2 global metadata inventory, but it must bind the
+# uniquely named fixture back to the expected Context before claiming success.
+mcp_final_context_probe="$(
+ sed -n '/^probe_hcc_final_context() {$/,/^probe_hcc_ready_pod() {$/p' \
+ "$MCP_READINESS_GATE"
+)"
+# Literal source-code assertions.
+# shellcheck disable=SC2016
+if [[ "$mcp_final_context_probe" == *"get('/api/v1/mcpservers')"* ]] &&
+ [[ "$mcp_final_context_probe" == *'server.contextRef === context'* ]] &&
+ [[ "$mcp_final_context_probe" == *'fixture.status?.ready !== true'* ]] &&
+ [[ "$mcp_final_context_probe" != *'/api/v1/mcpservers/context/'* ]]; then
+ pass "MCP readiness final probe uses global metadata and binds the fixture to its Context"
+else
+ fail "MCP readiness final probe calls a retired route or loses Context binding"
+fi
+
# A single held McpServer proves the minimal failure, but this gate must also
# cross the controller's bounded worker width with independent, gate-owned
# McpServer/Context pairs. Keep this as a static contract so future edits do
diff --git a/scripts/tests/test-np08-evidence-scanner.sh b/scripts/tests/test-np08-evidence-scanner.sh
index 2a4fee539..8b5772da8 100755
--- a/scripts/tests/test-np08-evidence-scanner.sh
+++ b/scripts/tests/test-np08-evidence-scanner.sh
@@ -5,6 +5,25 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
SCANNER="${ROOT}/scripts/security/scan-np08-evidence.sh"
tmpdir="$(mktemp -d "${TMPDIR:-/tmp}/np08-scan-test.XXXXXX")"
trap 'rm -rf "${tmpdir}"' EXIT
+BASH_BIN="$(command -v bash)"
+
+if PATH="${tmpdir}/missing-tools" "${BASH_BIN}" "${SCANNER}" \
+ --stdin-kind api </dev/null >/dev/null 2>&1; then
+ echo 'FAIL: scanner passed without ripgrep' >&2
+ exit 1
+fi
+
+if (
+ # Invoked indirectly by the scanner's child Bash process.
+ # shellcheck disable=SC2329
+ rg() { return 2; }
+ export -f rg
+ printf '%s\n' '{"Authorization":"Bearer abc.def.ghi"}' |
+ bash "${SCANNER}" --stdin-kind api >/dev/null 2>&1
+); then
+ echo 'FAIL: scanner passed when ripgrep returned an execution error' >&2
+ exit 1
+fi
if ! printf '%s\n' '{"error":"authorization_unavailable"}' | bash "${SCANNER}" --stdin-kind api >/dev/null; then
echo 'FAIL: sanitized authorization error was treated as a credential leak' >&2