@openresidency/sdk 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,12 +1,3 @@
-// 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;
@@ -16,6 +7,9 @@ export class OpenResidencyError extends Error {
         this.body = body;
     }
 }
+// ---------------------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------------------
 export class OpenResidencyClient {
     baseUrl;
     operatorKey;
@@ -29,110 +23,369 @@ export class OpenResidencyClient {
         this.operatorToken = opts.operatorToken;
         this.doFetch = opts.fetch ?? fetch;
     }
+    // ---- the whole contract ----
+    /**
+     * Call any operation in docs/openapi.yaml. Path parameters, query, body and the
+     * response are typed from the generated contract:
+     *
+     * ```ts
+     * const rel = await client.request('get', '/residency/{residentId}/relationship', {
+     *   path: { residentId },
+     * });
+     * ```
+     */
+    request(method, path, ...args) {
+        const opts = (args[0] ?? {});
+        return this.send(method, path, opts);
+    }
+    // ---- health ----
+    live() {
+        return this.request('get', '/health/live', { auth: 'none' });
+    }
+    ready() {
+        return this.request('get', '/health/ready', { auth: 'none' });
+    }
     // ---- identity ----
     /** Operator action: needs the `registrar` role. */
     identityChallenge(countryCode, identifiers) {
-        return this.post('/identity/challenge', { countryCode, identifiers }, true);
+        return this.send('post', '/identity/challenge', {
+            body: { countryCode, identifiers },
+            auth: 'operator',
+        });
     }
     /** Operator action: needs the `registrar` role. */
     verifyIdentity(req) {
-        return this.post('/identity/verify', req, true);
+        return this.send('post', '/identity/verify', { body: req, auth: 'operator' });
     }
     // ---- residency ----
     countries() {
-        return this.get('/residency/countries');
+        return this.send('get', '/residency/countries', { auth: 'none' });
     }
     /** Operator action: needs the `registrar` role. */
     issueResidency(req) {
-        return this.post('/residency/issue', req, true);
+        return this.send('post', '/residency/issue', { body: req, auth: 'operator' });
     }
     residencyStatus(residentId) {
-        return this.get(`/residency/${encodeURIComponent(residentId)}`);
+        return this.send('get', '/residency/{residentId}', { path: { residentId } });
     }
     verifyCredential(credential, offline = false) {
-        return this.post('/residency/verify', { credential, offline });
+        return this.send('post', '/residency/verify', {
+            body: { credential, offline },
+        });
     }
     /** Operator action: needs the `revoker` role. */
     revokeResidency(residentId) {
-        return this.post(`/residency/revoke/${encodeURIComponent(residentId)}`, {}, true);
+        return this.send('post', '/residency/revoke/{residentId}', {
+            path: { residentId },
+            body: {},
+            auth: 'operator',
+        });
+    }
+    /** Operator action: needs the `admin` role. Revokes first, then destroys personal data. */
+    eraseResidency(residentId, body) {
+        return this.request('post', '/residency/{residentId}/erase', {
+            path: { residentId },
+            body,
+            auth: 'operator',
+        });
+    }
+    /** Operator action. Erases records whose retention period has ended. */
+    retentionSweep(body) {
+        return this.request('post', '/residency/retention/sweep', { body, auth: 'operator' });
+    }
+    /** Operator action. Expires provisional registrations that were never completed. */
+    provisionalSweep(body) {
+        return this.request('post', '/residency/provisional/sweep', { body, auth: 'operator' });
+    }
+    /** Operator action. Re-verifies a resident against the foundational source. */
+    reconcile(residentId, body) {
+        return this.request('post', '/residency/{residentId}/reconcile', {
+            path: { residentId },
+            body,
+            auth: 'operator',
+        });
+    }
+    // ---- relationship and credential lifecycle (ORCS §6, §10) ----
+    /** The relationship's ORCS state and how it got there. */
+    relationship(residentId) {
+        return this.request('get', '/residency/{residentId}/relationship', { path: { residentId } });
+    }
+    /** Operator action. Move the relationship to a new ORCS state. */
+    transitionRelationship(residentId, body) {
+        return this.request('post', '/residency/{residentId}/relationship/transition', {
+            path: { residentId },
+            body,
+            auth: 'operator',
+        });
+    }
+    /** The credential's ORCS status. */
+    credential(residentId) {
+        return this.request('get', '/residency/{residentId}/credential', { path: { residentId } });
+    }
+    /** Operator action. Move the credential to a new ORCS status. */
+    transitionCredential(residentId, body) {
+        return this.request('post', '/residency/{residentId}/credential/transition', {
+            path: { residentId },
+            body,
+            auth: 'operator',
+        });
+    }
+    /** Why an application was refused, and how to appeal. */
+    refusal(reference) {
+        return this.request('get', '/residency/refusals/{reference}', { path: { reference } });
+    }
+    /** Operator action. Record the outcome of reviewing a refusal. */
+    reviewRefusal(reference, body) {
+        return this.request('post', '/residency/refusals/{reference}/review', {
+            path: { reference },
+            body,
+            auth: 'operator',
+        });
     }
-    // ---- consent ----
+    // ---- assurance (ORCS §7) ----
+    assuranceProfiles() {
+        return this.request('get', '/assurance/profiles', { auth: 'none' });
+    }
+    assuranceMappings() {
+        return this.request('get', '/assurance/mappings', { auth: 'none' });
+    }
+    /** Resolve a source-specific assurance value to the ORCS assurance profile. */
+    resolveAssurance(value) {
+        return this.request('get', '/assurance/resolve/{value}', { path: { value }, auth: 'none' });
+    }
+    residentAssurance(residentId) {
+        return this.request('get', '/residency/{residentId}/assurance', { path: { residentId } });
+    }
+    // ---- consent (ORCS §9) ----
     // 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);
+        return this.send('get', '/consent/resident/{residentId}', {
+            path: { residentId },
+            auth: 'operator',
+        });
     }
     grantConsent(req) {
-        return this.post('/consent/grant', req, true);
+        return this.send('post', '/consent/grant', { body: req, auth: 'operator' });
     }
     revokeConsent(id) {
-        return this.post(`/consent/${encodeURIComponent(id)}/revoke`, {}, true);
+        return this.send('post', '/consent/{id}/revoke', { path: { id }, body: {}, auth: 'operator' });
+    }
+    legalBases() {
+        return this.request('get', '/consent/legal-bases');
+    }
+    legalBasis(id) {
+        return this.request('get', '/consent/legal-bases/{id}', { path: { id } });
+    }
+    /** Operator action. Withdraw a legal basis; consents resting on it stop being valid. */
+    deactivateLegalBasis(id, body) {
+        return this.request('post', '/consent/legal-bases/{id}/deactivate', { path: { id }, body, auth: 'operator' });
+    }
+    // ---- operator identity ----
+    /** Local sign-in (`operatorAuth.mode: local`). The token goes in `ClientOptions.operatorToken`. */
+    operatorLogin(body) {
+        return this.request('post', '/operator/login', { body, auth: 'none' });
+    }
+    /** The calling operator's identity and roles. */
+    me() {
+        return this.request('get', '/operator/me', { auth: 'operator' });
     }
