@cosignet/sdk

Schlanker TypeScript-Client ohne Abhängigkeiten für Cosignet — Human-in-the-Loop-Freigabe für risikoreiche KI-Agenten-Aktionen, mit nutzlastgebundenen Passkey-Signaturen.

Bringe einen Menschen in den Kreislauf, bevor eine gefährliche Aktion ausgeführt wird: pausiere sie, hole eine explizite Passkey-Genehmigung von einer Person (Face ID / Touch ID / Windows Hello / Sicherheitsschlüssel) ein und fahre nur mit einer signierten Entscheidung fort, die an die exakte Nutzlast gebunden ist – ändere die Aktion danach und die Signatur stimmt nicht mehr. Cosignet ist eine Genehmigungs- und Beweisschicht, kein Ausführer oder Policy-Engine. Läuft überall mit globalem fetch + Web Crypto: Node 18+, Cloudflare Workers, Deno und Browser.

Status: Früher Zugang. Veröffentlicht auf npm als @cosignet/sdk.

Installieren

npm install @cosignet/sdk

Eine Genehmigung anfordern und auf die Entscheidung warten

import { Cosignet } from '@cosignet/sdk';

const cosignet = new Cosignet({ apiKey: process.env.COSIGNET_API_KEY! });

const decision = await cosignet.requestApproval(
  {
    username: 'alex',
    action: 'Wire transfer to vendor',
    payload: { to: 'acct_8821', amount_usd: 4200, memo: 'INV-2025-118' },
    notify: 'telegram_or_email',
  },
  { onCreated: (c) => console.log('Hier genehmigen:', c.url) },
);

if (decision.status === 'approved') {
  // fortfahren — decision.rawAssertion ist der signierte Beweis
} else {
  // 'rejected' | 'expired' | 'pending' (timeout)
}

requestApproval führt Long-Polling über Ihre eigene ausgehende Verbindung durch (~25s Hops), sodass es auch von CLI-Tools und abgeschotteten VPCs hinter NAT/Firewalls funktioniert – kein eingehender Webhook, kein offener Port, keine öffentliche IP erforderlich.

Fail-Closed, wenn Cosignet nicht verfügbar ist

Wenn Ihr System keine signierte Genehmigung erhalten kann, darf die abgesicherte Aktion nicht ausgeführt werden. Nichtverfügbarkeit darf niemals zu automatischer Genehmigung führen. Behandle jedes Timeout, jeden Netzwerkfehler und jeden 5xx als "nicht genehmigt".

Implementierungshinweise:

• Unterscheiden Sie in Ihren Logs und Alarmen zwischen "abgelehnt" und "nicht verfügbar". Ersteres ist eine menschliche Entscheidung, Letzteres ein Betriebszustand.
• Wiederholen Sie Lesevorgänge mit exponentiellem Backoff und Jitter; begrenzen Sie die Gesamtwartezeit auf Ihre eigene Frist für die Aktion und behandeln Sie sie dann als abgelaufen.
• Machen Sie gesperrte Aktionen auf Ihrer Seite idempotent, sodass eine Wiederholung nach einem unklaren Zustand keine doppelte Ausführung verursachen kann.
• Cachen Sie niemals eine Genehmigung zur Wiederverwendung. Eine signierte Entscheidung ist an einen Nutzlast-Hash gebunden; behandeln Sie sie als Einmalnutzung.

Siehe Wenn Cosignet nicht verfügbar ist für die vollständige Anleitung zur Verfügbarkeit und zum Notfallzugriff.

Aufrufe auf niedrigerer Ebene

const created = await cosignet.createConfirmation({ username, action, payload });
const status  = await cosignet.getConfirmation(created.id, { wait: 25 }); // Long-Poll

Sichere Wiederholungen mit einem Idempotenz-Schlüssel

Übergeben Sie idempotencyKey (gesendet als Idempotency-Key-Header), sodass ein wiederholter create-Vorgang – z. B. nach einem Netzwerkausfall, der ein Long-Poll unterbricht – mit gleichem Schlüssel und gleicher Aktion/Nutzlast die ursprüngliche Bestätigung (idempotent: true) zurückgibt, anstatt ein Duplikat zu erzeugen oder den Genehmiger erneut zu benachrichtigen. Die Wiederverwendung eines Schlüssels mit anderen Parametern wird mit einem 422 abgelehnt.

