@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

# Pin to an exact version — SDKF-09 forbids wildcard version constraints
npm install @mof-jamaica/[email protected]

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

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

// 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)