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 pha_….
Server
Was dieser Server ist und ob er zur App passt.
-
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öffentlichKonto anlegen: Konto-ID, öffentlicher Schlüssel, verpackter Master-Key, ggf. Einladungscode.
- POST
/api/v1/auth/challengeöffentlichEinmalige Challenge holen, 2 Minuten gültig. Auch für unbekannte Konten.
- POST
/api/v1/auth/sessionöffentlichSignierte Challenge gegen ein Bearer-Token tauschen; mit webKeyId eine lesende Browser-Sitzung.
- DELETE
/api/v1/auth/sessionangemeldetDieses Gerät abmelden.
- GET
/api/v1/accountangemeldetVerpackter Master-Key, Speicherverbrauch und Kontingent.
- PUT
/api/v1/account/keyangemeldet + frische SignaturMaster-Key neu verpackt speichern, wenn der Notfallschlüssel gewechselt wird.
- POST
/api/v1/account/deleteangemeldet + frische SignaturKonto mit allen Dokumenten endgültig löschen.
- GET
/api/v1/account/sessionsangemeldetAngemeldete Geräte.
- DELETE
/api/v1/account/sessions/{id}angemeldetEin Gerät abmelden.
Papierhafen-Konto
Auf Servern mit Papierhafen-Konten (PAPIERHAFEN_ACCOUNTS): Die App meldet sich über /connect im Browser an und bekommt ein Geräte-Token für den Header X-Papierhafen-User.
- POST
/api/v1/connect/tokenöffentlichDen einmaligen Code von /connect mit dem PKCE-Verifier gegen ein Geräte-Token tauschen.
- GET
/api/v1/mePapierhafen-KontoE-Mail, Name, verknüpfter Tresor, verbundene Apps und Version des Profilbilds.
- GET
/api/v1/me/avatarPapierhafen-KontoDas eigene Profilbild (JPEG), nur für dieses Konto.
- PUT
/api/v1/me/avatarPapierhafen-KontoProfilbild setzen: JPEG oder PNG, 32 bis 1024 Pixel, höchstens 2 MB; wird neu kodiert.
- DELETE
/api/v1/me/avatarPapierhafen-KontoProfilbild entfernen.
- POST
/api/v1/pairingPapierhafen-KontoNeues Gerät koppeln: X25519-Schlüssel hinterlegen, 10 Minuten gültig.
- GET
/api/v1/pairingPapierhafen-KontoGeräte, die auf Freigabe warten.
- GET
/api/v1/pairing/{id}Papierhafen-KontoStand der Kopplung; nach Freigabe einmalig mit dem verschlüsselten Notfallschlüssel.
- PUT
/api/v1/pairing/{id}Papierhafen-KontoFreigeben: Notfallschlüssel, verschlüsselt an das neue Gerät.
- DELETE
/api/v1/pairing/{id}Papierhafen-KontoKopplung abbrechen oder ablehnen.
- GET
/api/v1/employerPapierhafen-KontoFirmen, die diesem Konto Abrechnungen schicken.
- GET
/api/v1/employer/invite?token={token}öffentlichWelche Firma einlädt, vor dem Annehmen.
- POST
/api/v1/employer/joinöffentlichEinladung annehmen, mit dem X25519-Postfach-Schlüssel; gibt das Postfach-Token. Mit X-Papierhafen-User gilt das Business der Firma für das Konto.
- DELETE
/api/v1/employer/{id}PostfachVerbindung zu einer Firma beenden.
- GET
/api/v1/inboxPostfachWartende Abrechnungen, verschlüsselt an den Postfach-Schlüssel (Header X-Papierhafen-Inbox).
- GET
/api/v1/inbox/{id}PostfachEine verschlüsselte Abrechnung laden.
- DELETE
/api/v1/inbox/{id}PostfachAbrechnung entfernen, nachdem die App sie im Tresor abgelegt hat.
- POST
/api/v1/inbox/pushPostfachGerät für Mitteilungen über neue Abrechnungen anmelden (APNs-Token). Die Mitteilung nennt weder Firma noch Beträge.
- DELETE
/api/v1/inbox/pushPostfachGerä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 papierhafen-payroll). API-Schlüssel legen Inhaber und Admins auf der Firmenseite an.
- GET
/api/v1/payroll/employeesAPI-SchlüsselFirma und verbundene Mitarbeiter mit Personalnummer und Postfach-Schlüssel. Prüfcodes berechnet der Client selbst.
- POST
/api/v1/payroll/employees/{id}/payslipsAPI-SchlüsselEine verschlüsselte Abrechnung zustellen (Body, höchstens 20 MB).
- GET
/api/v1/payroll/signing-keyAPI-SchlüsselDer 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öffentlichKopplung starten: Austausch- und Web-Schlüssel des Browsers (öffentlich), 5 Minuten gültig.
- GET
/api/v1/webpair/{id}öffentlichAuf die Freigabe warten; danach einmalig der an den Browser verschlüsselte Tresorschlüssel.
- PUT
/api/v1/webpair/{id}angemeldetBrowser freigeben (nur eine App): die Schlüssel aus dem QR-Code und der verschlüsselte Tresorschlüssel.
- GET
/api/v1/webkeysangemeldetFreigegebene Browser.
- DELETE
/api/v1/webkeys/{id}angemeldetEinen Browser widerrufen: Schlüssel, verpackter Tresorschlüssel und Sitzungen werden gelöscht.
- PUT
/api/v1/webkeys/{id}/passkeyWeb-SitzungDen mit dem Passkey verpackten Schlüssel hinterlegen, einmal, nur vom Browser selbst.
- GET
/api/v1/webkeys/credential/{credentialId}öffentlichWas 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/sharesPapierhafen-KontoVerschlüsseltes Bündel ablegen (Body), mit X-Papierhafen-Expires-Hours (1–720) und X-Papierhafen-Max-Views (0 = unbegrenzt). Gibt ID und Link ohne Schlüssel.
- GET
/api/v1/sharesPapierhafen-KontoEigene Links mit Ablauf und Aufrufen.
- DELETE
/api/v1/shares/{id}Papierhafen-KontoLink sofort zurückziehen; die Daten werden gelöscht.
- GET
/api/v1/shares/{id}/dataöffentlichDas 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}/blobangemeldetVerschlüsselte Datei hochladen. Header X-Papierhafen-Blob-SHA256 wird geprüft.
- GET
/api/v1/items/{id}/blobangemeldetVerschlüsselte Datei laden.
- PUT
/api/v1/items/{id}angemeldetMetadaten speichern, mit baseRevision gegen gleichzeitige Änderungen (409).
- DELETE
/api/v1/items/{id}angemeldetDokument löschen.
Betrieb
Für Monitoring und Werkzeuge.
- GET
/api/v1/apps/macöffentlichNeueste Mac-Version: Version, Link zur notarisierten DMG, SHA-256 und Größe. Die Mac-App prüft hier auf Updates.
-
Lebenszeichen als JSON.
-
Maschinenlesbare Beschreibung (OpenAPI 3).