aa-central-registry

A lightweight TypeScript client to integrate with the Account Aggregator Ecosysetem, Central Registry and Token Issuance Service (Sahamati).
The client handles entity-token generation, admin user token generation (for secret read/reset), secret lifecycle management, entity discovery (AA / FIP / FIU), public-key retrieval and JWT verification.

Package on npm: @s25digital/aa-central-registry
Repository: S25Digital/aa-central-registry

---

Table of Contents

• Why use this package
• Features
• Install
• Quick Start
• Public API (methods)
• Environment variables / Config
• Cache interface
• Examples
• Error handling & troubleshooting
• Security notes
• Contributing
• License
• Resources

---

Why use this package

If your FIU/AA/FIP needs to:

• Discover other participants (base URL, public key, metadata), or
• Programmatically validate tokens issued by other participants, or
• Manage the entity secret lifecycle (read / reset via admin user token),

then this package wraps those Central Registry and Token Issuance Service calls and provides token caching and verification helpers so you don’t have to re-implement the flows. It follows the Sahamati Central Registry & Token Issuance Service APIs.

---

Features

• Generate entity tokens (cached) for Central Registry APIs.
• Generate admin user tokens (for secret read/reset ops).
• Read / reset entity secrets and handle expiry logic.
• Discover entities: list/fetch AAs, FIPs, FIUs (and fetch by id).
• Fetch OIDC certs and convert n/e to PEM for JWT verification (rsa-pem-from-mod-exp).
• Pluggable cache implementation (in-memory default; helpers for Redis available).

---

Install

npm install @s25digital/aa-central-registry
# or
yarn add @s25digital/aa-central-registry

---

Quick Start

import getCRClient, { getRedisCache } from "@s25digital/aa-central-registry";

(async () => {
  // create or reuse a cache (example redis url)
  const cache = await getRedisCache("redis://localhost:6379"); // helper provided

  // create client
  const centralRegistry = getCRClient({
    url: process.env.CR_BASE_URL,
    clientId: process.env.CR_CLIENT_ID,
    tokenUrl: process.env.CR_TOKEN_BASE_URL,
    username: process.env.CR_CLIENT_USERNAME,
    password: process.env.CR_CLIENT_PASSWORD,
    cache,
    loggerLevel: "info"
  });

  // fetch AAs
  const aa = await centralRegistry.getAA();
  console.log(aa);

  // get an entity token
  const tokenResponse = await centralRegistry.getToken();
  console.log(tokenResponse);

  // verify an incoming token
  const verification = await centralRegistry.verifyToken("eyJ...");
  console.log(verification);
})();

---

Public API (methods)

All methods are asynchronous.

• getToken(): returns cached entity token or generates a new one. Returns { status, data: { token, expiry } } or an error-like object.

• getAA(), getFIP(), getFIU(): fetch lists of entities from the Central Registry. Returns { status, data }.

• getAAById(id), getFIPById(id), getFIUById(id): fetch a single entity by id.

• verifyToken(token: string): verifies a JWT by:

  1. decoding to get iss and kid,
  2. fetching issuer OIDC certs, converting n/e to PEM,
  3. verifying with jsonwebtoken. Returns { isVerified: boolean, payload? }.

---

Environment variables / Config

You can pass config explicitly to getCRClient() or rely on environment variables.

• CR_BASE_URL — Base URL of the Central Registry (e.g. https://aacommons.sahamati.org.in)
• CR_CLIENT_ID — Client/entity ID assigned when onboarded
• CR_TOKEN_BASE_URL — Base URL of Sahamati token service
• CR_CLIENT_USERNAME — Admin user username (for secret read/reset)
• CR_CLIENT_PASSWORD — Admin user password
• CR_RESET_SECRET — boolean (optional) — force a reset on startup

If you use the package’s getCRClient() wrapper, the above will be read from process.env if not provided explicitly.

---

Cache interface

The client expects an ICache with these async methods:

interface ICache {
  set(key: string, value: string, ttlSeconds?: number): Promise<boolean>;
  get(key: string): Promise<string | null>;
  remove(key: string): Promise<boolean>;
}

Note: The repo includes an in-memory cache and a Redis helper (getRedisCache(url)). If you provide a custom cache, make sure the set behavior supports TTL.

---

Examples

Get list of AAs

const aaList = await centralRegistry.getAA();
console.log(aaList);

Fetch token and use it

const { data: { token } } = await centralRegistry.getToken();
// use `token` as Authorization header to call other CR-protected APIs

Verify incoming JWT

const { isVerified, payload } = await centralRegistry.verifyToken(incomingToken);
if (!isVerified) {
  // reject request
}

---

License

MIT — see LICENSE in repo.

---

Resources

• Repo: S25Digital/aa-central-registry
• Sahamati Central Registry documentation: https://aacommons.sahamati.org.in

This package is maintained by S25Digital Studio