await cosignet.createConfirmation({
  username: 'alex',
  action: 'Wire transfer to vendor',
  payload: { to: 'acct_8821', amount_usd: 4200 },
  idempotencyKey: 'wire-INV-2025-118', // stabil pro logischem Vorgang
});

Den Genehmiger zurück zu Ihrer App schicken

Übergeben Sie returnUrl, um auf der Genehmigungsseite einen "Zurück zu "-Button anzuzeigen, sobald die Anfrage aufgelöst wurde (genehmigt / abgelehnt / abgelaufen) – praktisch, damit ein Mensch zurück zu Ihrer App gelangen kann, um eine abgelaufene Aktion erneut auszulösen. Es muss eine HTTPS-URL sein und wird nur als Klick-Link dargestellt (niemals serverseitig abgerufen).

await cosignet.requestApproval({
  username: 'alex',
  action: 'Wire transfer to vendor',
  payload: { to: 'acct_8821', amount_usd: 4200 },
  returnUrl: 'https://app.example.com/approvals',
});

Benachrichtigungen

notify ('none' | 'telegram' | 'email' | 'telegram_or_email') steuert den persönlichen Erreichbarkeits-Ping an den spezifischen Unterzeichner:

• telegram – eine DM an das verknüpfte Telegram des Genehmigers (telegram_or_email bevorzugt dies, wenn der Genehmiger einen Chat verknüpft hat).
• email – eine E-Mail an die eigene Adresse des Genehmigers. Priorität: die direkte E-Mail, die Sie dem Genehmiger im Dashboard zugewiesen haben (nur zum Versand), dann die verifizierte Mitglieds-E-Mail, dann als letzte Möglichkeit die Kontaktadresse des Kontos.
• telegram_or_email – Telegram, falls verknüpft, ansonsten die obige E-Mail.
• none – kein persönlicher Ping.

Getrennt davon ist die Team-Erreichbarkeit eine Slack-Broadcast-Nachricht an einen gemeinsamen Kanal, die pro Konto im Dashboard konfiguriert wird. Sie ist additiv und wird bei Konfiguration immer ausgelöst, unabhängig von notify (d.h. selbst bei notify:'none' wird noch an Slack gesendet). Genehmiger erhalten ihr Telegram und ihre E-Mail im Bereich "Genehmiger" des Dashboards.

Hinweis zur Veröffentlichung mit public: true: Die in das Transparenzprotokoll aufgenommene E-Mail ist die vom Konto festgelegte verifizierte E-Mail-Adresse (gewählt in den Dashboard-Einstellungen, als verantwortliche Partei – nicht der einzelne Unterzeichner). Die direkte Benachrichtigungs-E-Mail dient nur zum Versand und wird niemals für den Offenlegungs-Hash verwendet.

Jeder Kanal ist rein als Link: Die Benachrichtigung enthält die Genehmigungs-URL und niemals die action oder payload. Die Genehmigung erfordert immer den nutzlastgebundenen Passkey des Genehmigers auf der Bestätigungsseite – es gibt keine Genehmigung im Kanal.

Einen Webhook verifizieren

verifyWebhookSignature berechnet den hex HMAC-SHA256 des rohen Anforderungstextes neu und vergleicht ihn konstantenzeitlich mit dem Cosignet-Signature-Header. Übergeben Sie die exakten Bytes, die Sie empfangen haben – erneutes Serialisieren von JSON ändert die Signatur.

import { verifyWebhookSignature } from '@cosignet/sdk';

const ok = await verifyWebhookSignature({
  body: rawBody,                              // roher String, kein neu-geparstes JSON
  signature: req.headers['cosignet-signature'],
  secret: process.env.COSIGNET_WEBHOOK_SECRET!,
  timestamp: req.headers['cosignet-timestamp'], // optionaler Replay-Schutz
  toleranceSeconds: 300,                         // optional
});
if (!ok) return res.status(401).end();

Verifikation

Siehe docs/verification.md für die aufruferseitige Checkliste: nur bei approved fortfahren, die Entscheidung mit der durchzuführenden Operation vergleichen und rejected/expired/timeouts als harte Stopps behandeln.

