@xshieldai/aegis-guard 0.3.0 → 0.4.0

package/README.md

@@ -1,10 +1,11 @@
-# @rocketlang/aegis-guard
+# @xshieldai/aegis-guard
 
-> **🔍 Verification status (2026-05-17 IST)**
-> - **Tests:** ✅ **63/63 passing** ([tests/aegis-guard.test.ts](tests/aegis-guard.test.ts) — `bun test`)
-> - **Examples:** ✅ runnable quickstart: [examples/quickstart.ts](examples/quickstart.ts) — `bun run examples/quickstart.ts` shows all 5 Locks in action with receipts
-> - **Live demo:** ⚠️ planned (Tier 3, see [PROOF-STACK.md](../../PROOF-STACK.md))
-> - **Phase-1 limits:** documented in the v0.2.0 ACC section below
+> **🔍 Verification status (2026-10-05 IST — v0.4.0)**
+> - **Tests:** ✅ **177/177 passing** in the repository; the npm package ships `src/` only, so run them from a clone (`bun test`): 70 in [tests/aegis-guard.test.ts](https://github.com/rocketlang/aegis/blob/master/packages/aegis-guard/tests/aegis-guard.test.ts) and 107 in [tests/hardening.test.ts](https://github.com/rocketlang/aegis/blob/master/packages/aegis-guard/tests/hardening.test.ts) for key trust, malformed tokens, nonces, the duplicate check, the audit event, the quality bar, the envelope helpers and the stated limits. No test contacts a network or touches `~/.aegis`.
+> - **Examples:** ✅ runnable quickstart, in the repository (not in the npm package): [examples/quickstart.ts](https://github.com/rocketlang/aegis/blob/master/packages/aegis-guard/examples/quickstart.ts) — `bun run examples/quickstart.ts` shows all 5 Locks in action with receipts
+> - **Live demo:** ⚠️ planned (Tier 3, see [PROOF-STACK.md](https://github.com/rocketlang/aegis/blob/master/PROOF-STACK.md))
+> - **Limits:** see "What this does not do" below, and the v0.2.0 ACC section
+> - **Upgrading from 0.3.x:** some calls that passed are now refused, and minting no longer makes a key. See "Upgrading from 0.3.x".
 
 AEGIS Guard SDK — reusable approval-token, nonce, idempotency, SENSE, and quality-evidence primitives for AEGIS-governed services.
 
@@ -25,17 +26,37 @@ The Five Locks were proven across 13 batches (62–74) of carbonx-backend. This
 ## Install
 
 ```bash
-bun add @rocketlang/aegis-guard
+bun add @xshieldai/aegis-guard
 # or
-npm install @rocketlang/aegis-guard
+npm install @xshieldai/aegis-guard
 ```
 
+## Keys — who signs, who verifies
+
+An approval token is an EdDSA-signed JWT. One box signs; every other box only verifies.
+
+| Box | Holds | Set up by |
+|---|---|---|
+| The approving authority (AEGIS) | `~/.aegis/approval-signing.key` and `.pub` | `ensureSigningKeypair()`, once, at boot |
+| Every service that checks approvals | the authority's **public** key | the file `~/.aegis/approval-signing.pub`, or the PEM in `AEGIS_APPROVAL_PUBKEY_PEM` |
+
+`AEGIS_DIR` replaces `~/.aegis`. The rules the package enforces (`AEG-HG-2B-007`):
+
+- **Minting never makes a key.** `mintApprovalToken()` throws on a box with no private key.
+- **A box that was given a public key never makes its own.** `ensureSigningKeypair()` throws there and writes nothing.
+- **Keys that disagree are not trusted.** If the private key, the public file and the environment PEM are not all the same Ed25519 key, every verification is refused and the reason names the conflict.
+- **No key, no approval.** With no key material at all, verification is refused.
+
 ## Usage
 
 ### LOCK_1 + LOCK_2 — decision + identity
 
+`verifyApprovalToken()` checks, in order: the signature; that service, capability and operation match exactly; that `expires_at` is a number and not past; that `issued_at`, when present, is a number, not more than 60 seconds ahead of the clock and not after `expires_at`; that `status`, when present, is exactly `approved`. Anything else throws `IrrNoApprovalError` (`code: 'IRR-NOAPPROVAL'`) — including a token that is not text.
+
+Mint with `issued_at` and `expires_at` in milliseconds: `mintApprovalToken({ service_id, capability, operation, nonce, issued_at: Date.now(), expires_at: Date.now() + 60_000 })`.
+
 ```typescript
-import { verifyApprovalToken, verifyScopedApprovalToken } from '@rocketlang/aegis-guard';
+import { verifyApprovalToken, verifyScopedApprovalToken } from '@xshieldai/aegis-guard';
 
 // LOCK_1 — base token verification (service_id + capability + operation)
 const payload = verifyApprovalToken(token, 'my-service', 'settle', 'record_settle');
@@ -47,10 +68,12 @@ const payload = verifyScopedApprovalToken(
 );
 ```
 
+Each scope field must be the token's own field and strictly equal (`100` is not `"100"`). A field the caller has no value for (`undefined` or `null`) is refused: it would bind the token to nothing.
+
 ### LOCK_3 — observability (SENSE)
 
 ```typescript
-import { emitAegisSenseEvent, digestApprovalToken, configureSenseTransport } from '@rocketlang/aegis-guard';
+import { emitAegisSenseEvent, digestApprovalToken, configureSenseTransport } from '@xshieldai/aegis-guard';
 
 // Wire your logger (default: process.stdout JSON)
 configureSenseTransport((event) => logger.info(event, `SENSE:${event.event_type}`));
@@ -70,32 +93,40 @@ emitAegisSenseEvent({
 });
 ```
 
+If `approval_token_ref` is not already a 24-hex digest, the SDK digests it before the event reaches the transport or the bus, so a raw token passed by mistake is not written to the log.
+
 ### LOCK_4 — rollback guard (idempotency check)
 
 ```typescript
-import { checkIdempotency, buildIdempotencyFingerprint } from '@rocketlang/aegis-guard';
+import { checkIdempotency, buildIdempotencyFingerprint } from '@xshieldai/aegis-guard';
 
 const existing = await db.findByExternalRef(args.externalRef);
 const fp = buildIdempotencyFingerprint({ amount: args.amount, vessel_id: args.vesselId });
 const { isDuplicate, safeNoOp } = checkIdempotency(args.externalRef, existing, fp, existing?.fingerprint);
 
 if (isDuplicate && safeNoOp) return existing; // safe no-op
-if (isDuplicate && !safeNoOp) throw new Error('payload mismatch on duplicate externalRef');
+if (isDuplicate && !safeNoOp) throw new Error('duplicate externalRef: payload differs or cannot be compared');
 ```
 
+A duplicate is a safe no-op only when **both** fingerprints are present and equal (`AEG-HG-2B-009`). If the existing record has no stored fingerprint, the result is `safeNoOp: false, comparable: false`: store the fingerprint with the record.
+
+`buildIdempotencyFingerprint()` sorts keys at every depth and keeps `NaN`, `±Infinity`, `bigint`, `Map` and `Set` distinct. The fingerprint is the payload, base64-encoded — **not a hash**. Anyone who can read a stored fingerprint can read the payload; keep secrets out of it or hash it before storing.
+
 ### LOCK_5 — nonce replay prevention
 
 ```typescript
-import { verifyAndConsumeNonce } from '@rocketlang/aegis-guard';
+import { verifyAndConsumeNonce } from '@xshieldai/aegis-guard';
 
 // Requires nonce in payload; throws IrrNoApprovalError on missing or replayed nonce
 await verifyAndConsumeNonce(payload, redisNonceStore);
 ```
 
+The nonce must be non-empty text and the payload must be in date. Only a store that answers exactly `true` has consumed the nonce; a store that throws propagates its error (fail closed). This call takes a payload and checks no signature: pass it what `verifyApprovalToken()` returned.
+
 ### Quality evidence
 
 ```typescript
-import { buildQualityMaskAtPromotion, meetsHgQualityRequirement } from '@rocketlang/aegis-guard';
+import { buildQualityMaskAtPromotion, meetsHgQualityRequirement } from '@xshieldai/aegis-guard';
 
 const mask = buildQualityMaskAtPromotion({
   tests_passed: true,
@@ -104,14 +135,29 @@ const mask = buildQualityMaskAtPromotion({
 });
 
 const ready = meetsHgQualityRequirement('HG-2B-financial', mask);
+// false here: the financial bar needs all twelve promotion bits
 ```
 
+`meetsHgQualityRequirement()` returns `false` for a group that is not in the table and for a mask that is not a whole number made of bits 0–11 (`-1`, `"4095"`, `4095.9`, or a mask with a drift bit set). `HG_REQUIRED_MASKS` is frozen.
+
+### Session envelope
+
+```typescript
+import { issueEnvelope, verifyEnvelope } from '@xshieldai/aegis-guard';
+
+const env = await issueEnvelope({ service_key: 'my-service', declared_caps: ['read'] });
+const audit = await verifyEnvelope(env.session_id);
+if (!audit.verified || audit.drift_detected) { /* quarantine the session */ }
+```
+
+Both call the Aegis dashboard (`aegis_url`, or `AEGIS_URL`, or `http://localhost:4850`; http and https only) and read its answer strictly (`ASE-016`): `verified` is true only when the answer says exactly `true` for the session asked about; an answer with no session id or seal throws. They trust that endpoint and the connection to it — they do not recompute the seal.
+
 ## NonceStore — production wiring
 
 The default `defaultNonceStore` is in-memory (single-process only). Multi-instance deployments must provide a Redis-backed store:
 
 ```typescript
-import { type NonceStore } from '@rocketlang/aegis-guard';
+import { type NonceStore } from '@xshieldai/aegis-guard';
 
 const redisNonceStore: NonceStore = {
   async consumeNonce(nonce, ttlMs) {
@@ -130,6 +176,30 @@ const redisNonceStore: NonceStore = {
 - `quality_drift_score`: bits 12–15, `aegis-quality-16bit-v1`
 - AEG-Q-003 invariant: bits 12–15 must **never** be set in `quality_mask_at_promotion`
 
+## Upgrading from 0.3.x
+
+- **Call `ensureSigningKeypair()` once on the authority box before minting.** Minting no longer makes a key. On a verifier box, do not call it at all.
+- **Mint with a numeric `expires_at`.** A token without one is refused (it used to never expire).
+- **`verifyApprovalToken()` refuses a `status` other than `approved`.** Before, only the scoped call looked at it.
+- **`checkIdempotency()` without a stored fingerprint is no longer a safe no-op.** Read the new `comparable` field.
+- **Fingerprints of nested payloads change** (inner keys are now sorted). A flat payload of text, finite numbers, booleans and null fingerprints as before. A retry that straddles the upgrade with a nested payload is reported as a mismatch.
+- **A stale `approval-signing.pub` next to the private key is now a conflict**, and verification is refused until the two agree.
+- `verifyEnvelope()` throws when the audit is for another session; `issueEnvelope()` throws on an answer with no session id or seal.
+
+## What this does not do
+
+Each of these is pinned by a test in `tests/hardening.test.ts`, so it cannot change unnoticed — except the two about what is absent (a shared nonce store, a revocation list), which no test can show.
+
+- **No upper limit on a token's life.** The signer chooses `expires_at`.
+- **An empty scope checks nothing more** than `verifyApprovalToken()`. A scope value that is an object never matches.
+- **`verifyAndConsumeNonce()` checks no signature and no status.** It trusts the payload it is given.
+- **A key file swapped under a running process is not noticed until restart.** A change of `AEGIS_APPROVAL_PUBKEY_PEM` is.
+- **The default nonce store is one process's memory.** Two instances each accept the same nonce once.
+- **The fingerprint is not a hash**, a field set to `undefined` is the same as the field absent, and a `Date` is the same as its ISO text.
+- **Only the `approval_token_ref` field is digested.** A raw token placed anywhere else in a SENSE event reaches the transport.
+- **A SENSE transport that throws reaches the caller**, and the three snapshots are not checked for presence.
+- **Revocation is a field in the token.** There is no revocation list: a token signed as `approved` stays valid until it expires.
+
 ## License
 
 AGPL-3.0 — Capt. Anil Sharma, powerpbox.org
@@ -145,7 +215,7 @@ v0.2.0 behaves identically to v0.1.0 — no emission, no state, no side effect.
 ### Wire it in 3 lines
 
 ```typescript
-import { setEventBus, type EventBus, type AccReceipt } from '@rocketlang/aegis-guard';
+import { setEventBus, type EventBus, type AccReceipt } from '@xshieldai/aegis-guard';
 
 const myBus: EventBus = {
   emit: (r: AccReceipt) => console.log(`[ACC] ${r.event_type} verdict=${r.verdict} ${r.summary}`),
@@ -161,7 +231,7 @@ Now every primitive call emits a receipt. Pass `null` to `setEventBus` to detach
 |---|---|---|
 | `verifyApprovalToken` | `lock.approval.verified` (PASS) | `lock.approval.rejected` (FAIL) |
 | `verifyAndConsumeNonce` | `lock.nonce.consumed` (PASS) | `lock.nonce.rejected` (FAIL) |
-| `checkIdempotency` | `lock.idempotency.duplicate` (PASS) OR `lock.idempotency.mismatch` (WARN) | (no event for non-duplicate path) |
+| `checkIdempotency` | `lock.idempotency.duplicate` (PASS), `lock.idempotency.mismatch` (WARN) or `lock.idempotency.unverifiable` (WARN, no fingerprint to compare) | (no event for non-duplicate path) |
 | `emitAegisSenseEvent` | `lock.sense.emitted` (PASS or WARN if irreversible) | — |
 
 ### Receipt shape
@@ -200,12 +270,12 @@ consumers ingest these events without translation.
   etc.) are a consumer choice — implement the `EventBus` interface and
   call `setEventBus(yourBus)`.
 
-### Use with `@rocketlang/aegis-suite`
+### Use with `@xshieldai/aegis-suite`
 
 If you installed the meta-package, you can wire all 6 primitives in one call:
 
 ```typescript
-import { wireAllToBus } from '@rocketlang/aegis-suite';  // available in suite v0.2.0+
+import { wireAllToBus } from '@xshieldai/aegis-suite';  // available in suite v0.2.0+
 wireAllToBus();  // default: in-memory bus + SQLite writer to ~/.aegis/acc-events.db
 ```
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@xshieldai/aegis-guard",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "AEGIS Guard SDK — Five Locks primitives (approval-token, nonce, idempotency, SENSE, quality-evidence) + opt-in Agentic Control Center event bus for AEGIS-governed services",
   "license": "AGPL-3.0-only",
   "type": "module",
   "author": "Capt. Anil Sharma <capt.anil.sharma@powerpbox.org>",
-  "homepage": "https://github.com/rocketlang/aegis/tree/main/packages/aegis-guard",
+  "homepage": "https://github.com/rocketlang/aegis/tree/master/packages/aegis-guard",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rocketlang/aegis.git",
@@ -41,7 +41,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "bun test tests/aegis-guard.test.ts",
+    "test": "bun test",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "node ../../scripts/publish-guard.mjs"
   },

package/src/acc-bus.ts

@@ -2,7 +2,7 @@
 // Copyright (c) 2026 Capt. Anil Sharma (rocketlang). All rights reserved.
 // See LICENSE for details.
 //
-// @rocketlang/aegis-guard — opt-in ACC event bus integration (v0.2.0)
+// @xshieldai/aegis-guard — opt-in ACC event bus integration (v0.2.0)
 // @rule:ACC-003 — Opt-in event bus. emit only when setEventBus() called.
 // @rule:ACC-004 — Lightweight OSS receipt shape (strict subset of EE PRAMANA).
 // @rule:ACC-YK-003 — Stateless-primitive contract preserved. No bus = no emit.

package/src/approval-token.ts

@@ -1,6 +1,9 @@
 // @rule:AEG-E-016 — approval tokens are scoped to service_id + capability + operation
 // @rule:AEG-HG-2B-005 — approval token references in SENSE use digest, not raw token material
 // @rule:AEG-HG-2B-006 — nonce protects the approval; idempotency protects the operation (separate locks)
+// @rule:AEG-HG-2B-008 — every field a decision rests on is checked for its type before it is
+//                       compared; anything the gate cannot read is a refusal, with the
+//                       package's own error, never a pass and never a TypeError
 
 import { createHash } from 'crypto';
 import { IrrNoApprovalError } from './errors.js';
@@ -23,16 +26,25 @@ export interface ApprovalTokenPayload {
   [key: string]: unknown;
 }
 
+const isTime = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v > 0;
+const isText = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
+const say = (v: unknown): string => (typeof v === 'string' ? v : typeof v).slice(0, 60);
+const own = (o: object, k: string): boolean => Object.prototype.hasOwnProperty.call(o, k);
+
 // @rule:AEG-HG-2B-005 — SENSE stores proof reference, not proof secret.
 // Returns first 24 hex chars of SHA-256 (96 bits) — sufficient for correlation, not reconstruction.
 export function digestApprovalToken(token: string): string {
-  return createHash('sha256').update(token).digest('hex').slice(0, 24);
+  return createHash('sha256').update(String(token)).digest('hex').slice(0, 24);
 }
 
 // @rule:AEG-E-016 @rule:KGT-002 — mint an AEGIS-signed EdDSA JWT (KGT-T1.1).
 // Signing requires the AEGIS private key (~/.aegis/approval-signing.key) — present on
-// the AEGIS box, auto-provisioned by the :4850 dashboard. Throws where the key is absent:
-// a service that cannot sign cannot mint, by design.
+// the AEGIS box, where the :4850 dashboard provisions it at boot with
+// ensureSigningKeypair(). Throws where the key is absent: a service that cannot sign
+// cannot mint, by design. Minting never makes a key.
+//
+// The payload is signed as given. verifyApprovalToken() will refuse a token without a
+// numeric expires_at, so mint with one.
 export function mintApprovalToken(payload: ApprovalTokenPayload): string {
   return signApprovalJwt(payload);
 }
@@ -41,6 +53,8 @@ export function mintApprovalToken(payload: ApprovalTokenPayload): string {
 // @rule:KGT-002 — signature verified FIRST, fail-closed: unsigned/tampered/alg:none/
 // wrong-key tokens are rejected before any scope check. Legacy base64url(JSON) tokens
 // (pre-KGT-T1.1, forgeable) are rejected outright.
+// @rule:AEG-HG-2B-008 — expires_at must be a number; a status other than 'approved' is a
+// refusal here, in LOCK_1, not only in the scoped check.
 export function verifyApprovalToken(
   token: string,
   expectedServiceId: string,
@@ -48,41 +62,71 @@ export function verifyApprovalToken(
   expectedOperation: string,
 ): ApprovalTokenPayload {
   // @rule:ACC-003 @rule:ACC-004 — emit ACC receipt on success OR failure
-  const scope = `${expectedServiceId}/${expectedCapability}/${expectedOperation}`;
+  const cap = isText(expectedCapability) ? expectedCapability : 'unknown';
+  const scope = `${say(expectedServiceId)}/${say(expectedCapability)}/${say(expectedOperation)}`;
   try {
+    if (!isText(expectedServiceId) || !isText(expectedCapability) || !isText(expectedOperation)) {
+      throw new IrrNoApprovalError(cap, 'AEG-E-016: the expected service, capability and operation must each be non-empty text');
+    }
     const jwt = verifyApprovalJwt(token);
     if (!jwt.ok) {
-      throw new IrrNoApprovalError(expectedCapability, `KGT-002: ${jwt.reason}`);
+      throw new IrrNoApprovalError(cap, `KGT-002: ${jwt.reason}`);
     }
     const payload = jwt.payload as ApprovalTokenPayload;
 
     if (payload.service_id !== expectedServiceId) {
       throw new IrrNoApprovalError(
-        expectedCapability,
-        `AEG-E-016: token scoped to '${payload.service_id}', not '${expectedServiceId}'`,
+        cap,
+        `AEG-E-016: token scoped to '${say(payload.service_id)}', not '${expectedServiceId}'`,
       );
     }
     if (payload.capability !== expectedCapability) {
       throw new IrrNoApprovalError(
-        expectedCapability,
-        `AEG-E-016: token capability '${payload.capability}' does not match '${expectedCapability}'`,
+        cap,
+        `AEG-E-016: token capability '${say(payload.capability)}' does not match '${expectedCapability}'`,
       );
     }
     if (payload.operation !== expectedOperation) {
       throw new IrrNoApprovalError(
-        expectedCapability,
-        `AEG-E-016: token operation '${payload.operation}' does not match '${expectedOperation}'`,
+        cap,
+        `AEG-E-016: token operation '${say(payload.operation)}' does not match '${expectedOperation}'`,
       );
     }
+    // A token with no expiry, or one written as text, used to compare false against the
+    // clock and so never expired.
+    if (!isTime(payload.expires_at)) {
+      throw new IrrNoApprovalError(cap, 'AEG-E-016: token has no numeric expires_at');
+    }
     if (Date.now() > payload.expires_at) {
-      throw new IrrNoApprovalError(expectedCapability, 'AEG-E-016: token expired');
+      throw new IrrNoApprovalError(cap, 'AEG-E-016: token expired');
+    }
+    if (payload.issued_at !== undefined) {
+      if (!isTime(payload.issued_at)) {
+        throw new IrrNoApprovalError(cap, 'AEG-E-016: token issued_at is not a number');
+      }
+      if (payload.issued_at > Date.now() + CLOCK_SKEW_MS) {
+        throw new IrrNoApprovalError(
+          cap,
+          'AEG-E-016: token issued_at is in the future (clock skew > 60s or forged timestamp)',
+        );
+      }
+      if (payload.issued_at > payload.expires_at) {
+        throw new IrrNoApprovalError(cap, 'AEG-E-016: token expires before it was issued');
+      }
     }
-    if (payload.issued_at !== undefined && payload.issued_at > Date.now() + CLOCK_SKEW_MS) {
+    // Absent means approved (tokens minted before the field existed). Anything else that
+    // is not exactly 'approved' is not an approval.
+    if (payload.status !== undefined && payload.status !== 'approved') {
       throw new IrrNoApprovalError(
-        expectedCapability,
-        'AEG-E-016: token issued_at is in the future (clock skew > 60s or forged timestamp)',
+        cap,
+        payload.status === 'revoked' ? 'AEG-E-016: token revoked'
+          : payload.status === 'denied' ? 'AEG-E-016: token denied'
+          : `AEG-E-016: token status '${say(payload.status)}' is not 'approved'`,
       );
     }
+    if (payload.nonce !== undefined && !isText(payload.nonce)) {
+      throw new IrrNoApprovalError(cap, 'AEG-E-016: token nonce is not text');
+    }
 
     emitAccReceipt({
       receipt_id: `aegis-guard-verify-${digestApprovalToken(token)}`,
@@ -106,29 +150,52 @@ export function verifyApprovalToken(
 
 // @rule:AEG-HG-2B-006 — consume nonce before any state mutation; missing nonce = hard reject.
 // Nonce TTL is bounded by token lifetime; store unavailable = fail CLOSED (throws, never open).
+// @rule:AEG-HG-2B-008 — the nonce must be text, the payload must be in date, and only a
+// store that answers exactly `true` has consumed it.
+//
+// This takes a payload, not a token: it does not check a signature. Pass it what
+// verifyApprovalToken() returned.
 export async function verifyAndConsumeNonce(
   payload: ApprovalTokenPayload,
   store: NonceStore = defaultNonceStore,
 ): Promise<void> {
   // @rule:ACC-003 @rule:ACC-004 — emit ACC receipt on success OR failure
-  const scope = `${payload.service_id}/${payload.capability}/${payload.operation}`;
+  const p = (payload !== null && typeof payload === 'object' ? payload : {}) as ApprovalTokenPayload;
+  const cap = isText(p.capability) ? p.capability : 'unknown';
+  const scope = `${say(p.service_id)}/${say(p.capability)}/${say(p.operation)}`;
   try {
-    if (!payload.nonce) {
+    if (p !== payload) {
+      throw new IrrNoApprovalError(cap, 'AEG-E-016: no approval payload');
+    }
+    if (payload.nonce === undefined || payload.nonce === null || payload.nonce === '') {
       throw new IrrNoApprovalError(
-        payload.capability,
+        cap,
         'AEG-E-016: irreversible operation requires nonce for replay prevention',
       );
     }
-    const ttlMs = Math.max(0, payload.expires_at - Date.now());
+    // An object as a nonce is a different object each time the token is parsed, so it
+    // would never be seen twice.
+    if (!isText(payload.nonce)) {
+      throw new IrrNoApprovalError(cap, 'AEG-E-016: nonce is not text');
+    }
+    if (!isTime(payload.expires_at)) {
+      throw new IrrNoApprovalError(cap, 'AEG-E-016: approval has no numeric expires_at');
+    }
+    // An expired approval has nothing left to protect, and a nonce stored for zero
+    // milliseconds is forgotten at once: the same approval could be consumed again.
+    const ttlMs = payload.expires_at - Date.now();
+    if (ttlMs <= 0) {
+      throw new IrrNoApprovalError(cap, 'AEG-E-016: approval expired');
+    }
     const consumed = await store.consumeNonce(payload.nonce, ttlMs);
-    if (!consumed) {
+    if (consumed !== true) {
       throw new IrrNoApprovalError(
-        payload.capability,
-        `AEG-E-016: nonce '${payload.nonce}' already consumed — approval replay rejected`,
+        cap,
+        `AEG-E-016: nonce '${payload.nonce.slice(0, 60)}' already consumed — approval replay rejected`,
       );
     }
     emitAccReceipt({
-      receipt_id: `aegis-guard-nonce-${payload.nonce}`,
+      receipt_id: `aegis-guard-nonce-${payload.nonce.slice(0, 80)}`,
       event_type: 'lock.nonce.consumed',
       verdict: 'PASS',
       rules_fired: ['AEG-HG-2B-006'],
@@ -149,6 +216,10 @@ export async function verifyAndConsumeNonce(
 // @rule:AEG-E-016 — HG-2B: verify scope fields declared by the caller service.
 // requiredScope: Record<string, unknown> — caller declares which fields to bind; SDK enforces them.
 // Service-agnostic: the caller owns the field names; the SDK never names domain concepts.
+// @rule:AEG-HG-2B-008 — a field the caller has no value for binds nothing, so it is a
+// refusal: before v0.4.0 `{ vessel_id: undefined }` matched any token without a vessel_id.
+//
+// An empty requiredScope checks nothing more than verifyApprovalToken() does.
 export function verifyScopedApprovalToken(
   token: string,
   expectedServiceId: string,
@@ -160,19 +231,22 @@ export function verifyScopedApprovalToken(
     token, expectedServiceId, expectedCapability, expectedOperation,
   );
 
-  if (payload.status === 'revoked') {
-    throw new IrrNoApprovalError(expectedCapability, 'AEG-E-016: token revoked');
-  }
-  if (payload.status === 'denied') {
-    throw new IrrNoApprovalError(expectedCapability, 'AEG-E-016: token denied');
+  if (requiredScope === null || typeof requiredScope !== 'object' || Array.isArray(requiredScope)) {
+    throw new IrrNoApprovalError(expectedCapability, 'AEG-E-016: required scope is not an object of fields');
   }
 
   for (const [field, contextValue] of Object.entries(requiredScope)) {
-    const tokenValue = payload[field];
+    if (contextValue === undefined || contextValue === null) {
+      throw new IrrNoApprovalError(
+        expectedCapability,
+        `AEG-E-016: scope field '${field}' has no value to bind the token to`,
+      );
+    }
+    const tokenValue = own(payload, field) ? payload[field] : undefined;
     if (tokenValue !== contextValue) {
       throw new IrrNoApprovalError(
         expectedCapability,
-        `AEG-E-016: token ${field} '${String(tokenValue)}' does not match scope '${String(contextValue)}'`,
+        `AEG-E-016: token ${field} '${String(tokenValue).slice(0, 60)}' does not match scope '${String(contextValue).slice(0, 60)}'`,
       );
     }
   }

package/src/envelope.ts

@@ -1,4 +1,4 @@
-// @ankr/aegis-guard — Agent Session Envelope helpers (ASE-T020)
+// @xshieldai/aegis-guard — Agent Session Envelope helpers (ASE-T020)
 //
 // issueEnvelope  — POST /api/v1/aegis/session   — proxy-native agent frameworks use this at startup
 // verifyEnvelope — GET  /api/v1/aegis/sessions/:id/audit — check seal integrity + drift
@@ -6,6 +6,12 @@
 // @rule:ASE-001 every proxy-native agent session must call issueEnvelope before its first LLM call
 // @rule:ASE-002 sealed_hash is computed by Aegis at issuance and returned in the response
 // @rule:INF-ASE-002 if sealed_hash_verified=false the session must be quarantined immediately
+// @rule:ASE-016 the helpers read the answer strictly: a seal is verified only when the
+//               answer says exactly `true`, for the session that was asked about; an
+//               answer with no session id or no seal is not an envelope
+//
+// These helpers trust the Aegis endpoint they are pointed at (aegis_url, or AEGIS_URL, or
+// http://localhost:4850) and the connection to it. They do not recompute the seal.
 
 export interface IssueEnvelopeParams {
   /** agent_type must be 'proxy-native' for frameworks calling this directly */
@@ -48,7 +54,13 @@ export interface EnvelopeVerifyResult {
 }
 
 function aegisBase(override?: string): string {
-  return override ?? process.env.AEGIS_URL ?? "http://localhost:4850";
+  const base = override ?? process.env.AEGIS_URL ?? "http://localhost:4850";
+  // Only http and https. Some runtimes will fetch a file: address and hand its contents
+  // back as if Aegis had answered.
+  let scheme = "";
+  try { scheme = new URL(base).protocol; } catch { throw new Error("aegis-guard: the Aegis address is not a URL"); }
+  if (scheme !== "http:" && scheme !== "https:") throw new Error(`aegis-guard: unsupported Aegis address scheme ${scheme}`);
+  return base.replace(/\/+$/, "");
 }
 
 // @rule:ASE-001 issue a sealed envelope before the first action
@@ -78,10 +90,19 @@ export async function issueEnvelope(params: IssueEnvelopeParams): Promise<Envelo
   }
 
   const data = await resp.json() as Record<string, unknown>;
+  // @rule:ASE-016 — a 200 that carries an error, or no session id, or no seal, is not an
+  // envelope. Before v0.4.0 it came back as a result with empty strings in it.
+  if (data === null || typeof data !== "object" || data.ok === false) {
+    throw new Error(`issueEnvelope failed: ${String((data as Record<string, unknown> | null)?.error ?? "the answer is not an envelope").slice(0, 200)}`);
+  }
+  if (typeof data.session_id !== "string" || data.session_id === "" ||
+      typeof data.sealed_hash !== "string" || data.sealed_hash === "") {
+    throw new Error("issueEnvelope failed: the answer has no session_id or no sealed_hash");
+  }
   return {
-    session_id:    String(data.session_id ?? ""),
-    agent_id:      String(data.agent_id ?? data.session_id ?? ""),
-    sealed_hash:   String(data.sealed_hash ?? ""),
+    session_id:    data.session_id,
+    agent_id:      String(data.agent_id ?? data.session_id),
+    sealed_hash:   data.sealed_hash,
     issued_at:     String(data.issued_at ?? ""),
     expires_at:    String(data.expires_at ?? ""),
     budget_usd:    Number(data.budget_usd ?? 0),
@@ -105,15 +126,27 @@ export async function verifyEnvelope(
   }
 
   const data = await resp.json() as Record<string, unknown>;
+  if (data === null || typeof data !== "object" || data.ok === false) {
+    throw new Error(`verifyEnvelope failed: ${String((data as Record<string, unknown> | null)?.error ?? "the answer is not an audit").slice(0, 200)}`);
+  }
+  // @rule:ASE-016 — the audit must be for the session that was asked about.
+  if (data.session_id !== sessionId) {
+    throw new Error("verifyEnvelope failed: the audit that came back is for another session, or names none");
+  }
   const drift_set: string[] = Array.isArray(data.drift_set) ? data.drift_set as string[] : [];
   return {
     session_id:        sessionId,
-    verified:          Boolean(data.sealed_hash_verified ?? false),
-    drift_detected:    Boolean(data.drift_detected ?? drift_set.length > 0),
+    // Only the boolean true. Boolean("false") is true, and so is Boolean("tampered").
+    verified:          data.sealed_hash_verified === true,
+    // Drift unless the answer says exactly false AND the list is an empty list (or absent).
+    drift_detected:    drift_set.length > 0 ||
+                       (data.drift_set !== undefined && !Array.isArray(data.drift_set)) ||
+                       (data.drift_detected !== undefined && data.drift_detected !== false),
     drift_set,
     declared_caps:     Array.isArray(data.declared_caps)     ? data.declared_caps as string[]    : [],
     actual_caps_used:  Array.isArray(data.actual_caps_used)  ? data.actual_caps_used as string[] : [],
-    budget_usd:        Number(data.budget_usd       ?? 0),
-    budget_used_usd:   Number(data.budget_used_usd  ?? 0),
+    // The audit route names these budget_allocated and budget_used.
+    budget_usd:        Number(data.budget_usd       ?? data.budget_allocated ?? 0),
+    budget_used_usd:   Number(data.budget_used_usd  ?? data.budget_used      ?? 0),
   };
 }

package/src/idempotency.ts

@@ -1,4 +1,6 @@
 // @rule:AEG-HG-2B-006 — idempotency protects the operation; nonce protects the approval (separate locks)
+// @rule:AEG-HG-2B-009 — a duplicate is a safe no-op only when both fingerprints are known
+//                       and equal; a fingerprint that was never stored proves nothing
 // Pattern: check DB for externalRef before mutating. Matching fingerprint = safe no-op. Mismatch = warn + reject.
 
 import { emitAccReceipt } from './acc-bus.js';
@@ -7,11 +9,21 @@ export interface IdempotencyCheckResult {
   isDuplicate: boolean;
   payloadMismatch: boolean;
   safeNoOp: boolean;
+  /**
+   * False when a record exists but one of the two fingerprints is missing, so the
+   * payloads could not be compared. safeNoOp is then false. Added in v0.4.0.
+   */
+  comparable: boolean;
 }
 
+const isText = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
+
 // Functional helper: does not touch DB. Caller provides existingRecord and fingerprints.
-// When isDuplicate=true and payloadMismatch=false: safeNoOp=true — return existing record, do not re-execute.
+// When isDuplicate=true and payloadMismatch=false and comparable=true: safeNoOp=true —
+//   return existing record, do not re-execute.
 // When isDuplicate=true and payloadMismatch=true: safeNoOp=false — log warning; reject or escalate.
+// When isDuplicate=true and comparable=false: safeNoOp=false — the record exists but nothing
+//   shows the new request is the same one. Before v0.4.0 this case was a safe no-op.
 export function checkIdempotency(
   _externalRef: string,
   existingRecord: unknown,
@@ -20,31 +32,80 @@ export function checkIdempotency(
 ): IdempotencyCheckResult {
   const isDuplicate = existingRecord !== null && existingRecord !== undefined;
   if (!isDuplicate) {
-    return { isDuplicate: false, payloadMismatch: false, safeNoOp: false };
+    return { isDuplicate: false, payloadMismatch: false, safeNoOp: false, comparable: false };
   }
-  const payloadMismatch =
-    existingFingerprint !== undefined && existingFingerprint !== newFingerprint;
+  const comparable = isText(newFingerprint) && isText(existingFingerprint);
+  const payloadMismatch = comparable && existingFingerprint !== newFingerprint;
   const result: IdempotencyCheckResult = {
     isDuplicate: true,
     payloadMismatch,
-    safeNoOp: !payloadMismatch,
+    safeNoOp: comparable && !payloadMismatch,
+    comparable,
   };
+  const ref = String(_externalRef).slice(0, 80);
   emitAccReceipt({
-    receipt_id: `aegis-guard-idem-${_externalRef}`,
-    event_type: payloadMismatch ? 'lock.idempotency.mismatch' : 'lock.idempotency.duplicate',
-    verdict: payloadMismatch ? 'WARN' : 'PASS',
+    receipt_id: `aegis-guard-idem-${ref}`,
+    event_type: !comparable
+      ? 'lock.idempotency.unverifiable'
+      : payloadMismatch ? 'lock.idempotency.mismatch' : 'lock.idempotency.duplicate',
+    verdict: result.safeNoOp ? 'PASS' : 'WARN',
     rules_fired: ['AEG-HG-2B-006'],
-    summary: payloadMismatch
-      ? `duplicate externalRef ${_externalRef} with payload mismatch — caller must reject or escalate`
-      : `duplicate externalRef ${_externalRef} — safe no-op, return existing`,
+    summary: !comparable
+      ? `duplicate externalRef ${ref} with no fingerprint to compare — caller must reject or escalate`
+      : payloadMismatch
+        ? `duplicate externalRef ${ref} with payload mismatch — caller must reject or escalate`
+        : `duplicate externalRef ${ref} — safe no-op, return existing`,
   });
   return result;
 }
 
+// One spelling for one value, at every depth: keys sorted, and the values JSON cannot
+// carry written so that they differ from each other and from null.
+//
+// The values JSON cannot carry are written as an object with one key that starts with "$".
+// So that a payload cannot be written to look like one of them, a real key that starts
+// with "$" gets a second "$" in front: { $bigint: "1" } and 1n do not collide.
+function canonical(v: unknown, seen: Set<object>, fromToJson = false): unknown {
+  if (typeof v === 'bigint') return { $bigint: v.toString() };
+  if (typeof v === 'number' && !Number.isFinite(v)) return { $number: String(v) };
+  if (v === null || typeof v !== 'object') return v;
+  // toJSON is asked once. What it returns is read as data, and its own toJSON is not
+  // called: a value whose toJSON returns itself would otherwise never finish.
+  if (!fromToJson && typeof (v as { toJSON?: unknown }).toJSON === 'function') {
+    return canonical((v as { toJSON: () => unknown }).toJSON(), seen, true);
+  }
+  if (seen.has(v)) throw new Error('buildIdempotencyFingerprint: the payload refers to itself');
+  seen.add(v);
+  let out: unknown;
+  if (Array.isArray(v)) out = v.map((x) => canonical(x, seen));
+  else if (v instanceof Map) out = { $map: [...v.entries()].map(([k, x]) => [canonical(k, seen), canonical(x, seen)]) };
+  else if (v instanceof Set) out = { $set: [...v.values()].map((x) => canonical(x, seen)) };
+  else {
+    const o: Record<string, unknown> = {};
+    for (const k of Object.keys(v).sort()) {
+      const x = (v as Record<string, unknown>)[k];
+      if (typeof x === 'function' || typeof x === 'symbol') continue; // as JSON leaves them out
+      o[k.startsWith('$') ? '$' + k : k] = canonical(x, seen);
+    }
+    out = o;
+  }
+  seen.delete(v);
+  return out;
+}
+
 // Build a stable base64 fingerprint from an arbitrary operation payload.
+//
+// The fingerprint is the payload itself, encoded — not a hash. Whoever can read a stored
+// fingerprint can read the payload. Keep secrets out of it, or hash it before storing.
+//
+// For a flat payload of text, finite numbers, booleans and null the output is the same as
+// before v0.4.0. It differs for: nested objects (their keys are now sorted too), NaN and
+// ±Infinity (were null), bigint (threw), Map and Set (were {}), and a key that starts with
+// "$" (it gets a second "$"). A field set to undefined is the same as the field being
+// absent, as it always was.
 export function buildIdempotencyFingerprint(payload: Record<string, unknown>): string {
-  const sorted = Object.keys(payload)
-    .sort()
-    .reduce<Record<string, unknown>>((acc, k) => { acc[k] = payload[k]; return acc; }, {});
-  return Buffer.from(JSON.stringify(sorted)).toString('base64');
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('buildIdempotencyFingerprint: the payload must be an object of fields');
+  }
+  return Buffer.from(JSON.stringify(canonical(payload, new Set()))).toString('base64');
 }

package/src/index.ts

@@ -1,4 +1,4 @@
-// @rocketlang/aegis-guard — AEGIS Guard SDK public API
+// @xshieldai/aegis-guard — AEGIS Guard SDK public API
 // Five Locks proved in carbonx-backend (batches 62-74). Batch 93 makes them reusable.
 // v0.2.0 adds opt-in Agentic Control Center (ACC) event bus integration.
 

package/src/quality.ts

@@ -35,6 +35,7 @@ const PROMOTION_BIT_MAP: Array<[keyof QualityEvidenceInput, number]> = [
 // @rule:AEG-Q-003 — bits 12-15 are never touched by this function (point-in-time only)
 export function buildQualityMaskAtPromotion(evidence: QualityEvidenceInput): number {
   let mask = 0;
+  if (evidence === null || typeof evidence !== 'object') return mask; // no evidence, no bits
   for (const [field, bit] of PROMOTION_BIT_MAP) {
     if (evidence[field] === true) mask |= (1 << bit);
   }
@@ -58,23 +59,35 @@ const DRIFT_BIT_MAP: Array<[keyof QualityDriftInput, number]> = [
 // @rule:AEG-Q-002 — drift bits 12-15 only; never OR'd with promotion mask into a single field
 export function buildQualityDriftScore(drift: QualityDriftInput): number {
   let score = 0;
+  if (drift === null || typeof drift !== 'object') return score;
   for (const [field, bit] of DRIFT_BIT_MAP) {
     if (drift[field] === true) score |= (1 << bit);
   }
   return score;
 }
 
-// HG group minimum quality mask requirements (promotion bits 0-11 only)
-export const HG_REQUIRED_MASKS = {
+// HG group minimum quality mask requirements (promotion bits 0-11 only).
+// Frozen: the table is exported, and before v0.4.0 any code in the process could lower a
+// bar by assigning to it.
+export const HG_REQUIRED_MASKS = Object.freeze({
   'HG-1':            0x0302,
   'HG-2A':           0x0B83,
   'HG-2B':           0x0FAB,
   'HG-2B-financial': 0x0FFF,
-} as const;
+} as const);
 
 export type HgGroup = keyof typeof HG_REQUIRED_MASKS;
 
+const PROMOTION_BITS = 0x0fff;
+
+// @rule:AEG-Q-003 — a promotion mask is a whole number made of bits 0-11 and nothing else.
+// Anything that is not one does not meet any bar: before v0.4.0 the bitwise test coerced
+// its input, so -1, the text "4095" and 4095.9 all met the financial bar, and so did a
+// mask carrying drift bits.
 export function meetsHgQualityRequirement(hgGroup: HgGroup, qualityMask: number): boolean {
+  if (typeof hgGroup !== 'string' || !Object.prototype.hasOwnProperty.call(HG_REQUIRED_MASKS, hgGroup)) return false;
+  if (typeof qualityMask !== 'number' || !Number.isInteger(qualityMask)) return false;
+  if (qualityMask < 0 || (qualityMask & ~PROMOTION_BITS) !== 0 || qualityMask > PROMOTION_BITS) return false;
   const required = HG_REQUIRED_MASKS[hgGroup];
   return (qualityMask & required) === required;
 }

package/src/sense.ts

@@ -3,6 +3,9 @@
 // @rule:AEG-HG-2B-004 — gate_phase tags event to soak vs live phase
 // @rule:AEG-HG-2B-005 — approval_token_ref must be a digest (digestApprovalToken), never raw token
 
+import { createHash } from 'crypto';
+import { emitAccReceipt } from './acc-bus.js';
+
 export interface AegisSenseEvent {
   event_type: string;
   service_id: string;
@@ -28,19 +31,37 @@ function defaultJsonTransport(event: AegisSenseEvent): void {
 let _transport: SenseTransport = defaultJsonTransport;
 
 export function configureSenseTransport(transport: SenseTransport): void {
-  _transport = transport;
+  _transport = typeof transport === 'function' ? transport : defaultJsonTransport;
+}
+
+// The shape digestApprovalToken() returns: 24 lower-case hex characters.
+const DIGEST = /^[0-9a-f]{24}$/;
+
+// @rule:AEG-HG-2B-005 — the event is the audit record, and an audit record must not hold
+// the thing it audits. A reference that is not already a digest is digested here, so a
+// caller who passes the raw token by mistake does not write it to the log. (Same digest
+// as digestApprovalToken; computed here so this module does not import the token module.)
+function asDigest(ref: unknown): string | undefined {
+  if (ref === undefined || ref === null || ref === '') return undefined;
+  if (typeof ref === 'string' && DIGEST.test(ref)) return ref;
+  return createHash('sha256').update(String(ref)).digest('hex').slice(0, 24);
 }
 
 // @rule:CA-003 — all three snapshot fields are required by the type; callers must supply them.
-// approval_token_ref, if present, must already be the output of digestApprovalToken (AEG-HG-2B-005).
+// The SDK does not check that they are present.
 // @rule:ACC-003 — also emit an ACC receipt for cockpit observability (no-op when bus unset).
+//
+// If the transport throws, this throws: the caller of an irreversible operation should
+// know its audit event was not written. (A bus that throws is different: it is swallowed.)
 export function emitAegisSenseEvent(event: AegisSenseEvent): void {
-  _transport(event);
-  emitAccReceiptFromSense(event);
+  const ref = asDigest(event?.approval_token_ref);
+  const safe: AegisSenseEvent = { ...event };
+  if (ref === undefined) delete safe.approval_token_ref;
+  else safe.approval_token_ref = ref;
+  _transport(safe);
+  emitAccReceiptFromSense(safe);
 }
 
-import { emitAccReceipt } from './acc-bus.js';
-
 function emitAccReceiptFromSense(event: AegisSenseEvent): void {
   emitAccReceipt({
     receipt_id: `aegis-guard-sense-${event.correlation_id || Date.now()}`,

package/src/signing.ts

@@ -1,5 +1,7 @@
 // @rule:AEG-E-016 — approval tokens are AEGIS-signed; an unsigned approval is a forgery
 // @rule:KGT-002 — fail-closed: no key material → verification DENIES, never falls open
+// @rule:AEG-HG-2B-007 — a box that was given a public key to trust never makes a key of its own,
+//                 and a box whose configured keys disagree trusts none of them
 //
 // KGT-T1.1 — Ed25519 JWT signing for approval tokens.
 // Before this module, mintApprovalToken emitted base64url(JSON): any client could
@@ -29,50 +31,92 @@ function aegisDir(): string {
   return process.env.AEGIS_DIR ?? join(process.env.HOME ?? homedir(), '.aegis');
 }
 
-// Cache keyed by resolved dir so tests (which point AEGIS_DIR at a temp dir) and
-// long-lived services both get one disk read, not one per verify.
-let cache: { dir: string; priv: KeyObject | null; pub: KeyObject | null } | null = null;
+// Cache keyed by resolved dir and by the environment key, so tests (which point AEGIS_DIR
+// at a temp dir) and long-lived services both get one disk read, not one per verify.
+// A key FILE that changes under a running process is not noticed until restart.
+interface Keys {
+  dir: string;
+  env: string;
+  priv: KeyObject | null;
+  pub: KeyObject | null;
+  /** Why no key is trusted although key material exists. */
+  conflict: string | null;
+}
+let cache: Keys | null = null;
+
+const pemOf = (k: KeyObject): string => k.export({ type: 'spki', format: 'pem' }).toString();
 
-function loadKeys(): { priv: KeyObject | null; pub: KeyObject | null } {
+function loadKeys(): Keys {
   const dir = aegisDir();
-  if (cache && cache.dir === dir) return cache;
+  const envPem = process.env.AEGIS_APPROVAL_PUBKEY_PEM ?? '';
+  if (cache && cache.dir === dir && cache.env === envPem) return cache;
 
   let priv: KeyObject | null = null;
   let pub: KeyObject | null = null;
+  let conflict: string | null = null;
 
   const keyPath = join(dir, KEY_FILE);
+  const pubPath = join(dir, PUB_FILE);
+
   if (existsSync(keyPath)) {
     try {
       priv = createPrivateKey(readFileSync(keyPath, 'utf8'));
+      if (priv.asymmetricKeyType !== 'ed25519') throw new Error('not an ed25519 key');
       pub = createPublicKey(priv);
-    } catch { priv = null; pub = null; }
+    } catch {
+      priv = null; pub = null;
+      conflict = `${KEY_FILE} exists but is not a usable Ed25519 private key`;
+    }
   }
 
-  // Verifier-only deployments: public key via env PEM or the .pub file.
-  if (!pub) {
-    const envPem = process.env.AEGIS_APPROVAL_PUBKEY_PEM;
-    const pubPath = join(dir, PUB_FILE);
-    try {
-      if (envPem) pub = createPublicKey(envPem);
-      else if (existsSync(pubPath)) pub = createPublicKey(readFileSync(pubPath, 'utf8'));
-    } catch { pub = null; }
+  // Every public key this box has been told about: the file, and the environment.
+  const told: Array<[string, KeyObject]> = [];
+  if (existsSync(pubPath)) {
+    try { told.push([PUB_FILE, createPublicKey(readFileSync(pubPath, 'utf8'))]); }
+    catch { conflict ??= `${PUB_FILE} exists but is not a usable public key`; }
+  }
+  if (envPem) {
+    try { told.push(['AEGIS_APPROVAL_PUBKEY_PEM', createPublicKey(envPem)]); }
+    catch { conflict ??= 'AEGIS_APPROVAL_PUBKEY_PEM is set but is not a usable public key'; }
   }
 
-  cache = { dir, priv, pub };
+  // @rule:AEG-HG-2B-007 — all of them must be the same Ed25519 key. If the private key and a
+  // public key the box was told about disagree, one of them was replaced, and the box
+  // cannot know which: it trusts none.
+  for (const [name, k] of told) {
+    if (k.asymmetricKeyType !== 'ed25519') { conflict ??= `${name} is not an Ed25519 key`; continue; }
+    if (!pub) pub = k;
+    else if (pemOf(pub) !== pemOf(k)) conflict ??= `${name} is a different key from the other key material on this box`;
+  }
+  if (conflict) { priv = null; pub = null; }
+
+  cache = { dir, env: envPem, priv, pub, conflict };
   return cache;
 }
 
-// Generate the per-machine keypair if absent. Called lazily by the mint path and by
-// the AEGIS dashboard at boot (the authority guarantees the key exists on its box).
+// Generate the per-machine keypair if absent. Called by the AEGIS dashboard at boot: the
+// authority guarantees the key exists on its box. It is NOT called by the mint path.
+//
+// @rule:AEG-HG-2B-007 — it refuses on a box that already trusts a public key (the file, or the
+// environment) and has no private key. Such a box is a verifier. Making a key there would
+// replace the authority's key with the box's own, and the box would then accept approvals
+// it signed itself.
 export function ensureSigningKeypair(): { publicKeyPem: string } {
   const dir = aegisDir();
   const keyPath = join(dir, KEY_FILE);
   const pubPath = join(dir, PUB_FILE);
 
   if (!existsSync(keyPath)) {
+    if (existsSync(pubPath) || process.env.AEGIS_APPROVAL_PUBKEY_PEM) {
+      throw new Error(
+        'AEG-HG-2B-007: this box holds a public approval key and no private key — it verifies, it ' +
+        'does not sign. Refusing to generate a keypair over the key it was given.',
+      );
+    }
     const { privateKey, publicKey } = generateKeyPairSync('ed25519');
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    writeFileSync(keyPath, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600 });
+    // 'wx': never write over a key another process made between the check and here.
+    writeFileSync(keyPath, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600, flag: 'wx' });
     writeFileSync(pubPath, publicKey.export({ type: 'spki', format: 'pem' }), { mode: 0o644 });
     cache = null;
   } else if (!existsSync(pubPath)) {
@@ -82,13 +126,14 @@ export function ensureSigningKeypair(): { publicKeyPem: string } {
     cache = null;
   }
 
-  const { pub } = loadKeys();
-  return { publicKeyPem: pub!.export({ type: 'spki', format: 'pem' }).toString() };
+  const { pub, conflict } = loadKeys();
+  if (!pub) throw new Error(`AEG-HG-2B-007: no usable approval signing key${conflict ? ` — ${conflict}` : ''}`);
+  return { publicKeyPem: pemOf(pub) };
 }
 
 export function getPublicKeyPem(): string | null {
   const { pub } = loadKeys();
-  return pub ? pub.export({ type: 'spki', format: 'pem' }).toString() : null;
+  return pub ? pemOf(pub) : null;
 }
 
 function b64url(buf: Buffer | string): string {
@@ -97,13 +142,16 @@ function b64url(buf: Buffer | string): string {
 
 // Sign a payload as a compact EdDSA JWT: b64url(header).b64url(payload).b64url(sig).
 // Throws if no private key — only the AEGIS box (or a box it provisioned) can mint.
+// It never makes a key: before v0.4.0 it did, on any box, at the first mint. The authority
+// calls ensureSigningKeypair() once, at boot.
 export function signApprovalJwt(payload: Record<string, unknown>): string {
-  ensureSigningKeypair();
-  const { priv } = loadKeys();
+  const { priv, conflict } = loadKeys();
   if (!priv) {
     throw new Error(
       'KGT-002: no AEGIS approval signing key — cannot mint (fail-closed). ' +
-      `Expected ${join(aegisDir(), KEY_FILE)}; the AEGIS dashboard (:4850) provisions it at boot.`,
+      (conflict ? `${conflict}. ` : '') +
+      `Expected ${join(aegisDir(), KEY_FILE)}; the AEGIS dashboard (:4850) provisions it at boot ` +
+      'with ensureSigningKeypair().',
     );
   }
   const header = b64url(JSON.stringify({ alg: APPROVAL_JWT_ALG, typ: 'JWT' }));
@@ -120,6 +168,9 @@ export type JwtVerifyResult =
 // Fail-closed on every path: malformed, wrong alg (alg:none forgery), bad signature,
 // or no public key available at all.
 export function verifyApprovalJwt(token: string): JwtVerifyResult {
+  if (typeof token !== 'string' || token.length === 0) {
+    return { ok: false, reason: 'malformed token: not text' };
+  }
   const parts = token.split('.');
   if (parts.length !== 3) {
     return {
@@ -133,7 +184,9 @@ export function verifyApprovalJwt(token: string): JwtVerifyResult {
 
   let alg: unknown;
   try {
-    alg = (JSON.parse(Buffer.from(header, 'base64url').toString('utf8')) as { alg?: unknown }).alg;
+    const h: unknown = JSON.parse(Buffer.from(header, 'base64url').toString('utf8'));
+    if (h === null || typeof h !== 'object' || Array.isArray(h)) throw new Error('not an object');
+    alg = (h as { alg?: unknown }).alg;
   } catch {
     return { ok: false, reason: 'malformed token: header is not base64url JSON' };
   }
@@ -141,26 +194,39 @@ export function verifyApprovalJwt(token: string): JwtVerifyResult {
     return { ok: false, reason: `alg '${String(alg)}' rejected — only ${APPROVAL_JWT_ALG} approvals are trusted` };
   }
 
-  const { pub } = loadKeys();
+  const { pub, conflict } = loadKeys();
   if (!pub) {
     return {
       ok: false,
       reason: 'KGT-002: no AEGIS public key available — verification fails closed. ' +
+        (conflict ? `AEG-HG-2B-007: ${conflict}. ` : '') +
         'Provision ~/.aegis/approval-signing.pub or set AEGIS_APPROVAL_PUBKEY_PEM ' +
         '(GET :4850/api/v2/enforcement/signing-key).',
     };
   }
 
+  // One approval, one spelling: the signature segment must be exactly the 64 bytes in
+  // base64url. The decoder ignores characters it does not know, so without this check
+  // "<token>!!" would verify as well, as a second token with a different digest.
+  const sigBytes = Buffer.from(sig, 'base64url');
+  if (sigBytes.length !== 64 || sigBytes.toString('base64url') !== sig) {
+    return { ok: false, reason: 'signature invalid — token was not minted by AEGIS' };
+  }
+
   let valid = false;
   try {
-    valid = edVerify(null, Buffer.from(`${header}.${body}`), pub, Buffer.from(sig, 'base64url'));
+    valid = edVerify(null, Buffer.from(`${header}.${body}`), pub, sigBytes);
   } catch {
     valid = false;
   }
   if (!valid) return { ok: false, reason: 'signature invalid — token was not minted by AEGIS' };
 
   try {
-    return { ok: true, payload: JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) };
+    const payload: unknown = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+      return { ok: false, reason: 'malformed token: payload is not a JSON object' };
+    }
+    return { ok: true, payload: payload as Record<string, unknown> };
   } catch {
     return { ok: false, reason: 'malformed token: payload is not base64url JSON' };
   }