@xshieldai/aegis-guard 0.5.0 → 0.6.1

package/README.md

@@ -1,11 +1,12 @@
 # @xshieldai/aegis-guard
 
-> **🔍 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`.
+> **🔍 Verification status (2026-10-11 IST — v0.6.1)**
+> - **Tests:** ✅ **184/184 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 114 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, the stated limits and the action digest. 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".
+> - **Upgrading from 0.4.x, 0.5.0 or 0.6.0:** minting needs `AEGIS_MINT_AUTHORITY=1`, an approval must name the concrete action, and since 0.6.1 an action must be plain data. See "Upgrading to 0.6.x".
 
 AEGIS Guard SDK — reusable approval-token, nonce, idempotency, SENSE, and quality-evidence primitives for AEGIS-governed services.
 
@@ -53,7 +54,12 @@ An approval token is an EdDSA-signed JWT. One box signs; every other box only ve
 
 `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 })`.
+Since 0.6.0 two things are refused by default, and the two calls below are therefore not enough on their own:
+
+- **Minting is an authority action.** `mintApprovalToken()` and `ensureSigningKeypair()` throw unless the process declares itself the approving authority with `AEGIS_MINT_AUTHORITY=1`. An agent process verifies; it does not mint. On one user account an agent can set that variable itself: the real boundary is a private key under a different account that the agent cannot read.
+- **An approval must name the concrete action.** A token without an `action_digest` is refused by every verify call, because an approval scoped only to service, capability and operation fits every instance of that operation. Use the action-bound pair described in the next section. `AEGIS_ALLOW_LABEL_ONLY_APPROVAL=1` brings back the old label-only behaviour for a caller that knowingly accepts it.
+
+Mint with `issued_at` and `expires_at` in milliseconds: `mintActionApprovalToken({ service_id, capability, operation, nonce, issued_at: Date.now(), expires_at: Date.now() + 60_000 }, action)`.
 
 ```typescript
 import { verifyApprovalToken, verifyScopedApprovalToken } from '@xshieldai/aegis-guard';
@@ -70,6 +76,25 @@ 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.
 
