@comms-id/sanctions

Typed client for the Comms.ID Sanctions API (https://api.comms.id/dfat-sanctions-consolidated-list/v1): screening of one individual, entity or vessel against the Australian Sanctions Consolidated List.

src/ is generated from the Sanctions contract (packages/dfat-consolidated-list/openapi/dfat-sanctions-consolidated-list.v1.json) by @comms-id/forge-transformers. Do not edit it: change the contract and run pnpm --filter @comms-id/forge-transformers generate.

import { createDfatSanctionsConsolidatedListClient } from "@comms-id/dfat-sanctions-consolidated-list/server";

const client = createDfatSanctionsConsolidatedListClient({
  clientId: process.env.COMMS_ID_CLIENT_ID!,
  privateJwk: JSON.parse(process.env.COMMS_ID_PRIVATE_JWK!),
});
const reply = await client.screen({"type": "Individual", "name": "Example Person", "dateOfBirth": "1970-06-15"});

Operations

• screen: Screen one individual, entity or vessel against the Australian Sanctions Consolidated List (DFAT): exact names and aliases, optionally narrowed by date and place of birth. The reply carries every possible match with its evidence, the list generation and its freshness. It refuses to answer from a stale list.

Every operation is a read, safe to repeat, and is retried after a retryable failure. A reply that is not a match is one of the outcomes of the reply convention: an error with outcomeOf(error) of no-match, source-unavailable or failed; an outage is never a "no match".

Test it first

createDfatSanctionsConsolidatedListFixtureClient() from @comms-id/dfat-sanctions-consolidated-list/fixtures answers from the contract's own examples with no network and says so (fixture: true). To call the TEST service (synthetic replies, your development app's key), pass environment: "test"; going live changes only the environment and the key.

Server only

Sanctions screening is not open to a browser holding no credential: call it from your own server, or through a relay (@comms-id/relay). ./browser takes your relay route and never signs.

COMMS_ID_PRIVATE_JWK is an ML-DSA-87 private JWK (kty AKP, with priv and pub). The server entry needs Node.js 24.7 or later, or a Cloudflare Worker with the compatibility flag webcrypto_modern_algorithms.

Entries: . (types and errors, safe in a browser), ./server (signs each call), ./browser (your relay route; never signs), ./fixtures (LOCAL FIXTURES, no network), ./descriptor (what @comms-id/relay may forward).

LICENSE is the consumer client licence.

The form

@comms-id/dfat-sanctions-consolidated-list/controller is the headless controller of a sanctions screening form: values, checks, one explicit submit, the answer, errors and retry, with the accessibility attributes of a labelled form. It has no framework and no DOM. @comms-id/dfat-sanctions-consolidated-list-react (a hook and a component) and <comms-id-dfat-sanctions-consolidated-list> (a web element) run on it, and so can your own UI.

import { createDfatSanctionsConsolidatedListController } from "@comms-id/dfat-sanctions-consolidated-list/controller";

const controller = createDfatSanctionsConsolidatedListController({ client, onResult: (record, timing) => console.log(record, timing.ms) });
controller.subscribe(() => render(controller.getState()));
controller.setValue("name", "…");
controller.submit();

src/local/profile.ts is the only product-specific part: it lists the fields, checks the values, prepares the call and says the reply in plain words. Everything else is generated. Like the client itself, the form is for your server or your relay: screening is never open to a browser that holds no credential.