initial commit

2026-07-13 01:45:37 +02:00
commit ecbb8bba9b
14 changed files with 1685 additions and 0 deletions
--- a/docs/filedrop-integration-contract.md
+++ b/docs/filedrop-integration-contract.md
@@ -0,0 +1,134 @@
+# File Drop Integration Contract
+
+Version: `filedrop.v1`
+
+The File Drop service is backend/API-first. UI code is only an integration example. Host systems discover an active dropbox, encrypt locally to the advertised recipient key, then commit ciphertext and the E2EE envelope to the intake endpoint.
+
+## Discovery
+
+`GET /api/dropbox/current`
+
+Response:
+
+```json
+{
+  "contractVersion": "filedrop.v1",
+  "dropboxId": "default",
+  "fingerprint": "recipient-key-fingerprint",
+  "key": {
+    "fingerprint": "recipient-key-fingerprint",
+    "publicKey": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." },
+    "source": "configured",
+    "status": "active"
+  },
+  "label": "Interling secure intake",
+  "publicKey": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." },
+  "source": "configured",
+  "status": "active",
+  "recipientKeys": [
+    {
+      "fingerprint": "recipient-key-fingerprint",
+      "publicKey": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." },
+      "source": "configured",
+      "status": "active"
+    },
+    {
+      "fingerprint": "master-recovery-fingerprint",
+      "publicKey": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." },
+      "source": "configured",
+      "status": "active"
+    }
+  ]
+}
+```
+
+Integrations must show or otherwise pin the recipient `fingerprint` where key authenticity matters.
+
+The `key.status` value is one of `active`, `rotating`, or `revoked`. Upload UIs must not accept new files for revoked keys.
+
+## Upload Commit
+
+`POST /api/uploads/intake`
+
+Content type: `multipart/form-data`
+
+Fields:
+
+- `ciphertext`: encrypted file bytes.
+- `envelope`: JSON E2EE envelope from `@addideas/sefidrop/e2ee`.
+- `contactName`: sender name.
+- `contactEmail`: sender email.
+- `dropboxId`: discovery response id.
+- `routingLabel`: operational routing label.
+- `serviceType`: optional operational service type.
+- `languagePair`: optional operational language pair.
+- `requestedDeadline`: optional operational date.
+- `projectPublicId`: optional existing order id for project-specific drop links.
+
+The original filename, note, MIME type, and other sensitive sender metadata stay in the encrypted E2EE metadata envelope.
+New integrations should encrypt to every active `recipientKeys[]` entry and submit an envelope with `recipients[]`. The legacy `recipient` field remains required and mirrors the first recipient wrap for older consumers.
+
+Response:
+
+```json
+{
+  "id": "upload-id",
+  "orderId": "INTAKE-20260710-XXXXXXXX",
+  "storageKey": "upload-id.enc",
+  "status": "ciphertext_received"
+}
+```
+
+## Event
+
+Each accepted upload emits a `filedrop.upload.received` event. Interling records that event in `project_events`, links the ciphertext row to an order, and exposes it in the portal timeline.
+
+The event payload is intentionally host-neutral:
+
+```json
+{
+  "contractVersion": "filedrop.v1",
+  "eventType": "filedrop.upload.received",
+  "occurredAt": "2026-07-10T17:32:07.000Z",
+  "sender": { "contactEmail": "client@example.com" },
+  "routing": {
+    "dropboxId": "default",
+    "serviceType": "translation",
+    "languagePair": "DE -> EN"
+  },
+  "storage": {
+    "driver": "local",
+    "key": "upload-id.enc",
+    "manifestKey": "upload-id.json"
+  },
+  "upload": {
+    "id": "upload-id",
+    "ciphertextByteLength": 12345,
+    "ciphertextSha256": "base64url-sha256",
+    "recipientKeyFingerprint": "recipient-key-fingerprint",
+    "recipientKeyFingerprints": ["recipient-key-fingerprint", "master-recovery-fingerprint"]
+  }
+}
+```
+
+## Webhook Signature
+
+Future standalone deployments can deliver the same event via webhook instead of direct DB integration.
+
+Signed webhook deliveries use these headers:
+
+- `x-filedrop-webhook-id`: stable id for idempotency.
+- `x-filedrop-timestamp`: Unix timestamp in seconds.
+- `x-filedrop-signature`: HMAC-SHA256 signature, formatted as `v1=<hex>`.
+
+The signature input is:
+
+```txt
+<timestamp>.<raw request body>
+```
+
+Receivers should reject old timestamps and verify the signature with a shared webhook secret.
+
+## Storage Boundary
+
+The package exposes a `FileDropStorage` interface. The current Interling host uses the local filesystem adapter; a standalone service can provide S3-compatible storage without changing the upload commit contract.