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:

{
  "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:

{
  "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:

{
  "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:

<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.

4.1 KiB Raw Blame History