@xshieldai/aegis-guard 0.4.0 → 0.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xshieldai/aegis-guard",
-  "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",
+  "version": "0.6.0",
+  "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

@@ -23,6 +23,7 @@ export interface ApprovalTokenPayload {
   issued_by?: string;
   nonce?: string;
   status?: 'approved' | 'revoked' | 'denied';
+  action_digest?: string; // @rule:AEG-E-016 — binds the token to the CONCRETE act, not just its label
   [key: string]: unknown;
 }
 
@@ -31,6 +32,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 {
@@ -127,6 +139,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)}`,
@@ -253,3 +275,44 @@ export function verifyScopedApprovalToken(
 
   return payload;
 }
+
+// @rule:AEG-E-016 — bind an approval to the CONCRETE act, not just its label.
+// An independent review (Oct 2026) showed a token scoped only to service/capability/operation
+// approves ANY instance of that operation: one 'drop_table' approval drops any table. The fix is a
+// digest of the concrete action (which table, which amount, which recipient) carried in the signed
+// payload as action_digest; the gate recomputes it from the act in hand and refuses a mismatch.
+// This rides the existing, hardened verifyScopedApprovalToken (a field with no token value refuses),
+// 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(',') + '}';
+}
+
+// SHA-256 of the canonical action. The caller owns what 'the action' is; the SDK never names domain concepts.
+export function actionDigest(action: unknown): string {
+  return createHash('sha256').update(stableStringify(action)).digest('hex');
+}
+
+// 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) });
+}
+
+// Verify an approval against the concrete action in hand. The token MUST carry a matching action_digest;
+// a label-only token (no action_digest) is refused here, closing "one approval fits every instance".
+export function verifyActionApprovalToken(
+  token: string,
+  expectedServiceId: string,
+  expectedCapability: string,
+  expectedOperation: string,
+  action: unknown,
+): ApprovalTokenPayload {
+  return verifyScopedApprovalToken(
+    token, expectedServiceId, expectedCapability, expectedOperation,
+    { action_digest: actionDigest(action) },
+  );
+}

package/src/index.ts

@@ -46,6 +46,10 @@ export {
   verifyApprovalToken,
   verifyAndConsumeNonce,
   verifyScopedApprovalToken,
+  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.
@@ -59,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(