+### One approval, one action
+
+```typescript
+import { mintActionApprovalToken, verifyActionApprovalToken } from '@xshieldai/aegis-guard';
+
+// On the authority (AEGIS_MINT_AUTHORITY=1): the approval names what was approved.
+const action = { table: 'audit_log_2023', run_at: '2026-10-11T06:40:00.000Z' };
+const token = mintActionApprovalToken({ service_id, capability, operation, nonce, issued_at, expires_at }, action);
+
+// In the service, with the action it is about to perform:
+const payload = verifyActionApprovalToken(token, 'my-service', 'schema', 'drop_table', actionInHand);
+```
+
+The token carries a SHA-256 digest of the action; the service recomputes it from the action in hand and a mismatch is refused. Keys are sorted at every depth, so the order they were written in does not matter.
+
+**An action must be plain data: text, finite numbers, booleans, `null`, arrays and plain objects of these.** Anything else is refused with `IrrNoApprovalError`, at mint and at verify, and the message says where in the action it is (`action.pay.to[0].when is a Date, not a plain object`). That covers `Date`, `URL`, `Map`, `Set`, `RegExp`, `Buffer`, any class instance, `NaN`, `±Infinity`, `undefined` (also as a field's value, and a hole in an array), `bigint`, functions, symbols, and an action that contains itself. Write such a value as text yourself: a date as its ISO text, a URL as its href, a set as a sorted array, a large integer as digits.
+
+Through 0.6.0 the digest gave those values a guessed spelling and the guesses collided: every `Date`, `URL`, `Map`, `Set`, `RegExp` and class instance was written `{}`, and `NaN`, `Infinity` and `undefined` were written `null`. **An approval minted for one such action verified for a different one.** If a service on 0.5.0 or 0.6.0 passes any of those as part of an action, upgrade. For an action that was plain data already, the digest is unchanged, so tokens minted before the upgrade still verify.
+
 ### LOCK_3 — observability (SENSE)
 
 ```typescript
@@ -176,6 +201,13 @@ 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 to 0.6.x
+
+- **0.5.0** added `actionDigest()`, `mintActionApprovalToken()` and `verifyActionApprovalToken()`.
+- **0.6.0: set `AEGIS_MINT_AUTHORITY=1` for the one process that mints**, and for no other. Without it minting and key generation throw. `AEGIS_ALLOW_INSECURE_LOCAL_MINT=1` is the stated opt-out for a single-process development box.
+- **0.6.0: mint and verify with the action-bound pair.** A token with no `action_digest` is refused by `verifyApprovalToken()` and `verifyScopedApprovalToken()` too, unless `AEGIS_ALLOW_LABEL_ONLY_APPROVAL=1`.
+- **0.6.1: an action must be plain data.** A `Date`, `URL`, `Map`, `Set`, `RegExp`, `Buffer`, class instance, `NaN`, `±Infinity`, `undefined` or `bigint` anywhere in an action is now refused, where 0.6.0 digested it (wrongly, see "One approval, one action"). Convert it to text on both sides, the minting side and the verifying side. A `Buffer` was digested correctly before and is refused now as well: write it as hex or base64 text.
+
 ## 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.
@@ -191,6 +223,8 @@ const redisNonceStore: NonceStore = {
 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`.
+- **The package does not decide what "the action" is.** The caller builds it. A field the caller leaves out of the action is not bound, and two services that describe the same act differently do not match.
+- **Verifying an action-bound token does not use it up.** The same token verifies again until it expires; a second use is stopped only by `verifyAndConsumeNonce()`.
 - **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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xshieldai/aegis-guard",
-  "version": "0.5.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",
+  "version": "0.6.1",
+  "description": "AEGIS Guard SDK \u2014 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>",

package/src/approval-token.ts

@@ -4,6 +4,7 @@
 // @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
+// @rule:AEG-HG-2B-010 — an action is plain data or it is refused; the digest never guesses a spelling
 
 import { createHash } from 'crypto';
 import { IrrNoApprovalError } from './errors.js';
@@ -32,6 +33,17 @@ const isText = (v: unknown): v is string => typeof v === 'string' && v.length >
 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-E-016 — action-binding is the ENFORCED default (review point 4, 2026-10-07): a token
+// that does not name the concrete act (no action_digest) is refused, so one approval cannot stand
+// in for every instance. A caller that knowingly accepts the old label-only behaviour sets
+// AEGIS_ALLOW_LABEL_ONLY_APPROVAL=1. (The full match — digest equals the act in hand — is still the
+// job of verifyActionApprovalToken; this base check guarantees no loose token is accepted anywhere.)
+export const LABEL_ONLY_ENV = 'AEGIS_ALLOW_LABEL_ONLY_APPROVAL';
+const labelOnlyAllowed = (): boolean => {
+  const v = process.env[LABEL_ONLY_ENV];
+  return v === '1' || v === 'true' || v === 'yes';
+};
+
 // @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 {
@@ -128,6 +140,16 @@ export function verifyApprovalToken(
     if (payload.nonce !== undefined && !isText(payload.nonce)) {
       throw new IrrNoApprovalError(cap, 'AEG-E-016: token nonce is not text');
     }
+    // Action-binding is the enforced default (point 4): a label-only approval authorises every
+    // instance of the operation, so refuse it unless the caller opted into the old loose behaviour.
+    if (!isText(payload.action_digest) && !labelOnlyAllowed()) {
+      throw new IrrNoApprovalError(
+        cap,
+        `AEG-E-016: approval is not bound to a concrete action (no action_digest) — a label-only ` +
+        `approval authorises every instance. Mint with mintActionApprovalToken()/verify with ` +
+        `verifyActionApprovalToken(), or set ${LABEL_ONLY_ENV}=1 to accept label-only approvals.`,
+      );
+    }
 
     emitAccReceipt({
       receipt_id: `aegis-guard-verify-${digestApprovalToken(token)}`,
@@ -264,21 +286,65 @@ export function verifyScopedApprovalToken(
 // so a token minted without an action_digest cannot pass the action-bound check at all.
 
 // Deterministic JSON: keys sorted, so {a,b} and {b,a} digest the same.
-function stableStringify(v: unknown): string {
-  if (v === null || typeof v !== 'object') return JSON.stringify(v) ?? 'null';
-  if (Array.isArray(v)) return '[' + v.map(stableStringify).join(',') + ']';
-  const o = v as Record<string, unknown>;
-  return '{' + Object.keys(o).sort().map((k) => JSON.stringify(k) + ':' + stableStringify(o[k])).join(',') + '}';
+//
+// @rule:AEG-HG-2B-010 — an action is PLAIN DATA or it is refused: text, finite numbers, booleans,
+// null, arrays of these, and plain objects of these. Through 0.6.0 every other value was given a
+// guessed spelling, and the guesses collided: a Date, a URL, a Set, a Map, a RegExp and any class
+// instance were all written "{}", and NaN, Infinity and undefined were all written "null". An
+// approval minted for one such act then verified for a different one (found 11 October 2026 on
+// the published 0.6.0). The digest does not guess any more. A caller writes such a value as text
+// itself (a date as its ISO text, a URL as its href, a set as a sorted array), so that what was
+// approved is what a person could read.
+//
+// For an action that was plain data already, the digest is the same as in 0.5.0 and 0.6.0.
+function stableStringify(v: unknown, cap: string, at: string, seen: Set<object>): string {
+  const refuse = (what: string): never => {
+    throw new IrrNoApprovalError(
+      cap,
+      `AEG-E-016: the action cannot be bound — ${at} is ${what}. An action must be plain data ` +
+      `(text, finite numbers, booleans, null, arrays and plain objects); write other values as text.`,
+    );
+  };
+  if (v === null || typeof v === 'string' || typeof v === 'boolean') return JSON.stringify(v);
+  if (typeof v === 'number') return Number.isFinite(v) ? JSON.stringify(v) : refuse(`the number ${String(v)}`);
+  if (typeof v !== 'object') return refuse(v === undefined ? 'undefined' : `a ${typeof v}`);
+  if (seen.has(v)) return refuse('a value that contains itself');
+  seen.add(v);
+  let out: string;
+  if (Array.isArray(v)) {
+    const parts: string[] = [];
+    // By index, not map(): map() skips a hole, and a hole is a missing value.
+    for (let i = 0; i < v.length; i++) parts.push(stableStringify(v[i], cap, `${at}[${i}]`, seen));
+    out = '[' + parts.join(',') + ']';
+  } else {
+    const proto = Object.getPrototypeOf(v);
+    if (proto !== Object.prototype && proto !== null) {
+      const name = (proto as { constructor?: { name?: unknown } })?.constructor?.name;
+      refuse(`a ${typeof name === 'string' && name ? name.slice(0, 40) : 'class instance'}, not a plain object`);
+    }
+    if (Object.getOwnPropertySymbols(v).length > 0) refuse('an object with a symbol key');
+    const o = v as Record<string, unknown>;
+    out = '{' + Object.keys(o).sort().map((k) =>
+      JSON.stringify(k) + ':' + stableStringify(o[k], cap, `${at}.${k.slice(0, 40)}`, seen)).join(',') + '}';
+  }
+  seen.delete(v);
+  return out;
+}
+
+function digestFor(action: unknown, cap: string): string {
+  return createHash('sha256').update(stableStringify(action, cap, 'action', new Set())).digest('hex');
 }
 
 // SHA-256 of the canonical action. The caller owns what 'the action' is; the SDK never names domain concepts.
+// Throws IrrNoApprovalError for an action that is not plain data (see AEG-HG-2B-010 above).
 export function actionDigest(action: unknown): string {
-  return createHash('sha256').update(stableStringify(action)).digest('hex');
+  return digestFor(action, 'unknown');
 }
 
 // Mint an approval already bound to a concrete action (adds action_digest to the signed payload).
 export function mintActionApprovalToken(payload: ApprovalTokenPayload, action: unknown): string {
-  return mintApprovalToken({ ...payload, action_digest: actionDigest(action) });
+  const cap = payload !== null && typeof payload === 'object' && isText(payload.capability) ? payload.capability : 'unknown';
+  return mintApprovalToken({ ...payload, action_digest: digestFor(action, cap) });
 }
 
 // Verify an approval against the concrete action in hand. The token MUST carry a matching action_digest;
@@ -292,6 +358,6 @@ export function verifyActionApprovalToken(
 ): ApprovalTokenPayload {
   return verifyScopedApprovalToken(
     token, expectedServiceId, expectedCapability, expectedOperation,
-    { action_digest: actionDigest(action) },
+    { action_digest: digestFor(action, isText(expectedCapability) ? expectedCapability : 'unknown') },
   );
 }

package/src/index.ts

@@ -49,6 +49,7 @@ export {
   actionDigest,
   mintActionApprovalToken,
   verifyActionApprovalToken,
+  LABEL_ONLY_ENV,
 } from './approval-token.js';
 
 // @rule:KGT-002 — KGT-T1.1 (v0.3.0): approval tokens are AEGIS-signed EdDSA JWTs.
@@ -62,6 +63,9 @@ export {
   getPublicKeyPem,
   signApprovalJwt,
   verifyApprovalJwt,
+  mintAllowed,
+  MINT_AUTHORITY_ENV,
+  INSECURE_LOCAL_MINT_ENV,
 } from './signing.js';
 
 export {

package/src/signing.ts

@@ -27,6 +27,25 @@ export const APPROVAL_JWT_ALG = 'EdDSA';
 const KEY_FILE = 'approval-signing.key'; // PKCS8 PEM (private) — mode 600
 const PUB_FILE = 'approval-signing.pub'; // SPKI PEM (public) — mode 644
 
+// @rule:KGT-002 — minting is an AUTHORITY action; separation is the default (review point 1,
+// key leg, 2026-10-07). An ordinary agent process VERIFIES; it does not mint, and it does not
+// make a signing key. Only the designated authority (the AEGIS dashboard, ideally under its own
+// uid) mints — it declares itself with AEGIS_MINT_AUTHORITY=1. A single-process dev box that
+// knowingly accepts the risk sets AEGIS_ALLOW_INSECURE_LOCAL_MINT=1 (explicit opt-out).
+//
+// HONEST CEILING: on one uid a determined agent can set the env itself. The real boundary is the
+// private key living under a DIFFERENT uid the agent cannot read; this gate stops the lazy path
+// (an agent that mints just by calling the SDK), and the OS stops the determined one.
+export const MINT_AUTHORITY_ENV = 'AEGIS_MINT_AUTHORITY';
+export const INSECURE_LOCAL_MINT_ENV = 'AEGIS_ALLOW_INSECURE_LOCAL_MINT';
+const envTrue = (v?: string): boolean => v === '1' || v === 'true' || v === 'yes';
+export const mintAllowed = (): boolean =>
+  envTrue(process.env[MINT_AUTHORITY_ENV]) || envTrue(process.env[INSECURE_LOCAL_MINT_ENV]);
+const MINT_REFUSAL =
+  'KGT-002: minting is an authority action — this process is not the approval authority. Agents verify, ' +
+  'they do not mint. Run the authority (the AEGIS dashboard, ideally under its own uid) with ' +
+  'AEGIS_MINT_AUTHORITY=1, or set AEGIS_ALLOW_INSECURE_LOCAL_MINT=1 to accept single-process minting.';
+
 function aegisDir(): string {
   return process.env.AEGIS_DIR ?? join(process.env.HOME ?? homedir(), '.aegis');
 }
@@ -102,6 +121,8 @@ function loadKeys(): Keys {
 // 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 } {
+  // Making a signing key is an authority action, not something an agent does by calling the SDK.
+  if (!mintAllowed()) throw new Error(MINT_REFUSAL);
   const dir = aegisDir();
   const keyPath = join(dir, KEY_FILE);
   const pubPath = join(dir, PUB_FILE);
@@ -145,6 +166,7 @@ function b64url(buf: Buffer | string): string {
 // 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 {
+  if (!mintAllowed()) throw new Error(MINT_REFUSAL);
   const { priv, conflict } = loadKeys();
   if (!priv) {
     throw new Error(