-    // ---- admin (operator-authenticated) ----
+    listOperators() {
+        return this.request('get', '/operator/operators', { auth: 'operator' });
+    }
+    createOperator(body) {
+        return this.request('post', '/operator/operators', { body, auth: 'operator' });
+    }
+    /** Disable (or with `disabled: false`, re-enable) an operator account. Needs the `admin` role. */
+    disableOperator(operatorId, disabled = true) {
+        return this.request('post', '/operator/operators/{id}/disable', {
+            path: { id: operatorId },
+            body: { disabled },
+            auth: 'operator',
+        });
+    }
+    listKeys() {
+        return this.request('get', '/operator/keys', { auth: 'operator' });
+    }
+    /** Mint a per-operator API key. The secret is returned once. */
+    createKey(body) {
+        return this.request('post', '/operator/keys', { body, auth: 'operator' });
+    }
+    /** Mint a replacement key; the old one keeps working for the overlap window. */
+    rotateKey(body) {
+        return this.request('post', '/operator/keys/rotate', { body, auth: 'operator' });
+    }
+    revokeKey(body) {
+        return this.request('post', '/operator/keys/revoke', { body, auth: 'operator' });
+    }
+    // ---- audit and 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);
+        return this.send('get', '/admin/residents', { query: params, auth: 'operator' });
     }
     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);
