Papierhafen-Protokoll v1

API

Die Mac-App spricht JSON über HTTPS mit diesem Server. Alles, was hier gespeichert wird, ist auf dem Gerät verschlüsselt. Angemeldete Anfragen tragen Authorization: Bearer ordo_….

Server

Was dieser Server ist und ob er zur App passt.

  • GET /api/v1/server öffentlich

    Name, Version, Protokoll, Registrierung, Kontingent und, falls freigegeben, Statistiken.

Konto und Anmeldung

Anmelden ohne Passwort: Der Server schickt eine Challenge, das Gerät signiert sie mit Ed25519.

  • POST /api/v1/accounts öffentlich

    Konto anlegen: Konto-ID, öffentlicher Schlüssel, verpackter Master-Key, ggf. Einladungscode.

  • POST /api/v1/auth/challenge öffentlich

    Einmalige Challenge holen, 2 Minuten gültig. Auch für unbekannte Konten.

  • POST /api/v1/auth/session öffentlich

    Signierte Challenge gegen ein Bearer-Token tauschen; mit webKeyId eine lesende Browser-Sitzung.

  • DELETE /api/v1/auth/session angemeldet

    Dieses Gerät abmelden.

  • GET /api/v1/account angemeldet

    Verpackter Master-Key, Speicherverbrauch und Kontingent.

  • PUT /api/v1/account/key angemeldet + frische Signatur

    Master-Key neu verpackt speichern, wenn der Notfallschlüssel gewechselt wird.

  • POST /api/v1/account/delete angemeldet + frische Signatur

    Konto mit allen Dokumenten endgültig löschen.

  • GET /api/v1/account/sessions angemeldet

    Angemeldete Geräte.

  • DELETE /api/v1/account/sessions/{id} angemeldet

    Ein Gerät abmelden.

Papierhafen-Konto

Auf Servern mit Papierhafen-Konten (ORDO_ACCOUNTS): Die App meldet sich über /connect im Browser an und bekommt ein Geräte-Token für den Header X-Ordo-User.

  • POST /api/v1/connect/token öffentlich

    Den einmaligen Code von /connect mit dem PKCE-Verifier gegen ein Geräte-Token tauschen.

  • GET /api/v1/me Papierhafen-Konto

    E-Mail, Name, verknüpfter Tresor, verbundene Apps und Version des Profilbilds.

  • GET /api/v1/me/avatar Papierhafen-Konto

    Das eigene Profilbild (JPEG), nur für dieses Konto.

  • PUT /api/v1/me/avatar Papierhafen-Konto

    Profilbild setzen: JPEG oder PNG, 32 bis 1024 Pixel, höchstens 2 MB; wird neu kodiert.

  • DELETE /api/v1/me/avatar Papierhafen-Konto

    Profilbild entfernen.

  • POST /api/v1/pairing Papierhafen-Konto

    Neues Gerät koppeln: X25519-Schlüssel hinterlegen, 10 Minuten gültig.

  • GET /api/v1/pairing Papierhafen-Konto

    Geräte, die auf Freigabe warten.

  • GET /api/v1/pairing/{id} Papierhafen-Konto

    Stand der Kopplung; nach Freigabe einmalig mit dem verschlüsselten Notfallschlüssel.

  • PUT /api/v1/pairing/{id} Papierhafen-Konto

    Freigeben: Notfallschlüssel, verschlüsselt an das neue Gerät.

  • DELETE /api/v1/pairing/{id} Papierhafen-Konto

    Kopplung abbrechen oder ablehnen.

  • GET /api/v1/employer Papierhafen-Konto

    Firmen, die diesem Konto Abrechnungen schicken.

  • GET /api/v1/employer/invite?token={token} öffentlich

    Welche Firma einlädt, vor dem Annehmen.

  • POST /api/v1/employer/join öffentlich

    Einladung annehmen, mit dem X25519-Postfach-Schlüssel; gibt das Postfach-Token. Mit X-Ordo-User gilt das Business der Firma für das Konto.

  • DELETE /api/v1/employer/{id} Postfach

    Verbindung zu einer Firma beenden.

  • GET /api/v1/inbox Postfach

    Wartende Abrechnungen, verschlüsselt an den Postfach-Schlüssel (Header X-Ordo-Inbox).

  • GET /api/v1/inbox/{id} Postfach

    Eine verschlüsselte Abrechnung laden.

  • DELETE /api/v1/inbox/{id} Postfach

    Abrechnung entfernen, nachdem die App sie im Tresor abgelegt hat.

  • POST /api/v1/inbox/push Postfach

    Gerät für Mitteilungen über neue Abrechnungen anmelden (APNs-Token). Die Mitteilung nennt weder Firma noch Beträge.

  • DELETE /api/v1/inbox/push Postfach

    Gerät wieder abmelden.

