@onchaindiligence/sdk 0.2.0 → 0.3.1

package/dist/index.js

@@ -22,6 +22,8 @@
  * build a payment header, or retry a request by hand.
  */
 import { Mppx, tempo } from 'mppx/client';
+import { DEFAULT_ATTESTATION_ISSUER, verifyAttestationOffline, } from './verification.js';
+export * from './verification.js';
 export class OnchainDiligenceError extends Error {
     status;
     constructor(status, message) {
@@ -31,12 +33,136 @@ export class OnchainDiligenceError extends Error {
     }
 }
 const DEFAULT_BASE_URL = 'https://api.onchaindiligence.com';
+export async function resolveAttestationKeyOnline(keyId, options = {}) {
+    const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+    if (!options.fetch && !globalThis.fetch)
+        throw new Error('fetch is unavailable in this runtime');
+    // `globalThis.fetch` is a WebIDL operation on the global object -- calling
+    // it through ANY indirection (a local variable, a class property) other
+    // than the bare `fetch(...)` identifier detaches it from its required
+    // receiver, which throws "Illegal invocation" in real browsers (invisible
+    // under Node, which does not enforce this). Binding to globalThis is what
+    // makes storing/passing it around safe.
+    const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const exact = await fetchImpl(`${baseUrl}/.well-known/attestation-keys/${encodeURIComponent(keyId)}`);
+    if (exact.ok) {
+        const payload = (await exact.json());
+        if (!payload.key || payload.key.key_id !== keyId) {
+            throw new Error('attestation key registry returned an invalid or mismatched key');
+        }
+        return payload.key;
+    }
+    if (exact.status !== 404) {
+        throw new OnchainDiligenceError(exact.status, 'could not fetch attestation public key');
+    }
+    const legacy = await fetchImpl(`${baseUrl}/.well-known/attestation-key`);
+    if (!legacy.ok) {
+        throw new OnchainDiligenceError(legacy.status, 'could not fetch attestation public key');
+    }
+    const text = await legacy.text();
+    let reportedKeyId = '';
+    let pem = text.trim();
+    let algorithm = 'ed25519';
+    let status = 'active';
+    if (!pem.includes('BEGIN PUBLIC KEY')) {
+        const payload = JSON.parse(text);
+        reportedKeyId = payload.key_id || '';
+        pem = (payload.public_key_pem || payload.publicKey || payload.pem || payload.key || '').trim();
+        algorithm = payload.algorithm || algorithm;
+        status = payload.status || status;
+    }
+    if (reportedKeyId !== keyId || !pem.includes('BEGIN PUBLIC KEY') || algorithm !== 'ed25519') {
+        throw new Error('legacy attestation-key endpoint did not return the requested key_id');
+    }
+    return {
+        key_id: keyId,
+        algorithm: 'ed25519',
+        public_key_pem: pem,
+        status,
+        valid_from: null,
+        valid_until: null,
+        status_changed_at: null,
+    };
+}
+/** Validate and return the complete signed envelope required by `/anchor`. */
+export function buildAnchorRequest(envelope) {
+    if (!envelope ||
+        typeof envelope !== 'object' ||
+        !Object.hasOwn(envelope, 'data') ||
+        !envelope.attestation ||
+        typeof envelope.attestation !== 'object' ||
+        envelope.attestation.signed !== true) {
+        throw new TypeError('anchor requires the complete signed attestation envelope');
+    }
+    return envelope;
+}
+/** Explicit online-discovery wrapper around the zero-network verifier core. */
+export async function verifyAttestationOnline(signed, options = {}) {
+    let parsed = signed;
+    if (typeof signed === 'string') {
+        try {
+            parsed = JSON.parse(signed);
+        }
+        catch {
+            return verifyAttestationOffline(signed, { keys: [] }, options);
+        }
+    }
+    const keyId = parsed?.attestation?.key_id;
+    if (typeof keyId !== 'string') {
+        return verifyAttestationOffline(signed, { keys: [] }, options);
+    }
+    const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+    let record;
+    try {
+        record = await resolveAttestationKeyOnline(keyId, { baseUrl, fetch: options.fetch });
+    }
+    catch (error) {
+        const offline = await verifyAttestationOffline(signed, { keys: [] }, options);
+        if (offline.state === 'INVALID')
+            return offline;
+        return {
+            ...offline,
+            state: 'UNVERIFIABLE',
+            valid: false,
+            code: 'online_key_resolution_failed',
+            reason: error instanceof Error ? error.message : 'Online key resolution failed.',
+        };
+    }
+    const material = {
+        keys: [record],
+        issuer: options.expectedIssuer ?? DEFAULT_ATTESTATION_ISSUER,
+        trust_source: `online-registry:${baseUrl}`,
+    };
+    const offline = await verifyAttestationOffline(signed, material, options);
+    const trustDecision = typeof options.trustRegistry === 'function'
+        ? await options.trustRegistry(record, { baseUrl })
+        : options.trustRegistry === true;
+    if (trustDecision || offline.state === 'INVALID')
+        return offline;
+    return {
+        ...offline,
+        state: 'UNVERIFIABLE',
+        valid: false,
+        code: 'online_registry_not_trusted',
+        reason: 'The key was discovered online but the caller did not trust that registry as identity authority.',
+        trusted: false,
+        components: {
+            ...offline.components,
+            identity: {
+                state: 'UNKNOWN',
+                code: 'online_registry_not_trusted',
+                message: 'Online key discovery is not an out-of-band trust decision.',
+            },
+        },
+    };
+}
 export class OnchainDiligence {
     baseUrl;
+    expectedAttestationIssuer;
     fetch;
-    attestationKeyPem = null;
     constructor(opts) {
         this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+        this.expectedAttestationIssuer = opts.expectedAttestationIssuer ?? DEFAULT_ATTESTATION_ISSUER;
         // Payment-aware fetch: transparently answers 402 challenges and retries.
         const client = Mppx.create({ methods: [tempo({ account: opts.account })] });
         this.fetch = client.fetch;
@@ -143,9 +269,9 @@ export class OnchainDiligence {
             items,
         };
     }
-    /** Anchor an attestation's signature hash on Tempo (paid). */
-    anchor(signature) {
-        return this.post(`/anchor`, { signature });
+    /** Anchor a complete authentic attestation envelope on Tempo (paid). */
+    anchor(envelope) {
+        return this.post(`/anchor`, buildAnchorRequest(envelope));
     }
     // --- Free endpoints ------------------------------------------------------
     /** Check whether an attestation has been anchored on-chain (free). */
@@ -159,93 +285,36 @@ export class OnchainDiligence {
     // --- Verification (local, free, no trust in this SDK or the server) -------
     /**
      * Verify a signed attestation locally. Fetches the server's published
-     * Ed25519 public key once (cached), then checks the signature over the
-     * canonical signing input `JSON.stringify({ data, issued_at, key_id })` —
-     * the exact bytes the server signs. A `valid: true` result means the data
-     * has not been altered since the server signed it, provable without trusting
-     * this SDK.
+     * exact Ed25519 key identified by `key_id` (cached), then verifies either
+     * the domain-separated RFC 8785 version 2 input or the legacy version 1
+     * JSON.stringify input. Revoked/compromised keys remain cryptographically
+     * checkable but return `valid: false` and `trusted: false`.
      *
      * Uses WebCrypto (`globalThis.crypto.subtle`) so it runs dependency-free in
      * Node 18+, edge runtimes, and modern browsers.
      */
-    async verifyAttestation(signed) {
-        const att = signed?.attestation;
-        if (!att || att.signed === false)
-            return { valid: false, reason: 'response is not signed' };
-        if (!att.signature || !att.key_id || !att.issued_at) {
-            return { valid: false, reason: 'attestation is missing signature, key_id, or issued_at' };
-        }
-        if (att.algorithm && att.algorithm !== 'ed25519') {
-            return { valid: false, reason: `unsupported algorithm: ${att.algorithm}`, keyId: att.key_id };
-        }
-        const subtle = globalThis.crypto?.subtle;
-        if (!subtle)
-            return { valid: false, reason: 'WebCrypto (crypto.subtle) is unavailable in this runtime' };
-        let key;
-        try {
-            const pem = await this.getAttestationKeyPem();
-            key = await subtle.importKey('spki', pemToDer(pem), { name: 'Ed25519' }, false, ['verify']);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            return { valid: false, reason: `could not load public key: ${msg}`, keyId: att.key_id };
-        }
-        const signingInput = JSON.stringify({
-            data: signed.data,
-            issued_at: att.issued_at,
-            key_id: att.key_id,
-        });
-        const ok = await subtle.verify('Ed25519', key, b64urlToBytes(att.signature), new TextEncoder().encode(signingInput));
-        return ok
-            ? { valid: true, keyId: att.key_id }
-            : { valid: false, reason: 'signature does not match', keyId: att.key_id };
-    }
     /**
-     * Fetch and cache the server's Ed25519 public key (PEM) from
-     * `/.well-known/attestation-key`. Accepts a raw PEM body or a JSON wrapper
-     * exposing the PEM under a common field name.
+     * Compatibility online wrapper. Prefer the standalone zero-network
+     * verifyAttestationOffline() with caller-supplied trust material.
      */
-    async getAttestationKeyPem() {
-        if (this.attestationKeyPem)
-            return this.attestationKeyPem;
-        const res = await this.fetch(`${this.baseUrl}/.well-known/attestation-key`);
-        if (!res.ok) {
-            throw new OnchainDiligenceError(res.status, 'could not fetch attestation public key');
-        }
-        const text = await res.text();
-        let pem = text.trim();
-        if (!pem.includes('BEGIN PUBLIC KEY')) {
-            try {
-                const j = JSON.parse(text);
-                pem = (j.public_key_pem || j.publicKey || j.pem || j.key || '').trim();
-            }
-            catch {
-                /* not JSON — fall through to the check below */
-            }
-        }
-        if (!pem.includes('BEGIN PUBLIC KEY')) {
-            throw new Error('attestation-key endpoint did not return a PEM public key');
-        }
-        this.attestationKeyPem = pem;
-        return pem;
+    verifyAttestation(signed) {
+        return verifyAttestationOnline(signed, {
+            baseUrl: this.baseUrl,
+            expectedIssuer: this.expectedAttestationIssuer,
+            fetch: this.fetch,
+            // This preserves the historical SDK behavior: constructing this client
+            // explicitly chooses its configured HTTPS issuer registry as authority.
+            trustRegistry: true,
+            // Compatibility until production publishes a real activation boundary.
+            requireValidFrom: false,
+        });
+    }
+    verifyAttestationOnline(signed, options = {}) {
+        return verifyAttestationOnline(signed, {
+            ...options,
+            baseUrl: this.baseUrl,
+            expectedIssuer: options.expectedIssuer ?? this.expectedAttestationIssuer,
+            fetch: this.fetch,
+        });
     }
-}
-// --- Internal helpers (isomorphic: no Buffer, no Node built-ins) ------------
-/** Decode a PEM (SPKI) public key to its raw DER bytes. */
-function pemToDer(pem) {
-    const b64 = pem.replace(/-----[^-]+-----/g, '').replace(/\s+/g, '');
-    const bin = atob(b64);
-    const out = new Uint8Array(bin.length);
-    for (let i = 0; i < bin.length; i++)
-        out[i] = bin.charCodeAt(i);
-    return out;
-}
-/** Decode a base64url string to bytes. */
-function b64urlToBytes(s) {
-    const b64 = s.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(s.length / 4) * 4, '=');
-    const bin = atob(b64);
-    const out = new Uint8Array(bin.length);
-    for (let i = 0; i < bin.length; i++)
-        out[i] = bin.charCodeAt(i);
-    return out;
 }

package/dist/verification.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Zero-network verification for existing OnChainDiligence attestations.
+ *
+ * This module deliberately has no HTTP client and never discovers keys. The
+ * caller supplies the exact key records it has independently chosen to trust.
+ * Online discovery is implemented separately in index.ts as a convenience
+ * wrapper around this core.
+ */
+export declare const ATTESTATION_V2_SCHEMA = "onchaindiligence.attestation.v2";
+export declare const DEFAULT_ATTESTATION_ISSUER = "https://api.onchaindiligence.com";
+export declare const COMPLIANCE_ATTESTATION_PURPOSE = "compliance-screening-result";
+export declare const FIXTURE_ATTESTATION_PURPOSE = "verification-fixture";
+export type VerificationState = 'VALID' | 'INVALID' | 'UNVERIFIABLE';
+export type ComponentState = 'PASS' | 'FAIL' | 'UNKNOWN' | 'NOT_CHECKED';
+export type AttestationKeyStatus = 'active' | 'retired' | 'revoked' | 'compromised';
+export interface Attestation {
+    signed: boolean;
+    schema_version?: string;
+    issuer?: string;
+    purpose?: string;
+    key_id?: string;
+    algorithm?: string;
+    canonicalization?: string;
+    signature?: string;
+    issued_at?: string;
+    [key: string]: unknown;
+}
+export interface Signed<T> {
+    data: T;
+    attestation: Attestation;
+}
+export interface AttestationKeyRecord {
+    key_id: string;
+    algorithm: 'ed25519';
+    public_key_pem: string;
+    status: AttestationKeyStatus;
+    valid_from: string | null;
+    valid_until: string | null;
+    status_changed_at?: string | null;
+    status_reason?: string;
+    replacement_key_id?: string | null;
+    compromised_at?: string | null;
+}
+/**
+ * Passing this object is an explicit caller trust decision. A key embedded in
+ * an attestation or downloaded from an arbitrary URL MUST NOT be copied here
+ * automatically.
+ */
+export interface TrustedAttestationKeySet {
+    keys: readonly AttestationKeyRecord[];
+    /** Optional identity namespace represented by these trusted records. */
+    issuer?: string;
+    /** Human/machine-readable description of the out-of-band trust source. */
+    trust_source?: string;
+    /** Reserved for future signed registry snapshot/root policy. */
+    registry_version?: number;
+}
+export interface VerificationComponent {
+    state: ComponentState;
+    code: string;
+    message: string;
+}
+export interface AttestationVerificationComponents {
+    structure: VerificationComponent;
+    signature: VerificationComponent;
+    identity: VerificationComponent;
+    lifecycle: VerificationComponent;
+    timestamp: VerificationComponent;
+    key_window: VerificationComponent;
+    freshness: VerificationComponent;
+    anchor: VerificationComponent;
+}
+export interface AttestationVerificationResult {
+    state: VerificationState;
+    /** Compatibility convenience. Security-sensitive callers should use state. */
+    valid: boolean;
+    code: string;
+    reason: string;
+    schemaVersion?: string;
+    keyId?: string;
+    keyStatus?: AttestationKeyStatus;
+    cryptographicallyValid?: boolean;
+    trusted?: boolean;
+    components: AttestationVerificationComponents;
+    warnings: string[];
+}
+export interface VerifyAttestationOptions {
+    expectedIssuer?: string;
+    allowedPurposes?: readonly string[];
+    /** Default true. A missing active valid_from is UNVERIFIABLE. */
+    requireValidFrom?: boolean;
+    /** Evaluate business freshness separately from signature/key validity. */
+    maxAgeMs?: number;
+    /** Injected for deterministic verification/tests. */
+    now?: Date | number | string;
+    /** Default five minutes. */
+    maxFutureSkewMs?: number;
+}
+/** RFC 8785 canonical JSON for values in the I-JSON data model. */
+export declare function canonicalizeJson(value: unknown): string;
+/**
+ * Parse JSON while rejecting duplicate object member names. JSON.parse keeps
+ * the last duplicate, which is unsafe for signed formats because another
+ * implementation may keep the first.
+ */
+export declare function parseJsonNoDuplicateKeys(text: string, maxDepth?: number): unknown;
+export declare function deriveAttestationKeyId(publicKeyPem: string): Promise<string>;
+/** Verify using only the supplied envelope and caller-trusted key records. */
+export declare function verifyAttestationOffline(input: unknown, trustMaterial: TrustedAttestationKeySet, options?: VerifyAttestationOptions): Promise<AttestationVerificationResult>;