+        return this.send('get', '/audit', { query: params, auth: 'operator' });
     }
     verifyAuditChain() {
-        return this.get('/audit/verify', true);
+        return this.send('get', '/audit/verify', { auth: 'operator' });
+    }
+    /** Counts by country. */
+    stats() {
+        return this.request('get', '/admin/stats', { auth: 'operator' });
+    }
+    /** Aggregate, non-PII statistics (the open-data surface), as JSON. */
+    statistics(query) {
+        return this.request('get', '/admin/statistics', { query, auth: 'operator' });
+    }
+    /** The same report as RFC 4180 CSV. */
+    statisticsCsv(query) {
+        return this.request('get', '/admin/statistics.csv', { query, auth: 'operator', accept: 'text/csv' });
+    }
+    // ---- offline ----
+    /** Render a credential as an SVG QR for paper or low-connectivity carriage. */
+    qr(body) {
+        return this.request('post', '/offline/qr', { body });
+    }
+    /** The USSD aggregator webhook. `secret` is the shared USSD_GATEWAY_SECRET. */
+    ussd(body, secret) {
+        return this.request('post', '/offline/ussd', { body, auth: { headers: { 'x-ussd-secret': secret } } });
+    }
+    // ---- OpenID4VCI: issuing into a wallet ----
+    credentialIssuerMetadata() {
+        return this.request('get', '/.well-known/openid-credential-issuer', { auth: 'none' });
+    }
+    oauthAuthorizationServerMetadata() {
+        return this.request('get', '/.well-known/oauth-authorization-server', { auth: 'none' });
+    }
+    /** Operator action. Create a credential offer for a resident's wallet to redeem. */
+    createCredentialOffer(body) {
+        return this.request('post', '/openid4vci/offer', { body, auth: 'operator' });
+    }
+    /** The wallet side: exchange the pre-authorized code for an access token. */
+    walletToken(body) {
+        return this.request('post', '/openid4vci/token', { body, auth: 'none' });
+    }
+    walletNonce() {
+        return this.request('post', '/openid4vci/nonce', { auth: 'none' });
+    }
+    /** The wallet side: obtain the credential with the access token from `walletToken`. */
+    walletCredential(accessToken, body) {
+        return this.request('post', '/openid4vci/credential', { body, auth: { bearer: accessToken } });
+    }
+    // ---- OpenID4VP: asking a wallet to present ----
+    /** Create a presentation request for a wallet to answer. */
+    createPresentationRequest(body) {
+        return this.request('post', '/openid4vp/request', { body });
+    }
+    /** The request object a wallet fetches (the `request_uri`). */
+    presentationRequest(id) {
+        return this.request('get', '/openid4vp/request/{id}', { path: { id }, auth: 'none' });
+    }
+    /** The wallet side: submit the presentation. */
+    submitPresentation(id, body) {
+        return this.request('post', '/openid4vp/response/{id}', { path: { id }, body, auth: 'none' });
+    }
+    /** What the wallet presented, once it has. */
+    presentationResult(id) {
+        return this.request('get', '/openid4vp/result/{id}', { path: { id } });
+    }
+    // ---- W3C VC-API ----
+    /** Operator action. Issue a credential through the VC-API issuer interface. */
+    vcIssue(body) {
+        return this.request('post', '/credentials/issue', { body, auth: 'operator' });
+    }
+    /** Verify a Verifiable Credential (JWT or Data Integrity) through the VC-API verifier interface. */
+    vcVerify(body) {
+        return this.request('post', '/credentials/verify', { body });
+    }
+    /** Verify a Verifiable Presentation through the VC-API verifier interface. */
+    vpVerify(body) {
+        return this.request('post', '/presentations/verify', { body });
     }
     // ---- discovery ----