Lohnsoftware

Für Firmen mit Papierhafen Business: Die Lohnsoftware verschlüsselt jede Abrechnung selbst an den Postfach-Schlüssel des Mitarbeiters (X25519, HKDF, AES-256-GCM; Format in docs/PAYROLL.md, Werkzeug ordo-payroll). API-Schlüssel legen Inhaber und Admins auf der Firmenseite an.

  • GET /api/v1/payroll/employees API-Schlüssel

    Firma und verbundene Mitarbeiter mit Personalnummer und Postfach-Schlüssel. Prüfcodes berechnet der Client selbst.

  • POST /api/v1/payroll/employees/{id}/payslips API-Schlüssel

    Eine verschlüsselte Abrechnung zustellen (Body, höchstens 20 MB).

  • GET /api/v1/payroll/signing-key API-Schlüssel

    Der Signaturschlüssel der Firma, verschlüsselt mit ihrem Passwort, zum Signieren der Abrechnungen (docs/PAYROLL.md).

Papierhafen im Browser

Lesender Zugriff im Browser, entsperrt mit einem Passkey (docs/WEBVAULT.md). Ein Browser hat einen eigenen Web-Schlüssel; Sitzungen damit dürfen nur lesen.

  • POST /api/v1/webpair öffentlich

    Kopplung starten: Austausch- und Web-Schlüssel des Browsers (öffentlich), 5 Minuten gültig.

  • GET /api/v1/webpair/{id} öffentlich

    Auf die Freigabe warten; danach einmalig der an den Browser verschlüsselte Tresorschlüssel.

  • PUT /api/v1/webpair/{id} angemeldet

    Browser freigeben (nur eine App): die Schlüssel aus dem QR-Code und der verschlüsselte Tresorschlüssel.

  • GET /api/v1/webkeys angemeldet

    Freigegebene Browser.

  • DELETE /api/v1/webkeys/{id} angemeldet

    Einen Browser widerrufen: Schlüssel, verpackter Tresorschlüssel und Sitzungen werden gelöscht.

  • PUT /api/v1/webkeys/{id}/passkey Web-Sitzung

    Den mit dem Passkey verpackten Schlüssel hinterlegen, einmal, nur vom Browser selbst.

  • GET /api/v1/webkeys/credential/{credentialId} öffentlich

    Was ein Passkey öffnet: der verpackte Schlüssel, nutzlos ohne den Passkey.

Teilen per Link

Dokumente für jemanden ohne Papierhafen. Die App verschlüsselt ein Bündel; der Schlüssel steht nur im Link hinter dem #, den Browser nie senden.

  • POST /api/v1/shares Papierhafen-Konto

    Verschlüsseltes Bündel ablegen (Body), mit X-Ordo-Expires-Hours (1–720) und X-Ordo-Max-Views (0 = unbegrenzt). Gibt ID und Link ohne Schlüssel.

  • GET /api/v1/shares Papierhafen-Konto

    Eigene Links mit Ablauf und Aufrufen.

  • DELETE /api/v1/shares/{id} Papierhafen-Konto

    Link sofort zurückziehen; die Daten werden gelöscht.

  • GET /api/v1/shares/{id}/data öffentlich

    Das Chiffrat für die Seite /s/{id}; zählt einen Aufruf, danach 410.

Dokumente

Jedes Dokument ist eine verschlüsselte Datei plus verschlüsselte Metadaten. Der Server sieht nur Chiffretext.

  • GET /api/v1/items?since={cursor} angemeldet

    Änderungen seit einer Revision, seitenweise. Gelöschte kommen als Grabstein.

  • PUT /api/v1/items/{id}/blob angemeldet

    Verschlüsselte Datei hochladen. Header X-Ordo-Blob-SHA256 wird geprüft.

  • GET /api/v1/items/{id}/blob angemeldet

    Verschlüsselte Datei laden.

  • PUT /api/v1/items/{id} angemeldet

    Metadaten speichern, mit baseRevision gegen gleichzeitige Änderungen (409).

  • DELETE /api/v1/items/{id} angemeldet

    Dokument löschen.

Betrieb

Für Monitoring und Werkzeuge.

  • GET /api/v1/apps/mac öffentlich

    Neueste Mac-Version: Version, Link zur notarisierten DMG, SHA-256 und Größe. Die Mac-App prüft hier auf Updates.

  • GET /healthz öffentlich

    Lebenszeichen als JSON.

  • GET /api/openapi.json öffentlich

    Maschinenlesbare Beschreibung (OpenAPI 3).