@xshieldai/aegis-guard 0.2.0 → 0.3.1

package/README.md

@@ -1,4 +1,10 @@
-# @rocketlang/aegis-guard
+# @xshieldai/aegis-guard
+
+> **🔍 Verification status (2026-10-05 IST — v0.3.1)**
+> - **Tests:** ✅ **70/70 passing** in the repository; the npm package ships `src/` only, so run them from a clone ([tests/aegis-guard.test.ts](https://github.com/rocketlang/aegis/blob/master/packages/aegis-guard/tests/aegis-guard.test.ts) — `bun test`)
+> - **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))
+> - **Phase-1 limits:** documented in the v0.2.0 ACC section below
 
 AEGIS Guard SDK — reusable approval-token, nonce, idempotency, SENSE, and quality-evidence primitives for AEGIS-governed services.
 
@@ -19,9 +25,9 @@ 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
 ```
 
 ## Usage
@@ -29,7 +35,7 @@ npm install @rocketlang/aegis-guard
 ### LOCK_1 + LOCK_2 — decision + identity
 
 ```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');
@@ -44,7 +50,7 @@ const payload = verifyScopedApprovalToken(
 ### 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}`));
@@ -67,7 +73,7 @@ emitAegisSenseEvent({
 ### 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 });
@@ -80,7 +86,7 @@ if (isDuplicate && !safeNoOp) throw new Error('payload mismatch on duplicate ext
 ### 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);
@@ -89,7 +95,7 @@ await verifyAndConsumeNonce(payload, redisNonceStore);
 ### Quality evidence
 
 ```typescript
-import { buildQualityMaskAtPromotion, meetsHgQualityRequirement } from '@rocketlang/aegis-guard';
+import { buildQualityMaskAtPromotion, meetsHgQualityRequirement } from '@xshieldai/aegis-guard';
 
 const mask = buildQualityMaskAtPromotion({
   tests_passed: true,
@@ -105,7 +111,7 @@ const ready = meetsHgQualityRequirement('HG-2B-financial', mask);
 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) {
@@ -139,7 +145,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}`),
@@ -194,12 +200,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.2.0",
+  "version": "0.3.1",
   "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",
@@ -42,7 +42,8 @@
   ],
   "scripts": {
     "test": "bun test tests/aegis-guard.test.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "node ../../scripts/publish-guard.mjs"
   },
   "devDependencies": {
     "typescript": "^5.4.0",

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

@@ -6,6 +6,7 @@ import { createHash } from 'crypto';
 import { IrrNoApprovalError } from './errors.js';
 import { type NonceStore, defaultNonceStore } from './nonce.js';
 import { emitAccReceipt } from './acc-bus.js';
+import { signApprovalJwt, verifyApprovalJwt } from './signing.js';
 
 // Token may arrive up to 60s before local clock (NTP tolerance).
 const CLOCK_SKEW_MS = 60_000;
@@ -28,14 +29,18 @@ export function digestApprovalToken(token: string): string {
   return createHash('sha256').update(token).digest('hex').slice(0, 24);
 }
 
-// @rule:AEG-E-016 — test/dev helper: encode a payload as base64url JSON.
-// Production tokens are minted by the AEGIS PROOF system (port 4850), not by services.
+// @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.
 export function mintApprovalToken(payload: ApprovalTokenPayload): string {
-  return Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return signApprovalJwt(payload);
 }
 
 // @rule:AEG-E-016 — token must match service_id + capability + operation exactly.
-// Token format: base64url(JSON). Production replacement: JWT signed by AEGIS key at port 4850.
+// @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.
 export function verifyApprovalToken(
   token: string,
   expectedServiceId: string,
@@ -45,13 +50,11 @@ export function verifyApprovalToken(
   // @rule:ACC-003 @rule:ACC-004 — emit ACC receipt on success OR failure
   const scope = `${expectedServiceId}/${expectedCapability}/${expectedOperation}`;
   try {
-    let payload: ApprovalTokenPayload;
-    try {
-      const decoded = Buffer.from(token, 'base64url').toString('utf8');
-      payload = JSON.parse(decoded) as ApprovalTokenPayload;
-    } catch {
-      throw new IrrNoApprovalError(expectedCapability, 'token could not be decoded');
+    const jwt = verifyApprovalJwt(token);
+    if (!jwt.ok) {
+      throw new IrrNoApprovalError(expectedCapability, `KGT-002: ${jwt.reason}`);
     }
+    const payload = jwt.payload as ApprovalTokenPayload;
 
     if (payload.service_id !== expectedServiceId) {
       throw new IrrNoApprovalError(

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

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.
 
@@ -48,6 +48,19 @@ export {
   verifyScopedApprovalToken,
 } from './approval-token.js';
 
+// @rule:KGT-002 — KGT-T1.1 (v0.3.0): approval tokens are AEGIS-signed EdDSA JWTs.
+// ensureSigningKeypair is called by the AEGIS dashboard at boot (minting authority);
+// verifier-only boxes pin the public key via ~/.aegis/approval-signing.pub or
+// AEGIS_APPROVAL_PUBKEY_PEM (served at :4850 /api/v2/enforcement/signing-key).
+export {
+  APPROVAL_JWT_ALG,
+  type JwtVerifyResult,
+  ensureSigningKeypair,
+  getPublicKeyPem,
+  signApprovalJwt,
+  verifyApprovalJwt,
+} from './signing.js';
+
 export {
   type IssueEnvelopeParams,
   type EnvelopeIssueResult,

package/src/signing.ts

@@ -0,0 +1,172 @@
+// @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
+//
+// KGT-T1.1 — Ed25519 JWT signing for approval tokens.
+// Before this module, mintApprovalToken emitted base64url(JSON): any client could
+// fabricate an "approval". Now AEGIS (:4850, the minting authority) holds the private
+// key; every verifier needs only the public key. Same key-management pattern as
+// kernel/mudrika.ts: persistent per-machine key material under ~/.aegis, mode 600,
+// generated once. Zero-dep — node:crypto ed25519 only.
+
+import {
+  generateKeyPairSync,
+  createPrivateKey,
+  createPublicKey,
+  sign as edSign,
+  verify as edVerify,
+  type KeyObject,
+} from 'crypto';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+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
+
+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;
+
+function loadKeys(): { priv: KeyObject | null; pub: KeyObject | null } {
+  const dir = aegisDir();
+  if (cache && cache.dir === dir) return cache;
+
+  let priv: KeyObject | null = null;
+  let pub: KeyObject | null = null;
+
+  const keyPath = join(dir, KEY_FILE);
+  if (existsSync(keyPath)) {
+    try {
+      priv = createPrivateKey(readFileSync(keyPath, 'utf8'));
+      pub = createPublicKey(priv);
+    } catch { priv = null; pub = null; }
+  }
+
+  // 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; }
+  }
+
+  cache = { dir, priv, pub };
+  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).
+export function ensureSigningKeypair(): { publicKeyPem: string } {
+  const dir = aegisDir();
+  const keyPath = join(dir, KEY_FILE);
+  const pubPath = join(dir, PUB_FILE);
+
+  if (!existsSync(keyPath)) {
+    const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(keyPath, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600 });
+    writeFileSync(pubPath, publicKey.export({ type: 'spki', format: 'pem' }), { mode: 0o644 });
+    cache = null;
+  } else if (!existsSync(pubPath)) {
+    // key exists but pub was lost — re-derive, never regenerate (verifiers may hold the pub)
+    const priv = createPrivateKey(readFileSync(keyPath, 'utf8'));
+    writeFileSync(pubPath, createPublicKey(priv).export({ type: 'spki', format: 'pem' }), { mode: 0o644 });
+    cache = null;
+  }
+
+  const { pub } = loadKeys();
+  return { publicKeyPem: pub!.export({ type: 'spki', format: 'pem' }).toString() };
+}
+
+export function getPublicKeyPem(): string | null {
+  const { pub } = loadKeys();
+  return pub ? pub.export({ type: 'spki', format: 'pem' }).toString() : null;
+}
+
+function b64url(buf: Buffer | string): string {
+  return Buffer.from(buf).toString('base64url');
+}
+
+// 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.
+export function signApprovalJwt(payload: Record<string, unknown>): string {
+  ensureSigningKeypair();
+  const { priv } = 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.`,
+    );
+  }
+  const header = b64url(JSON.stringify({ alg: APPROVAL_JWT_ALG, typ: 'JWT' }));
+  const body = b64url(JSON.stringify(payload));
+  const sig = edSign(null, Buffer.from(`${header}.${body}`), priv);
+  return `${header}.${body}.${b64url(sig)}`;
+}
+
+export type JwtVerifyResult =
+  | { ok: true; payload: Record<string, unknown> }
+  | { ok: false; reason: string };
+
+// Verify signature + structure ONLY (scope/expiry stay in approval-token.ts).
+// 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 {
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    return {
+      ok: false,
+      reason: parts.length === 1
+        ? 'unsigned legacy token rejected — approval tokens are AEGIS-signed JWTs (KGT-T1.1)'
+        : 'malformed token: expected 3 JWT segments',
+    };
+  }
+  const [header, body, sig] = parts;
+
+  let alg: unknown;
+  try {
+    alg = (JSON.parse(Buffer.from(header, 'base64url').toString('utf8')) as { alg?: unknown }).alg;
+  } catch {
+    return { ok: false, reason: 'malformed token: header is not base64url JSON' };
+  }
+  if (alg !== APPROVAL_JWT_ALG) {
+    return { ok: false, reason: `alg '${String(alg)}' rejected — only ${APPROVAL_JWT_ALG} approvals are trusted` };
+  }
+
+  const { pub } = loadKeys();
+  if (!pub) {
+    return {
+      ok: false,
+      reason: 'KGT-002: no AEGIS public key available — verification fails closed. ' +
+        'Provision ~/.aegis/approval-signing.pub or set AEGIS_APPROVAL_PUBKEY_PEM ' +
+        '(GET :4850/api/v2/enforcement/signing-key).',
+    };
+  }
+
+  let valid = false;
+  try {
+    valid = edVerify(null, Buffer.from(`${header}.${body}`), pub, Buffer.from(sig, 'base64url'));
+  } 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')) };
+  } catch {
+    return { ok: false, reason: 'malformed token: payload is not base64url JSON' };
+  }
+}
+
+// test-only: drop the key cache so a test can swap AEGIS_DIR mid-suite
+export function __resetSigningCache(): void {
+  cache = null;
+}