nestjs-ddd-cli 3.3.1 → 3.4.0

package/dist/templates/recipes/platform-parc-bound-authorization/README.md.hbs

@@ -90,3 +90,33 @@ are bounded at 16 KiB under a five-second deadline; redirects are refused.
 Receipts must bind the exact scope, operation and resource and expire within
 PARC's five-second bound. Never cache/reuse them as durable permissions. A failed
 request may already have consumed its lease; obtain fresh authority explicitly.
+
+## Scoped grant shadow comparison
+
+Deploy a PARC version accepting optional `shadowContext` before opting a consumer
+into `shadowFacts`. Omit the option for unchanged wire compatibility with older
+PARC installations. The receipt, allow/deny decision, expiry and owner commit
+checks remain unchanged. There is no client-side grant evaluator.
+
+```typescript
+const receipt = await parc.check({
+  // ...the existing lease, credential, permission, action, resource and expected scope
+  contextDigest: digestOfOwnerVerifiedOperation,
+  shadowFacts: { amountMinor: persistedOperation.amountMinor, currency: persistedOperation.currency },
+});
+```
+
+The operation digest must cover these exact facts and the resource/version being
+authorized. Read them from persisted or independently verified owner state, never
+copy amount, currency or policy claims from browser headers. PARC accepts facts
+only from the admitted service owning the permission. Amounts are canonical
+unsigned integer strings of at most 38 digits; currency is three uppercase
+letters. Invalid optional facts produce an invalid shadow observation and do not
+change the existing decision. No facts are included in the returned receipt.
+
+PARC compares imported grants against legacy decisions separately from proposed
+resource, amount and expiry restrictions. Intentional proposal differences are
+not compatibility failures. Reports include unobserved decisions; an empty
+window, missing observations or only denied requests cannot prove full parity.
+Role/proposal administration stays in the governed PARC console, never this
+consumer client. Keep legacy enforcement until the scoped rollout is proven.

package/dist/templates/recipes/platform-parc-bound-authorization/client.ts.hbs

@@ -1,5 +1,18 @@
 import { BoundedJsonHttpClient } from '../../auth/oauth2-token-introspection/bounded-json-http.client';
 
+export interface ParcShadowFacts {
+  /** Canonical integer string, never a floating-point amount. */
+  amountMinor: string;
+  currency: string;
+}
+
+/** Optional diagnostic facts. They cannot alter or replace the bound receipt. */
+function shadowContext(facts: ParcShadowFacts, contextDigest: string) {
+  if (!facts || typeof facts.amountMinor !== 'string' || !/^(0|[1-9][0-9]{0,37})$/.test(facts.amountMinor) ||
+      typeof facts.currency !== 'string' || !/^[A-Z]{3}$/.test(facts.currency)) return null;
+  return { contractVersion: 1, contextDigest, facts: { amountMinor: facts.amountMinor, currency: facts.currency } };
+}
+
 export interface ParcBoundRequest {
   /** Fresh opaque SA lease. PARC consumes it; do not introspect it first. */
   lease: string;
@@ -10,6 +23,9 @@ export interface ParcBoundRequest {
   resource: { type: string; id: string };
   /** SHA-256 of the owner-verified operation material. */
   contextDigest: string;
+  /** Opt-in shadow comparison only. Read from the same owner material covered by contextDigest.
+   * Enable only after the receiving PARC API supports shadowContext. */
+  shadowFacts?: ParcShadowFacts;
   /** Persisted owner scope or an untrusted route selector; trusted only after exact receipt matching. */
   expected: { businessId: string; clientAppId: string; subjectId?: string };
 }
@@ -75,6 +91,10 @@ export class ParcBoundAuthorizationClient {
     };
     if (typeof request.contextDigest !== 'string' ||
         !/^[a-f0-9]{64}$/.test(request.contextDigest)) this.invalid();
+    // Invalid optional facts are recorded as invalid shadow context without changing enforcement.
+    const payload = input.shadowFacts === undefined ? request : {
+      ...request, shadowContext: shadowContext(input.shadowFacts, request.contextDigest),
+    };
     const expected = {
       businessId: this.id(input?.expected?.businessId),
       clientAppId: this.id(input?.expected?.clientAppId),
@@ -92,7 +112,7 @@ export class ParcBoundAuthorizationClient {
           'x-request-context-lease': lease,
           'x-service-access-credential': credential,
         },
-      }).postJson(['v1', 'decisions', 'check-bound'], request);
+      }).postJson(['v1', 'decisions', 'check-bound'], payload);
     } catch { throw new ParcBoundAuthorizationError('unavailable'); }
     this.requireTls();
     const fail = (): never => { throw new ParcBoundAuthorizationError('invalid_receipt'); };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-ddd-cli",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "description": "CLI for generating NestJS DDD boilerplate code",
   "main": "dist/index.js",
   "bin": {