API

• new Cosignet({ apiKey, baseUrl?, fetch? })
• createConfirmation(input) → CreatedConfirmation
• getConfirmation(id, { wait? }) → Confirmation
• requestApproval(input, { timeoutMs?, onCreated? }) → Confirmation
• verifyWebhookSignature({ body, signature, secret, timestamp?, toleranceSeconds? }) → Promise<boolean>

Öffentliche Offenlegung der Genehmigung (opt-in, standardmäßig aus)

Standardmäßig hält das Transparenzprotokoll die Nutzlast zurück und gibt keine Identität des Genehmigers preis. Setzen Sie public: true bei createConfirmation/requestApproval, um eine einzelne Genehmigung für die öffentliche Offenlegung zu aktivieren: Ihre rohe action + payload werden im Verifikationspaket lesbar, und ein PBKDF2-Hash der vom Konto festgelegten verifizierten E-Mail-Adresse (gewählt in den Dashboard-Einstellungen – die verantwortliche Partei, nicht der einzelne Unterzeichner) wird in das Merkle-Blatt aufgenommen, sodass jeder eine Kandidatenadresse dagegen prüfen kann.

await cosignet.requestApproval({
  username: 'alice',
  action: 'Publish Q3 board resolution',
  payload: { docId: 'res-2026-Q3' },
  public: true, // dauerhaft und unumkehrbar – siehe Hinweise unten
});

• Dauerhaft und unumkehrbar – einmal veröffentlicht, kann es nicht rückgängig gemacht werden.
• Erfordert, dass die öffentliche Offenlegung für Ihr Konto aktiviert ist (Dashboard-Einstellungen); andernfalls wird die Anfrage abgelehnt.
• Ehrlichkeit: Die Nutzlast-Offenlegung ist passkey-gebunden (stark); der E-Mail-Hash wird von Cosignets signiertem Baumkopf bezeugt – nicht vom Passkey signiert – und E-Mail hat eine geringe Entropie, daher beweist eine Übereinstimmung eine bekannte Adresse und keine Anonymität. Die aufgenommene E-Mail benennt die vom Konto gewählte verantwortliche Partei, nicht unbedingt den einzelnen Unterzeichner; wenn keine E-Mail gewählt wurde, gibt das Blatt nur die Nutzlast preis.
• Aktivieren Sie es nicht für Bestätigungen, die Geheimnisse oder personenbezogene Daten enthalten.

Beispiele & Sicherheitsdokumentation

• examples/ – kopierfertige Beispiele für cURL, Node, Python, GitLab CI, MCP/Tool-Wrapper und Worker.
• security/ – Nutzlastbindung, WebAuthn-Beweismodell, Bedrohungsmodell, Transparenzprotokoll und verantwortungsvolle Offenlegung.

Rezepte

Sperren Sie risikoreiche Aktionen hinter einer Passkey-Genehmigung:

• recipes/ai-agent-gate – pausieren Sie einen KI-Codierungsagenten (Claude Code), bevor er einen gefährlichen Shell-Befehl ausführt, bis ein Mensch gegenzeichnet.
• recipes/cli-approval – umschließen Sie beliebige Befehle (z. B. terraform destroy).
• recipes/ci-cd – blockieren Sie eine Pipeline (GitHub Actions / GitLab CI) bis zur Genehmigung.
• recipes/backend-service – pausieren Sie einen irreversiblen Vorgang in einem Dienst.

Feedback und Anfragen

• Feature-Anfragen, Produktideen, SDK/API-Ergonomie und Roadmap-Diskussion: Eröffnen Sie ein Feature-Issue.
• Anfragen für neue Beispiele oder Integrationen: Eröffnen Sie ein Beispiel-Anfrage-Issue.
• Sicherheitsmeldungen: E-Mail an [email protected]; reichen Sie keine öffentlichen Issues für Schwachstellen ein.

Mitwirken & Sicherheit

• Code, Issues und Diskussionen leben auf GitLab: https://gitlab.com/cosignet/sdk.
• Beiträge willkommen – siehe CONTRIBUTING und unseren Verhaltenskodex.
• Melden Sie Schwachstellen privat: SECURITY.md · [email protected].

Lizenz

MIT © Cosignet