initial commit

docs/return-file-key-model.md

@@ -0,0 +1,59 @@
+# Return File Key Model
+
+File drops and returned deliverables use the same browser-only cryptographic boundary, but they need different recipient discovery.
+
+## Principle
+
+The server stores ciphertext, public keys, key fingerprints, wrapped content keys, routing metadata, and audit events. It must not receive private keys or plaintext file bytes.
+
+Each encrypted file should have one content key and one or more recipient key wraps:
+
+- office intake key for incoming client material;
+- assigned contractor key for source files that need contractor access;
+- client account key for deliverables returned through the portal;
+- master recovery key for operational recovery.
+
+The existing single-recipient envelope remains valid for simple file drops. New envelopes include `recipients[]` while keeping the legacy `recipient` field readable.
+
+## Client Delivery
+
+Client accounts need a recipient key pair before they can receive encrypted deliverables.
+
+Recommended flow:
+
+1. The browser creates or imports a P-256 recipient key pair.
+2. The private key stays browser-side and can be downloaded as a JSON key file or pasted/imported later.
+3. The public key and fingerprint are registered with the host system.
+4. Deliverables are encrypted in the browser to the client public key and the master recovery public key.
+5. The client decrypts in the browser by presenting the private key file or pasted private key.
+
+For non-technical clients, the private-key file is the least ambiguous first UX. Passphrase-protected key files can be added later.
+
+## Contractor Access
+
+Contractors should have their own registered public key. When a source file needs contractor access, an authorized office browser decrypts or unwraps the content key and re-encrypts/rewraps it to the contractor key. The server only receives the updated recipient wrap.
+
+Contractor deliverables are uploaded as encrypted ciphertext and recorded as a source-deliverable pair:
+
+- source file id;
+- deliverable file id;
+- contractor user id;
+- delivery status and review timestamps.
+
+## Master Recovery Key
+
+The master recovery key is a public key configured in the host system. Its private key should be kept offline or in a controlled operator keystore, never in the application database.
+
+Every real encrypted file should include a master recipient wrap. Recovery is then possible by importing the master private key in a browser-only operator tool and re-encrypting the content key to a new client or contractor key.
+
+## Host API Shape
+
+A host system should provide:
+
+- recipient key registration for account keys;
+- active public-key discovery for client, contractor, office, and master recipients;
+- encrypted file upload for source and deliverable purposes;
+- recipient wrap update for assignment/recovery workflows;
+- encrypted file download with access checks only.
+
+The host remains responsible for orders, users, payment state, permissions, and audit trails. Sefidrop remains responsible for the ciphertext and envelope contract.