-    oidcDiscovery() {
-        return this.get('/oidc/.well-known/openid-configuration');
+    /** This deployment's DID document (`did:web`). */
+    didDocument() {
+        return this.request('get', '/.well-known/did.json', { auth: 'none' });
     }
-    // ---- internals ----
-    async get(path, admin = false) {
-        return this.request('GET', path, undefined, admin);
+    /** The DID document for one country's issuer key. */
+    didDocumentFor(countryCode) {
+        return this.request('get', '/.well-known/did/{countryCode}.json', { path: { countryCode }, auth: 'none' });
     }
-    async post(path, body, admin = false) {
-        return this.request('POST', path, body, admin);
+    /** A Bitstring Status List credential, for offline revocation checks. */
+    statusList(file) {
+        return this.request('get', '/.well-known/status/{file}', { path: { file }, auth: 'none' });
     }
-    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');
-            }
+    /** OpenID Connect discovery for the SSO provider mounted under /oidc. */
+    oidcDiscovery() {
+        return this.request('get', '/oidc/.well-known/openid-configuration', { auth: 'none' });
+    }
+    // ---- internals ----
+    async send(method, template, opts) {
+        // Parameter names are identifiers; the bounded class keeps the scan linear.
+        const path = template.replace(/\{([A-Za-z0-9_]+)\}/g, (_, name) => {
+            const value = opts.path?.[name];
+            if (value === undefined)
+                throw new Error(`Missing path parameter "${name}" for ${template}`);
+            return encodeURIComponent(String(value));
+        });
+        const q = new URLSearchParams();
+        for (const [k, v] of Object.entries(opts.query ?? {})) {
+            if (v === undefined || v === null)
+                continue;
+            if (Array.isArray(v))
+                v.forEach((item) => q.append(k, String(item)));
+            else
+                q.set(k, String(v));
         }
-        const res = await this.doFetch(`${this.baseUrl}${path}`, {
-            method,
+        const qs = q.toString();
+        const headers = { accept: opts.accept ?? 'application/json' };
+        if (opts.body !== undefined)
+            headers['content-type'] = 'application/json';
+        this.applyAuth(headers, opts.auth ?? 'auto');
+        Object.assign(headers, opts.headers);
+        const res = await this.doFetch(`${this.baseUrl}${path}${qs ? `?${qs}` : ''}`, {
+            method: method.toUpperCase(),
             headers,
-            body: body !== undefined ? JSON.stringify(body) : undefined,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
         });
         const text = await res.text();
-        const parsed = text ? JSON.parse(text) : undefined;
+        const isJson = (res.headers.get('content-type') ?? '').includes('json');
+        let parsed = text;
+        if (isJson || headers.accept === 'application/json') {
+            try {
+                parsed = text ? JSON.parse(text) : undefined;
+            }
+            catch {
+                parsed = text;
+            }
+        }
         if (!res.ok)
             throw new OpenResidencyError(res.status, parsed);
         return parsed;
     }
+    applyAuth(headers, auth) {
+        if (auth === 'none')
+            return;
+        if (typeof auth === 'object') {
+            if ('bearer' in auth)
+                headers['authorization'] = `Bearer ${auth.bearer}`;
+            else
+                Object.assign(headers, auth.headers);
+            return;
+        }
+        // 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 if (auth === 'operator') {
+            throw new Error('This endpoint requires operator authentication: set operatorKey (preferred), ' +
+                'operatorToken, or the legacy adminKey in ClientOptions');
+        }
+    }
 }