@xshieldai/aegis-guard 0.5.0 → 0.6.0

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.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

@@ -32,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 {
@@ -128,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)}`,

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(