gov-finance-authorization-sdk 1.0.0

package/README.md

@@ -0,0 +1,102 @@
+# @mof-jamaica/gov-finance-authorization-sdk
+
+**TypeScript SDK** for the Ministry of Finance Jamaica — Government Financial Authorization & Governance Platform.
+
+**Semantic Freeze: v1.0.0** | **API Compatibility: v1.0.0+**
+
+## Installation
+
+```bash
+# Pin to an exact version — SDKF-09 forbids wildcard version constraints
+npm install @mof-jamaica/gov-finance-authorization-sdk@1.0.0
+```
+
+> **CRITICAL**: SDK version must be pinned exactly (`1.0.0`), not loosely (`^1.0.0`, `~1.0.0`, or `latest`).
+> Wildcard constraints are **unconditionally forbidden** per SDK_SEMANTIC_CONFORMANCE.md SDKF-09
+> and will cause GATE-3 failure in consumer onboarding.
+
+## Quick Start
+
+```typescript
+import { GovFinanceAuthorizationClient } from '@mof-jamaica/gov-finance-authorization-sdk';
+
+const client = new GovFinanceAuthorizationClient({
+  baseUrl: 'https://auth.mof.gov.jm',
+  consumingSystemId: 'my-registered-system-id',  // Must be registered with the platform
+});
+
+// Single authorization
+const result = await client.authorize({
+  actorId: 'real-actor-uuid-here',      // OBL-02: real actor identity required
+  action: 'debt.approve',
+  resource: 'debt_instrument',
+  correlationId: 'caller-uuid-here',    // OBL-01: must be caller-provided, unique per request
+  amount: '5000000.00',                 // SDKF-02: MUST be a string, not a number
+  currency: 'JMD',
+});
+
+// SDKF-01: decision is 'ALLOW' | 'DENY' — never use boolean helpers
+if (result.decision === 'ALLOW') {
+  // OBL-04: store explainability for every decision
+  await myAuditStore.save({ correlationId, explainability: result.explainability });
+  // proceed
+}
+// OBL-05: do NOT retry a DENY as an ALLOW
+// OBL-08: do NOT cache this result — every call requires a live authorization check
+```
+
+## Mandatory Consuming System Obligations
+
+Before going to production, your system must satisfy all 4 onboarding gates.
+See `CONSUMER_ONBOARDING_REQUIREMENTS.md` for the full gate sequence.
+
+| Obligation | Rule |
+|-----------|------|
+| OBL-01 | Always pass a real `correlationId` — do not auto-generate silently |
+| OBL-02 | Always pass a real `actorId` — not `'system'`, `'anonymous'`, etc. |
+| OBL-03 | Send `amount` as a decimal string, never a number |
+| OBL-04 | Store the full `explainability` block for every decision |
+| OBL-05 | Never retry a DENY as an ALLOW |
+| OBL-06 | If this SDK throws, treat the request as **DENY** (fail-closed) |
+| OBL-07 | Pin SDK to an exact version — no wildcards |
+| OBL-08 | Never cache authorization decisions |
+
+## Forbidden Patterns (SDKF-01 through SDKF-10)
+
+| Code | Pattern | Consequence |
+|------|---------|-------------|
+| SDKF-01 | Boolean-only helpers (`isAllowed()`) | Hides decision context; audit gap |
+| SDKF-02 | Float/number for financial amounts | Decimal precision failure (INC-DEC SEV-1) |
+| SDKF-03 | Caching decisions | Stale authorization; access retained after revocation |
+| SDKF-04 | Silent correlationId generation | Breaks replay; audit tracing failure |
+| SDKF-05 | Stripping `explainabilityComplete` | Permanent explainability loss |
+| SDKF-06 | Retry masking (DENY→ALLOW) | Unauthorized access; FAA Act violation |
+| SDKF-07 | Hardcoded role checks alongside API | Policy bypass; security incident |
+| SDKF-08 | Placeholder `actorId` values | Actor identity loss; audit integrity failure |
+| SDKF-09 | Wildcard version constraints | Breaking change propagation without control |
+| SDKF-10 | Silent compatibility downgrade | Semantic drift; undetected breaking changes |
+
+## Replay API
+
+```typescript
+// Verify a historical decision
+const replay = await client.replayByCorrelation({
+  correlationId: 'original-decision-correlation-id',
+  mode: 'VERIFY',
+});
+// replay.result: 'MATCH' | 'DIVERGENCE' | 'INTEGRITY_VIOLATION' | 'AUDIT_RECORD_MISSING'
+
+// Get a human-readable explanation for auditors
+const explain = await client.replayByCorrelation({
+  correlationId: 'original-decision-correlation-id',
+  mode: 'EXPLAIN',
+});
+console.log(explain.explanation);
+```
+
+## Version Contract
+
+This SDK is governed by `GOVERNANCE_COMPATIBILITY_MATRIX.md`. Breaking changes
+require a Governance Change Review Board (GCRB) vote and a 90-day deprecation notice.
+
+Current status: **CURRENT** (v1.0.0, Semantic Freeze v1.0.0)

