- ESM-Package für Node.js 18+
- Client mit Sync, Async (mit Polling), Webhook, Verify, Download
- Typisierte Error-Klassen
- Webhook-Signatur-Verifikation (timingSafeEqual)
- 13 Tests mit Node native test runner

2026-04-25 12:26:04 +02:00

5.2 KiB

Raw Blame History

hightrusted CAPTURE — Node.js SDK

Status: v0.1 Preview — API stabil, SDK in aktiver Entwicklung

Offizielles Node.js-SDK für die hightrusted CAPTURE API — forensische Web-Captures mit qualifiziertem Zeitstempel nach RFC 3161 / eIDAS Art. 41.

Made in Germany. Server in Deutschland. DSGVO-nativ. Quelloffen unter MIT.

Installation

npm install @hightrusted/capture

Quickstart

import { Client } from '@hightrusted/capture';

const client = new Client({ apiKey: 'ht_live_...' });

// Synchron — wartet bis zu 30 s auf das fertige PDF
const capture = await client.capture({ url: 'https://example.com' });

console.log(capture.id);
console.log(capture.verify_url);
console.log(capture.timestamp.issued_at);

// PDF herunterladen
await client.downloadPdf(capture.id, './beweis.pdf');

Drei Aufruf-Modi

Synchron (Default)

const capture = await client.capture({ url: 'https://example.com' });

Asynchron mit Polling

const capture = await client.captureAsync({
  url: 'https://example.com',
  reference: 'case-001',
  waitForReady: true,   // Default — pollt bis ready
  maxWaitMs: 60_000,
});

Webhook

const job = await client.captureWebhook({
  url: 'https://example.com',
  webhookUrl: 'https://your-app.tld/webhooks/capture',
  reference: 'case-001',
});
// Server liefert das fertige Capture per HTTP-POST aus

Verifikation (kostenlos, ohne Quota)

// Per Capture-ID
const result = await client.verify({ source: 'cap_...' });

// Per Verify-URL
const result = await client.verify({ source: 'https://verify.hightrusted.net/c/...' });

// Per PDF-Upload (Buffer oder Blob)
const pdf = await readFile('./beweis.pdf');
const result = await client.verify({ pdf });

console.log(result.valid);                     // true
console.log(result.audit_log.chain_valid);     // true

Webhook-Signatur prüfen

import express from 'express';
import { verifyWebhookSignature } from '@hightrusted/capture';

const app = express();

app.post(
  '/webhooks/capture',
  express.raw({ type: 'application/json' }),  // RAW body — wichtig!
  (req, res) => {
    const sig = req.header('X-Hightrusted-Signature');
    if (!verifyWebhookSignature(req.body, sig, 'wh_secret_...')) {
      return res.status(401).json({ error: 'invalid_signature' });
    }
    const payload = JSON.parse(req.body);
    // ...
    res.status(200).json({ ok: true });
  }
);

Fehler-Behandlung

import {
  Client,
  InvalidApiKeyError,
  QuotaExceededError,
  RateLimitedError,
  UnreachableUrlError,
} from '@hightrusted/capture';

try {
  const capture = await client.capture({ url: 'https://example.com' });
} catch (err) {
  if (err instanceof InvalidApiKeyError) console.error('API-Key ungültig');
  else if (err instanceof QuotaExceededError) console.error('Quota erschöpft');
  else if (err instanceof RateLimitedError)
    console.error(`Rate-limited, retry in ${err.retryAfterSeconds}s`);
  else throw err;
}

API-Key

Bearer-Token, Erzeugung unter https://capture.hightrusted.net/dashboard/api-keys

const client = new Client({ apiKey: 'ht_live_...' });
// alternativ via Umgebungsvariable HIGHTRUSTED_API_KEY
const client = new Client();

Voraussetzungen

Node.js 18 oder höher (fetch, AbortSignal.timeout, FormData werden vorausgesetzt)
ESM only — import-Syntax. Wenn du CommonJS brauchst, dynamic import nutzen:
```
const { Client } = await import('@hightrusted/capture');
```

Entwicklung

git clone ssh://git@git.hightrusted.net:2222/hightrusted-capture/node.git
cd node
npm install
npm test       # 13 Tests mit Node native test runner

Roadmap

v0.1 — Basis-Client (sync + async + webhook), Verify, Download, typisierte Errors
v0.2 — TypeScript-Defs, retry-after-Helper
v0.3 — Stream-API für große PDFs
v1.0 — Stabile API, semantische Versionierung

Support

Doku: https://capture.hightrusted.net/api/docs
Status: https://status.hightrusted.net
Developer Support: developers@hightrusted.net
Sicherheit: siehe SECURITY.md

Lizenz

MIT — siehe LICENSE.

hightrusted GmbH — The European Trust Infrastructure. Made in Germany. DSGVO-nativ. eIDAS-konform.

5.2 KiB Raw Blame History