@openresidency/sdk 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# @openresidency/sdk
+
+Typed client for the OpenResidency API. Dependency-free, uses the global `fetch`
+(Node 18+ or any browser). Every method maps to an endpoint in `docs/openapi.yaml`.
+
+## Install
+
+```bash
+npm install @openresidency/sdk
+```
+
+## Use
+
+```ts
+import { OpenResidencyClient } from '@openresidency/sdk';
+
+// Identity verification is an operator action, so the client needs a credential.
+const client = new OpenResidencyClient({
+  baseUrl: 'https://id.katsina.gov.ng',
+  operatorKey: process.env.OPERATOR_KEY, // ork_..., minted at POST /operator/keys
+});
+
+// Verify a person against the national ID (no residency issued)
+const idv = await client.verifyIdentity({
+  countryCode: 'NG',
+  identifiers: { nin: '12345678901', dateOfBirth: '1990-01-01' },
+  purpose: 'health enrolment',
+});
+
+// Issue a residency credential
+const issued = await client.issueResidency({
+  countryCode: 'NG',
+  subnationalUnit: 'KT',
+  identifiers: { nin: '12345678901', dateOfBirth: '1990-01-01' },
+});
+console.log(issued.residentId, issued.credentialJwt);
+
+// Verify a presented credential (a sector service checking a citizen's residency)
+const check = await client.verifyCredential(issued.credentialJwt!);
+console.log(check.valid, check.subject);
+
+// Consent
+await client.grantConsent({
+  residentId: issued.residentId!,
+  relyingParty: 'health',
+  purpose: 'Enrol in state health scheme',
+  scopes: ['residency', 'health'],
+});
+const consents = await client.listConsents(issued.residentId!);
+```
+
+## Admin endpoints
+
+Pass `adminKey` to reach the registry and audit endpoints:
+
+```ts
+const admin = new OpenResidencyClient({
+  baseUrl: 'https://id.katsina.gov.ng',
+  adminKey: process.env.ADMIN_API_KEY,
+});
+const chain = await admin.verifyAuditChain(); // { ok: true, length: N }
+const page = await admin.listResidents({ countryCode: 'NG', limit: 50 });
+```
+
+## Errors
+
+Non-2xx responses throw `OpenResidencyError` with `status` and parsed `body`.
+
+## Build
+
+```bash
+npm run build
+```
+
+Licensed under Apache-2.0.

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+/**
+ * OpenResidency Interoperability SDK.
+ *
+ * A small, dependency-free typed client for the OpenResidency API. Uses the global
+ * fetch (Node 18+ or any browser). Every method maps one-to-one to an endpoint in
+ * docs/openapi.yaml, so a sector service (Health, Tax, ...) or a partner system can
+ * integrate without hand-writing HTTP calls.
+ */
+export type AssuranceLevel = 'none' | 'basic' | 'verified' | 'high';
+export interface ClientOptions {
+    baseUrl: string;
+    /**
+     * Per-operator API key (`ork_...`), minted at POST /operator/keys.
+     *
+     * This is the credential to use: it identifies WHICH operator is calling, so privileged
+     * actions are attributable in the audit log, it carries only the roles that operator
+     * holds, and it can be rotated with an overlap window rather than a hard cutover.
+     */
+    operatorKey?: string;
+    /**
+     * Legacy shared admin key. Works only where the deployment still runs
+     * `operatorAuth.mode: sharedKey`, and carries no identity or roles. Prefer operatorKey.
+     *
+     * @deprecated Use `operatorKey`.
+     */
+    adminKey?: string;
+    /**
+     * Bearer token from an operator SSO sign-in (`operatorAuth.mode: oidc` or `local`).
+     * Send this when the caller is a person in a console rather than a machine.
+     */
+    operatorToken?: string;
+    /** Optional custom fetch (for tests or non-standard runtimes). */
+    fetch?: typeof fetch;
+}
+export interface IdentityVerifyRequest {
+    countryCode: string;
+    identifiers: Record<string, string>;
+    challengeRef?: string;
+    purpose?: string;
+}
+export interface IdentityVerifyResponse {
+    verified: boolean;
+    assuranceLevel?: AssuranceLevel;
+    subjectRef?: string;
+    attributes?: Record<string, unknown>;
+    pendingChallenge?: boolean;
+    challengeRef?: string;
+    channel?: string;
+    reason?: string;
+}
+export interface IssueRequest {
+    countryCode: string;
+    subnationalUnit: string;
+    identifiers: Record<string, string>;
+    holderId?: string;
+    challengeRef?: string;
+    proofOfResidence?: string;
+    /**
+     * Applicant phone in E.164, for one-time-code delivery. What is retained depends on the
+     * deployment's `contactDirectory.mode`; it never reaches the credential or the audit log.
+     */
+    phone?: string;
+    offline?: boolean;
+}
+export interface IssueResult {
+    status: 'issued' | 'exists' | 'challenge' | 'rejected';
+    residentId?: string;
+    credentialJwt?: string;
+    reason?: string;
+    challenge?: {
+        type: string;
+        channel: string;
+        challengeRef: string;
+    };
+}
+export interface ResidencyStatus {
+    residentId: string;
+    countryCode: string;
+    subnationalUnit: string;
+    assuranceLevel: string;
+    provisional: boolean;
+    createdAt: string;
+}
+export interface CredentialVerifyOutcome {
+    valid: boolean;
+    reason?: string;
+    checkedRevocation?: boolean;
+    subject?: Record<string, unknown>;
+}
+export interface ConsentRecord {
+    id: string;
+    residentId: string;
+    relyingParty: string;
+    purpose: string;
+    scopes: string[];
+    status: 'active' | 'revoked' | 'expired';
+    grantedAt: string;
+    expiresAt?: string;
+    revokedAt?: string;
+    receiptId: string;
+}
+export interface AuditEvent {
+    seq: number;
+    id: string;
+    timestamp: string;
+    action: string;
+    actor: string;
+    target?: string;
+    countryCode?: string;
+    outcome: 'success' | 'failure';
+    metadata?: Record<string, unknown>;
+    prevHash: string;
+    hash: string;
+}
+export declare class OpenResidencyError extends Error {
+    status: number;
+    body: unknown;
+    constructor(status: number, body: unknown);
+}
+export declare class OpenResidencyClient {
+    private baseUrl;
+    private operatorKey?;
+    private adminKey?;
+    private operatorToken?;
+    private doFetch;
+    constructor(opts: ClientOptions);
+    /** Operator action: needs the `registrar` role. */
+    identityChallenge(countryCode: string, identifiers: Record<string, string>): Promise<{
+        challengeRequired: boolean;
+        challengeRef?: string;
+        channel?: string;
+    }>;
+    /** Operator action: needs the `registrar` role. */
+    verifyIdentity(req: IdentityVerifyRequest): Promise<IdentityVerifyResponse>;
+    countries(): Promise<{
+        countryCode: string;
+        countryName: string;
+        provider: string;
+        inputs: unknown[];
+    }[]>;
+    /** Operator action: needs the `registrar` role. */
+    issueResidency(req: IssueRequest): Promise<IssueResult>;
+    residencyStatus(residentId: string): Promise<ResidencyStatus>;
+    verifyCredential(credential: string, offline?: boolean): Promise<CredentialVerifyOutcome>;
+    /** Operator action: needs the `revoker` role. */
+    revokeResidency(residentId: string): Promise<{
+        revoked: boolean;
+    }>;
+    listConsents(residentId: string): Promise<{
+        residentId: string;
+        consents: ConsentRecord[];
+    }>;
+    grantConsent(req: {
+        residentId: string;
+        relyingParty: string;
+        purpose: string;
+        scopes: string[];
+        relyingPartyName?: string;
+        validityDays?: number;
+    }): Promise<{
+        consent: ConsentRecord;
+        receipt: string;
+    }>;
+    revokeConsent(id: string): Promise<{
+        consent: ConsentRecord;
+    }>;
+    listResidents(params?: {
+        countryCode?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        total: number;
+        residents: ResidencyStatus[];
+    }>;
+    auditLog(params?: {
+        limit?: number;
+        offset?: number;
+        target?: string;
+    }): Promise<{
+        count: number;
+        events: AuditEvent[];
+    }>;
+    verifyAuditChain(): Promise<{
+        ok: boolean;
+        length: number;
+        brokenAtSeq?: number;
+    }>;
+    oidcDiscovery(): Promise<Record<string, unknown>>;
+    private get;
+    private post;
+    private request;
+}

package/dist/index.js

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * OpenResidency Interoperability SDK.
+ *
+ * A small, dependency-free typed client for the OpenResidency API. Uses the global
+ * fetch (Node 18+ or any browser). Every method maps one-to-one to an endpoint in
+ * docs/openapi.yaml, so a sector service (Health, Tax, ...) or a partner system can
+ * integrate without hand-writing HTTP calls.
+ */
+export class OpenResidencyError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`OpenResidency API error ${status}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+export class OpenResidencyClient {
+    baseUrl;
+    operatorKey;
+    adminKey;
+    operatorToken;
+    doFetch;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+        this.operatorKey = opts.operatorKey;
+        this.adminKey = opts.adminKey;
+        this.operatorToken = opts.operatorToken;
+        this.doFetch = opts.fetch ?? fetch;
+    }
+    // ---- identity ----
+    /** Operator action: needs the `registrar` role. */
+    identityChallenge(countryCode, identifiers) {
+        return this.post('/identity/challenge', { countryCode, identifiers }, true);
+    }
+    /** Operator action: needs the `registrar` role. */
+    verifyIdentity(req) {
+        return this.post('/identity/verify', req, true);
+    }
+    // ---- residency ----
+    countries() {
+        return this.get('/residency/countries');
+    }
+    /** Operator action: needs the `registrar` role. */
+    issueResidency(req) {
+        return this.post('/residency/issue', req, true);
+    }
+    residencyStatus(residentId) {
+        return this.get(`/residency/${encodeURIComponent(residentId)}`);
+    }
+    verifyCredential(credential, offline = false) {
+        return this.post('/residency/verify', { credential, offline });
+    }
+    /** Operator action: needs the `revoker` role. */
+    revokeResidency(residentId) {
+        return this.post(`/residency/revoke/${encodeURIComponent(residentId)}`, {}, true);
+    }
+    // ---- consent ----
+    // The consent routes are operator-guarded server-side (support role), so they carry
+    // credentials like the admin ones. They previously did not, and 401'd.
+    listConsents(residentId) {
+        return this.get(`/consent/resident/${encodeURIComponent(residentId)}`, true);
+    }
+    grantConsent(req) {
+        return this.post('/consent/grant', req, true);
+    }
+    revokeConsent(id) {
+        return this.post(`/consent/${encodeURIComponent(id)}/revoke`, {}, true);
+    }
+    // ---- admin (operator-authenticated) ----
+    listResidents(params = {}) {
+        const q = new URLSearchParams();
+        if (params.countryCode)
+            q.set('countryCode', params.countryCode);
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        if (params.offset != null)
+            q.set('offset', String(params.offset));
+        return this.get(`/admin/residents?${q.toString()}`, true);
+    }
+    auditLog(params = {}) {
+        const q = new URLSearchParams();
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        if (params.offset != null)
+            q.set('offset', String(params.offset));
+        if (params.target)
+            q.set('target', params.target);
+        return this.get(`/audit?${q.toString()}`, true);
+    }
+    verifyAuditChain() {
+        return this.get('/audit/verify', true);
+    }
+    // ---- discovery ----
+    oidcDiscovery() {
+        return this.get('/oidc/.well-known/openid-configuration');
+    }
+    // ---- internals ----
+    async get(path, admin = false) {
+        return this.request('GET', path, undefined, admin);
+    }
+    async post(path, body, admin = false) {
+        return this.request('POST', path, body, admin);
+    }
+    async request(method, path, body, admin = false) {
+        const headers = { accept: 'application/json' };
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        if (admin) {
+            // Preference order matches how much the deployment can tell about the caller:
+            // an operator key or SSO token names a person; the shared key names nobody.
+            if (this.operatorKey) {
+                headers['x-operator-key'] = this.operatorKey;
+            }
+            else if (this.operatorToken) {
+                headers['authorization'] = `Bearer ${this.operatorToken}`;
+            }
+            else if (this.adminKey) {
+                headers['x-admin-key'] = this.adminKey;
+            }
+            else {
+                throw new Error('This endpoint requires operator authentication: set operatorKey (preferred), ' +
+                    'operatorToken, or the legacy adminKey in ClientOptions');
+            }
+        }
+        const res = await this.doFetch(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        const parsed = text ? JSON.parse(text) : undefined;
+        if (!res.ok)
+            throw new OpenResidencyError(res.status, parsed);
+        return parsed;
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@openresidency/sdk",
+  "version": "0.1.0",
+  "description": "Typed client for the OpenResidency API (identity verification, residency, consent, SSO helpers).",
+  "license": "Apache-2.0",
+  "author": "Chinonso Williams <nonso@harmonizedx.com>",
+  "contributors": [
+    "HarmonizedX Limited"
+  ],
+  "homepage": "https://github.com/Harmonizedx/open-residency",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Harmonizedx/open-residency.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/Harmonizedx/open-residency/issues"
+  },
+  "keywords": [
+    "openresidency",
+    "digital-identity",
+    "verifiable-credentials",
+    "sdk"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}