package/dist/client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * client.ts — SDK HTTP Client
+ *
+ * A minimal, governance-conformant HTTP client for the Ministry of Finance
+ * Government Financial Authorization & Governance Platform API.
+ *
+ * GOVERNANCE RULES ENFORCED BY THIS CLIENT:
+ *   SDK-CT-04: Correlation ID propagated through all requests — caller MUST provide it.
+ *   SDK-CT-02: Decimal amounts preserved as strings — never coerced to numbers.
+ *   SDK-CT-01: All response objects are frozen (Object.freeze) after deserialization.
+ *   SDKF-01:   No boolean-only authorization helpers.
+ *   SDKF-03:   No decision caching — every call makes a live request.
+ *   SDKF-04:   correlationId is never auto-generated silently.
+ *   SDKF-06:   No retry masking — failed requests propagate the error.
+ *   SDKF-09:   Client version is pinned, never a wildcard.
+ *
+ * CONSUMING SYSTEM OBLIGATIONS (CONSUMER_ONBOARDING_REQUIREMENTS.md §2):
+ *   OBL-01: Always pass a real correlationId.
+ *   OBL-02: Always pass a real actorId — not 'system', 'anonymous', etc.
+ *   OBL-04: Store the full explainability block for every decision.
+ *   OBL-05: Never retry a DENY as an ALLOW.
+ *   OBL-06: If this client throws, treat as DENY (fail-closed).
+ *   OBL-07: Pin this SDK to an exact version — no wildcards.
+ *   OBL-08: Never cache the returned decision.
+ */
+import type { AuthorizationRequest, AuthorizationResponse, BulkAuthorizationRequest, BulkAuthorizationResponse, ReplayByCorrelationRequest, ReplayByTimestampRequest, ReplayResponse } from './types';
+export interface GovFinanceClientConfig {
+    /** Base URL of the authorization platform API (e.g. https://auth.mof.gov.jm). */
+    baseUrl: string;
+    /** Registered consuming system ID — required for telemetry labeling. */
+    consumingSystemId: string;
+    /**
+     * HTTP fetch implementation.
+     * Defaults to the global `fetch` (Node 18+, all modern browsers).
+     * Inject a custom implementation for testing or environments without global fetch.
+     */
+    fetch?: typeof globalThis.fetch;
+    /** Request timeout in milliseconds. Defaults to 10000 (10s). */
+    timeoutMs?: number;
+}
+export declare class GovFinanceAuthorizationClient {
+    private readonly baseUrl;
+    private readonly consumingSystemId;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(config: GovFinanceClientConfig);
+    /**
+     * Authorize a single request.
+     *
+     * OBL-01: correlationId must be supplied by caller — this method will throw
+     *         SdkConformanceError if it is missing (SDKF-04 enforcement).
+     * OBL-02: actorId must be a real identity — 'system' and 'anonymous' are rejected.
+     * OBL-08: Decision is NOT cached — every call hits the live API.
+     */
+    authorize(request: AuthorizationRequest): Promise<AuthorizationResponse>;
+    /**
+     * Authorize a batch of sub-requests in a single call.
+     *
+     * Per BULK_AUTHORIZATION_SEMANTICS §7.3: policy set is loaded once server-side
+     * for the entire batch. The consuming system must not split one logical batch
+     * into separate calls to achieve different policy evaluation (SDKF-06).
+     */
+    bulkAuthorize(request: BulkAuthorizationRequest): Promise<BulkAuthorizationResponse>;
+    /**
+     * Replay a historical decision by correlationId.
+     *
+     * VERIFY mode:      re-runs evaluation, returns MATCH or DIVERGENCE.
+     * RECONSTRUCT mode: returns reconstructed context and hash-verified policies.
+     * EXPLAIN mode:     returns all RECONSTRUCT data plus a plain-language narrative.
+     *
+     * All replay operations are READ-ONLY — no events are emitted, no writes occur.
+     */
+    replayByCorrelation(request: ReplayByCorrelationRequest): Promise<ReplayResponse>;
+    /**
+     * Replay the most recent decision for actor+action+resource at or before a timestamp.
+     */
+    replayByTimestamp(request: ReplayByTimestampRequest): Promise<ReplayResponse>;
+    private validateAuthorizationRequest;
+    private validateBulkAuthorizationRequest;
+    private post;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,cAAc,EACf,MAAM,SAAS,CAAC;AAQjB,MAAM,WAAW,sBAAsB;IACrC,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,qBAAa,6BAA6B;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,sBAAsB;IAc1C;;;;;;;OAOG;IACG,SAAS,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAM9E;;;;;;OAMG;IACG,aAAa,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAU1F;;;;;;;;OAQG;IACG,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,cAAc,CAAC;IAMvF;;OAEG;IACG,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC;IAUnF,OAAO,CAAC,4BAA4B;IA0BpC,OAAO,CAAC,gCAAgC;YAsB1B,IAAI;CA4CnB"}

package/dist/client.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * client.ts — SDK HTTP Client
+ *
+ * A minimal, governance-conformant HTTP client for the Ministry of Finance
+ * Government Financial Authorization & Governance Platform API.
+ *
+ * GOVERNANCE RULES ENFORCED BY THIS CLIENT:
+ *   SDK-CT-04: Correlation ID propagated through all requests — caller MUST provide it.
+ *   SDK-CT-02: Decimal amounts preserved as strings — never coerced to numbers.
+ *   SDK-CT-01: All response objects are frozen (Object.freeze) after deserialization.
+ *   SDKF-01:   No boolean-only authorization helpers.
+ *   SDKF-03:   No decision caching — every call makes a live request.
+ *   SDKF-04:   correlationId is never auto-generated silently.
+ *   SDKF-06:   No retry masking — failed requests propagate the error.
+ *   SDKF-09:   Client version is pinned, never a wildcard.
+ *
+ * CONSUMING SYSTEM OBLIGATIONS (CONSUMER_ONBOARDING_REQUIREMENTS.md §2):
+ *   OBL-01: Always pass a real correlationId.
+ *   OBL-02: Always pass a real actorId — not 'system', 'anonymous', etc.
+ *   OBL-04: Store the full explainability block for every decision.
+ *   OBL-05: Never retry a DENY as an ALLOW.
+ *   OBL-06: If this client throws, treat as DENY (fail-closed).
+ *   OBL-07: Pin this SDK to an exact version — no wildcards.
+ *   OBL-08: Never cache the returned decision.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GovFinanceAuthorizationClient = void 0;
+const types_1 = require("./types");
+const errors_1 = require("./errors");
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+class GovFinanceAuthorizationClient {
+    constructor(config) {
+        if (!config.baseUrl)
+            throw new errors_1.SdkConformanceError('baseUrl is required');
+        if (!config.consumingSystemId)
+            throw new errors_1.SdkConformanceError('consumingSystemId is required');
+        this.baseUrl = config.baseUrl.replace(/\/$/, '');
+        this.consumingSystemId = config.consumingSystemId;
+        this.fetchImpl = config.fetch ?? globalThis.fetch;
+        this.timeoutMs = config.timeoutMs ?? 10000;
+    }
+    // ---------------------------------------------------------------------------
+    // Authorization
+    // ---------------------------------------------------------------------------
+    /**
+     * Authorize a single request.
+     *
+     * OBL-01: correlationId must be supplied by caller — this method will throw
+     *         SdkConformanceError if it is missing (SDKF-04 enforcement).
+     * OBL-02: actorId must be a real identity — 'system' and 'anonymous' are rejected.
+     * OBL-08: Decision is NOT cached — every call hits the live API.
+     */
+    async authorize(request) {
+        this.validateAuthorizationRequest(request);
+        const response = await this.post('/api/v1/authorize', request);
+        return Object.freeze(response);
+    }
+    /**
+     * Authorize a batch of sub-requests in a single call.
+     *
+     * Per BULK_AUTHORIZATION_SEMANTICS §7.3: policy set is loaded once server-side
+     * for the entire batch. The consuming system must not split one logical batch
+     * into separate calls to achieve different policy evaluation (SDKF-06).
+     */
+    async bulkAuthorize(request) {
+        this.validateBulkAuthorizationRequest(request);
+        const response = await this.post('/api/v1/authorize/bulk', request);
+        return Object.freeze(response);
+    }
+    // ---------------------------------------------------------------------------
+    // Historical replay
+    // ---------------------------------------------------------------------------
+    /**
+     * Replay a historical decision by correlationId.
+     *
+     * VERIFY mode:      re-runs evaluation, returns MATCH or DIVERGENCE.
+     * RECONSTRUCT mode: returns reconstructed context and hash-verified policies.
+     * EXPLAIN mode:     returns all RECONSTRUCT data plus a plain-language narrative.
+     *
+     * All replay operations are READ-ONLY — no events are emitted, no writes occur.
+     */
+    async replayByCorrelation(request) {
+        if (!request.correlationId)
+            throw new errors_1.SdkConformanceError('correlationId is required for replay');
+        const response = await this.post('/api/v1/replay/by-correlation', request);
+        return Object.freeze(response);
+    }
+    /**
+     * Replay the most recent decision for actor+action+resource at or before a timestamp.
+     */
+    async replayByTimestamp(request) {
+        if (!request.actorId)
+            throw new errors_1.SdkConformanceError('actorId is required for timestamp replay');
+        const response = await this.post('/api/v1/replay/by-timestamp', request);
+        return Object.freeze(response);
+    }
+    // ---------------------------------------------------------------------------
+    // Validation helpers — SDKF enforcement
+    // ---------------------------------------------------------------------------
+    validateAuthorizationRequest(req) {
+        // SDKF-04: correlationId must not be auto-generated silently
+        if (!req.correlationId) {
+            throw new errors_1.SdkConformanceError('SDKF-04 VIOLATION: correlationId is required and must be provided by the caller. ' +
+                'The SDK does not generate correlationIds silently.');
+        }
+        // SDKF-08: actorId must not be a placeholder
+        if (!req.actorId || req.actorId === 'system' || req.actorId === 'anonymous' || req.actorId === 'unknown') {
+            throw new errors_1.SdkConformanceError(`SDKF-08 VIOLATION: actorId='${req.actorId}' is a forbidden placeholder. ` +
+                'Consuming system must assert real actor identity.');
+        }
+        // SDKF-02: amount must be a string if provided
+        if (req.amount !== undefined && typeof req.amount !== 'string') {
+            throw new errors_1.SdkConformanceError(`SDKF-02 VIOLATION: amount must be a decimal string (e.g. "5000000.00"), not a ${typeof req.amount}. ` +
+                'Float and number types are prohibited for financial amounts.');
+        }
+    }
+    validateBulkAuthorizationRequest(req) {
+        if (!req.correlationId) {
+            throw new errors_1.SdkConformanceError('SDKF-04 VIOLATION: correlationId is required for bulk authorization.');
+        }
+        if (!req.actorId || req.actorId === 'system' || req.actorId === 'anonymous') {
+            throw new errors_1.SdkConformanceError(`SDKF-08 VIOLATION: actorId='${req.actorId}' is a forbidden placeholder in bulk authorization.`);
+        }
+        for (const sub of req.requests) {
+            if (sub.amount !== undefined && typeof sub.amount !== 'string') {
+                throw new errors_1.SdkConformanceError(`SDKF-02 VIOLATION: sub-request amount must be a decimal string, not a ${typeof sub.amount}.`);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // HTTP helpers
+    // ---------------------------------------------------------------------------
+    async post(path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Consuming-System': this.consumingSystemId,
+                    'X-SDK-Version': types_1.SDK_VERSION_INFO.version,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timer);
+            // OBL-06: If network fails, the consumer must treat as DENY (fail-closed).
+            // The client throws rather than returning a synthetic ALLOW.
+            throw new Error(`GovernanceClient: network error for ${path} — OBL-06: treat as DENY (fail-closed). ` +
+                `Underlying: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            let detail = '';
+            try {
+                const errorBody = (await response.json());
+                detail = JSON.stringify(errorBody);
+            }
+            catch {
+                // ignore JSON parse errors on error bodies
+            }
+            throw new Error(`GovernanceClient: HTTP ${response.status} from ${path}. Detail: ${detail}`);
+        }
+        return response.json();
+    }
+}
+exports.GovFinanceAuthorizationClient = GovFinanceAuthorizationClient;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * errors.ts — SDK Error Types
+ *
+ * Per SDK_SEMANTIC_CONFORMANCE.md §4.1: SDK must throw structured errors,
+ * never suppress governance failures silently.
+ */
+/**
+ * SdkConformanceError — thrown when the consuming system violates an SDK
+ * conformance rule (SDKF-01 through SDKF-10).
+ *
+ * These errors are programmer errors — they indicate the consuming system
+ * is using the SDK incorrectly. They must not be caught and suppressed.
+ */
+export declare class SdkConformanceError extends Error {
+    readonly code: "SDK_CONFORMANCE_ERROR";
+    constructor(message: string);
+}
+/**
+ * GovernanceApiError — thrown when the authorization API returns a non-2xx
+ * response that is not a validation error.
+ */
+export declare class GovernanceApiError extends Error {
+    readonly statusCode: number;
+    readonly detail?: string | undefined;
+    readonly code: "GOVERNANCE_API_ERROR";
+    constructor(message: string, statusCode: number, detail?: string | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,uBAAuB,CAAU;gBAErC,OAAO,EAAE,MAAM;CAK5B;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAKzB,UAAU,EAAE,MAAM;aAClB,MAAM,CAAC,EAAE,MAAM;IALjC,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAU;gBAG9C,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,YAAA;CAMlC"}

package/dist/errors.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * errors.ts — SDK Error Types
+ *
+ * Per SDK_SEMANTIC_CONFORMANCE.md §4.1: SDK must throw structured errors,
+ * never suppress governance failures silently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GovernanceApiError = exports.SdkConformanceError = void 0;
+/**
+ * SdkConformanceError — thrown when the consuming system violates an SDK
+ * conformance rule (SDKF-01 through SDKF-10).
+ *
+ * These errors are programmer errors — they indicate the consuming system
+ * is using the SDK incorrectly. They must not be caught and suppressed.
+ */
+class SdkConformanceError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = 'SDK_CONFORMANCE_ERROR';
+        this.name = 'SdkConformanceError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.SdkConformanceError = SdkConformanceError;
+/**
+ * GovernanceApiError — thrown when the authorization API returns a non-2xx
+ * response that is not a validation error.
+ */
+class GovernanceApiError extends Error {
+    constructor(message, statusCode, detail) {
+        super(message);
+        this.statusCode = statusCode;
+        this.detail = detail;
+        this.code = 'GOVERNANCE_API_ERROR';
+        this.name = 'GovernanceApiError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.GovernanceApiError = GovernanceApiError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH;;;;;;GAMG;AACH,MAAa,mBAAoB,SAAQ,KAAK;IAG5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,SAAI,GAAG,uBAAgC,CAAC;QAI/C,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AARD,kDAQC;AAED;;;GAGG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAG3C,YACE,OAAe,EACC,UAAkB,EAClB,MAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,eAAU,GAAV,UAAU,CAAQ;QAClB,WAAM,GAAN,MAAM,CAAS;QALxB,SAAI,GAAG,sBAA+B,CAAC;QAQ9C,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAZD,gDAYC"}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @mof-jamaica/gov-finance-authorization-sdk
+ *
+ * TypeScript SDK for the Ministry of Finance Jamaica Government Financial Authorization
+ * & Governance Platform.
+ *
+ * SEMANTIC FREEZE v1.0.0
+ * Compatible with API v1.0.0+
+ *
+ * Usage:
+ *   import { GovFinanceAuthorizationClient } from '@mof-jamaica/gov-finance-authorization-sdk';
+ *
+ *   const client = new GovFinanceAuthorizationClient({
+ *     baseUrl: 'https://auth.mof.gov.jm',
+ *     consumingSystemId: 'my-registered-system',
+ *   });
+ *
+ *   const result = await client.authorize({
+ *     actorId:       'real-actor-uuid',           // OBL-02: must be a real actor identity
+ *     action:        'debt.approve',
+ *     resource:      'debt_instrument',
+ *     correlationId: 'caller-provided-uuid',      // OBL-01: must be caller-provided
+ *     amount:        '5000000.00',                // SDKF-02: decimal string, never a number
+ *     currency:      'JMD',
+ *   });
+ *
+ *   // SDKF-01: use result.decision === 'ALLOW', never a boolean helper
+ *   if (result.decision === 'ALLOW') {
+ *     // OBL-04: store result.explainability for audit records
+ *     await storeExplainability(result.explainability);
+ *     // proceed with the operation
+ *   }
+ *   // OBL-05: do NOT retry a DENY as an ALLOW
+ *   // OBL-08: do NOT cache this result — every call requires a live check
+ */
+export { GovFinanceAuthorizationClient } from './client';
+export { SdkConformanceError, GovernanceApiError } from './errors';
+export { SDK_VERSION_INFO } from './types';
+export type { GovFinanceClientConfig } from './client';
+export type { AuthorizationRequest, AuthorizationResponse, ExplainabilityMetadata, BulkAuthorizationRequest, BulkAuthorizationSubRequest, BulkAuthorizationResponse, BulkSubResult, BulkAuthorizationSummary, ReplayByCorrelationRequest, ReplayByTimestampRequest, ReplayResponse, ReplayPolicyVersion, ReplayMetadata, AuthorizationDecision, WorkflowState, ReplayMode, ReplayResult, DecimalString, SdkVersionInfo, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C,YAAY,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAEvD,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,EAC3B,yBAAyB,EACzB,aAAa,EACb,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,UAAU,EACV,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * @mof-jamaica/gov-finance-authorization-sdk
+ *
+ * TypeScript SDK for the Ministry of Finance Jamaica Government Financial Authorization
+ * & Governance Platform.
+ *
+ * SEMANTIC FREEZE v1.0.0
+ * Compatible with API v1.0.0+
+ *
+ * Usage:
+ *   import { GovFinanceAuthorizationClient } from '@mof-jamaica/gov-finance-authorization-sdk';
+ *
+ *   const client = new GovFinanceAuthorizationClient({
+ *     baseUrl: 'https://auth.mof.gov.jm',
+ *     consumingSystemId: 'my-registered-system',
+ *   });
+ *
+ *   const result = await client.authorize({
+ *     actorId:       'real-actor-uuid',           // OBL-02: must be a real actor identity
+ *     action:        'debt.approve',
+ *     resource:      'debt_instrument',
+ *     correlationId: 'caller-provided-uuid',      // OBL-01: must be caller-provided
+ *     amount:        '5000000.00',                // SDKF-02: decimal string, never a number
+ *     currency:      'JMD',
+ *   });
+ *
+ *   // SDKF-01: use result.decision === 'ALLOW', never a boolean helper
+ *   if (result.decision === 'ALLOW') {
+ *     // OBL-04: store result.explainability for audit records
+ *     await storeExplainability(result.explainability);
+ *     // proceed with the operation
+ *   }
+ *   // OBL-05: do NOT retry a DENY as an ALLOW
+ *   // OBL-08: do NOT cache this result — every call requires a live check
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION_INFO = exports.GovernanceApiError = exports.SdkConformanceError = exports.GovFinanceAuthorizationClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "GovFinanceAuthorizationClient", { enumerable: true, get: function () { return client_1.GovFinanceAuthorizationClient; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "SdkConformanceError", { enumerable: true, get: function () { return errors_1.SdkConformanceError; } });
+Object.defineProperty(exports, "GovernanceApiError", { enumerable: true, get: function () { return errors_1.GovernanceApiError; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "SDK_VERSION_INFO", { enumerable: true, get: function () { return types_1.SDK_VERSION_INFO; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;;;AAEH,mCAAyD;AAAhD,uHAAA,6BAA6B,OAAA;AACtC,mCAAmE;AAA1D,6GAAA,mBAAmB,OAAA;AAAE,4GAAA,kBAAkB,OAAA;AAChD,iCAA2C;AAAlC,yGAAA,gBAAgB,OAAA"}

package/dist/types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * types.ts — SDK Canonical Type Definitions
+ *
+ * Per SDK_SEMANTIC_CONFORMANCE.md §2: all SDK types are immutable after construction.
+ * Per SYSTEM_CONSTITUTION §22: all financial amounts are decimal strings, NEVER numbers.
+ *
+ * SEMANTIC FREEZE v1.0.0 — these types must not change without a GCRB vote.
+ *
+ * SDKF-01: No boolean-only authorization helpers (isAllowed(), canApprove(), etc.)
+ * SDKF-02: No float or number types for financial amounts
+ * SDKF-03: No decision caching at SDK layer
+ * SDKF-04: No silent correlation ID generation
+ * SDKF-05: No stripping of explainabilityComplete field
+ * SDKF-06: No retry masking (retrying a DENY as ALLOW)
+ * SDKF-07: No hardcoded role checks
+ * SDKF-08: No default actorId values
+ * SDKF-09: No wildcard SDK version pinning
+ * SDKF-10: No silent compatibility downgrade
+ */
+/** Authorization decision — string enum per SDKF-01 (no boolean-only helpers). */
+export type AuthorizationDecision = 'ALLOW' | 'DENY';
+/** Canonical workflow states per WORKFLOW_STATE_REGISTRY v1.0-semantic-freeze. */
+export type WorkflowState = 'DRAFT' | 'REVIEW' | 'APPROVED' | 'REJECTED' | 'REVOKED' | 'ARCHIVED';
+/** Replay modes per HISTORICAL_REPLAY_ARCHITECTURE §4.1. */
+export type ReplayMode = 'VERIFY' | 'RECONSTRUCT' | 'EXPLAIN';
+/** Replay result per HISTORICAL_REPLAY_ARCHITECTURE §5.1. */
+export type ReplayResult = 'MATCH' | 'DIVERGENCE' | 'INTEGRITY_VIOLATION' | 'AUDIT_RECORD_MISSING';
+/**
+ * DecimalString — a financial amount encoded as a string.
+ *
+ * GOVERNANCE RULE: amounts MUST be transmitted as strings, never as numbers.
+ * Examples: "5000000.00", "123456.78", "0.01"
+ *
+ * This type alias serves as a semantic marker. Values assigned to this type
+ * must satisfy /^\d+(\.\d+)?$/. Validation is performed server-side per
+ * SDK_SEMANTIC_CONFORMANCE.md SDK-CT-02.
+ *
+ * SDKF-02: Do NOT use number or float for financial amounts.
+ */
+export type DecimalString = string;
+/**
+ * AuthorizationRequest — request body for POST /api/v1/authorize.
+ *
+ * All fields are readonly — immutable after construction per SDK-CT-01.
+ * correlationId MUST be supplied by the caller — never auto-generated (SDKF-04).
+ * actorId MUST be a real actor identity — never a placeholder (SDKF-08).
+ */
+export interface AuthorizationRequest {
+    readonly actorId: string;
+    readonly action: string;
+    readonly resource: string;
+    readonly correlationId: string;
+    readonly resourceId?: string;
+    readonly workflowState?: WorkflowState;
+    readonly organizationId?: string;
+    /** Financial amount — MUST be a DecimalString, never a number (SDKF-02). */
+    readonly amount?: DecimalString;
+    readonly currency?: string;
+    readonly resourceOwnerId?: string;
+    readonly delegationId?: string;
+    readonly additionalClaims?: Readonly<Record<string, unknown>>;
+}
+/**
+ * ExplainabilityMetadata — mandatory in every authorization response.
+ *
+ * Per EXPLAINABILITY_COMPLETENESS_RULES.md EC-01: present in every response.
+ * SDKF-05: explainabilityComplete MUST NOT be stripped by consuming systems.
+ */
+export interface ExplainabilityMetadata {
+    readonly matchedPolicies: readonly string[];
+    readonly failedConditions: readonly string[];
+    readonly evaluationPhaseReached: number;
+    /** SDKF-05: this field is mandatory — do not omit when storing or forwarding. */
+    readonly explainabilityComplete: boolean;
+    readonly explainabilityVersion?: string;
+}
+/**
+ * AuthorizationResponse — response from POST /api/v1/authorize.
+ *
+ * SDKF-01: decision is 'ALLOW' | 'DENY' — not a boolean.
+ * explainability is always present — never undefined (EC-01).
+ */
+export interface AuthorizationResponse {
+    readonly decision: AuthorizationDecision;
+    readonly errorCode?: string;
+    readonly message?: string;
+    /** Always present — SDKF-05 forbids stripping this. */
+    readonly explainability: ExplainabilityMetadata;
+}
+/**
+ * BulkAuthorizationSubRequest — one item in a bulk batch.
+ */
+export interface BulkAuthorizationSubRequest {
+    readonly actorId?: string;
+    readonly action: string;
+    readonly resource: string;
+    readonly resourceId?: string;
+    readonly workflowState?: WorkflowState;
+    readonly amount?: DecimalString;
+    readonly currency?: string;
+    readonly delegationId?: string;
+    readonly additionalClaims?: Readonly<Record<string, unknown>>;
+}
+/**
+ * BulkAuthorizationRequest — request body for POST /api/v1/authorize/bulk.
+ *
+ * actorId is asserted once for the batch (SDKF-08: no placeholder defaults).
+ * correlationId is mandatory per SDK-CT-04.
+ */
+export interface BulkAuthorizationRequest {
+    readonly actorId: string;
+    readonly correlationId: string;
+    readonly requests: readonly BulkAuthorizationSubRequest[];
+}
+/**
+ * BulkSubResult — result for a single item in a bulk batch.
+ * explainability is always present per EC-01.
+ */
+export interface BulkSubResult {
+    readonly index: number;
+    readonly decision: AuthorizationDecision;
+    readonly errorCode?: string;
+    readonly reason?: string;
+    readonly explainability?: ExplainabilityMetadata;
+}
+/**
+ * BulkAuthorizationSummary — aggregate counts for the batch.
+ */
+export interface BulkAuthorizationSummary {
+    readonly requestCount: number;
+    readonly grantedCount: number;
+    readonly deniedCount: number;
+}
+/**
+ * BulkAuthorizationResponse — response from POST /api/v1/authorize/bulk.
+ */
+export interface BulkAuthorizationResponse {
+    readonly results: readonly BulkSubResult[];
+    readonly summary: BulkAuthorizationSummary;
+}
+/**
+ * ReplayByCorrelationRequest — request body for POST /api/v1/replay/by-correlation.
+ */
+export interface ReplayByCorrelationRequest {
+    readonly correlationId: string;
+    readonly mode: ReplayMode;
+}
+/**
+ * ReplayByTimestampRequest — request body for POST /api/v1/replay/by-timestamp.
+ */
+export interface ReplayByTimestampRequest {
+    readonly actorId: string;
+    readonly action: string;
+    readonly resource: string;
+    /** ISO8601 timestamp string. */
+    readonly atOrBefore: string;
+    readonly mode?: ReplayMode;
+}
+/**
+ * ReplayPolicyVersion — one policy version record in a replay response.
+ * hashVerified=true means SHA-256(content) === contentHash was verified.
+ */
+export interface ReplayPolicyVersion {
+    readonly policyId: string;
+    readonly versionNumber: number;
+    readonly policyKey: string;
+    readonly contentHash: string;
+    readonly hashVerified: boolean;
+}
+/**
+ * ReplayMetadata — execution metadata for a replay operation.
+ */
+export interface ReplayMetadata {
+    readonly policiesReconstructed: number;
+    readonly integrityViolations: readonly string[];
+    readonly delegationSnapshotUsed: boolean;
+    readonly auditRecordFound: boolean;
+}
+/**
+ * ReplayResponse — response from all /api/v1/replay/* endpoints.
+ *
+ * VERIFY mode:      result + replayedDecision are populated.
+ * RECONSTRUCT mode: reconstructedContext + reconstructedPolicies are populated.
+ * EXPLAIN mode:     all RECONSTRUCT fields + explanation are populated.
+ */
+export interface ReplayResponse {
+    readonly correlationId: string;
+    readonly mode: ReplayMode;
+    readonly storedDecision: AuthorizationDecision;
+    readonly replayedDecision?: AuthorizationDecision;
+    readonly result?: ReplayResult;
+    readonly originalDecisionAt: string;
+    readonly replayedAt: string;
+    readonly reconstructedContext?: Readonly<Record<string, unknown>>;
+    readonly reconstructedPolicies?: readonly ReplayPolicyVersion[];
+    readonly explanation?: string;
+    readonly evaluationOntologyVersion: string;
+    readonly explainabilitySchemaVersion: string;
+    readonly replayMetadata: ReplayMetadata;
+}
+/**
+ * SdkVersionInfo — version contract information.
+ * Per GOVERNANCE_COMPATIBILITY_MATRIX.md — consuming systems must pin this version.
+ * SDKF-09: Wildcard version constraints are forbidden.
+ */
+export interface SdkVersionInfo {
+    readonly version: string;
+    readonly semanticFreezeVersion: string;
+    readonly apiCompatibilityMinVersion: string;
+    readonly status: 'CURRENT' | 'MAINTENANCE' | 'LEGACY' | 'RETIRED' | 'EXPERIMENTAL';
+    readonly deprecationNotice?: string;
+    readonly retirementDate?: string;
+}
+export declare const SDK_VERSION_INFO: SdkVersionInfo;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * types.ts — SDK Canonical Type Definitions
+ *
+ * Per SDK_SEMANTIC_CONFORMANCE.md §2: all SDK types are immutable after construction.
+ * Per SYSTEM_CONSTITUTION §22: all financial amounts are decimal strings, NEVER numbers.
+ *
+ * SEMANTIC FREEZE v1.0.0 — these types must not change without a GCRB vote.
+ *
+ * SDKF-01: No boolean-only authorization helpers (isAllowed(), canApprove(), etc.)
+ * SDKF-02: No float or number types for financial amounts
+ * SDKF-03: No decision caching at SDK layer
+ * SDKF-04: No silent correlation ID generation
+ * SDKF-05: No stripping of explainabilityComplete field
+ * SDKF-06: No retry masking (retrying a DENY as ALLOW)
+ * SDKF-07: No hardcoded role checks
+ * SDKF-08: No default actorId values
+ * SDKF-09: No wildcard SDK version pinning
+ * SDKF-10: No silent compatibility downgrade
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION_INFO = void 0;
+exports.SDK_VERSION_INFO = {
+    version: '1.0.0',
+    semanticFreezeVersion: '1.0.0',
+    apiCompatibilityMinVersion: '1.0.0',
+    status: 'CURRENT',
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAsPU,QAAA,gBAAgB,GAAmB;IAC9C,OAAO,EAAE,OAAO;IAChB,qBAAqB,EAAE,OAAO;IAC9B,0BAA0B,EAAE,OAAO;IACnC,MAAM,EAAE,SAAS;CAClB,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "gov-finance-authorization-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for the Ministry of Finance Jamaica — Government Financial Authorization & Governance Platform. Provides type-safe, immutable DTOs and semantic-conformance helpers for consuming systems.",
+  "private": false,
+  "license": "UNLICENSED",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "authorization",
+    "governance",
+    "ministry-of-finance",
+    "jamaica",
+    "fintech"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  },
+  "governanceMetadata": {
+    "semanticFreezeVersion": "1.0.0",
+    "openApiHashFile": "../../docs/snapshots/openapi-snapshot-hash.txt",
+    "sdkConformanceSpec": "../../attached_assets/SDK_SEMANTIC_CONFORMANCE.md",
+    "forbiddenPatterns": "SDKF-01 through SDKF-10 — see SDK_SEMANTIC_CONFORMANCE.md §5",
+    "versionPinningRequired": true,
+    "wildcardVersionsForbidden": true
+  }
+}