api-description.yaml

openapi: "3.0.3"
info:
  title: "Cryptify API"
  description: "This is the cryptify server that manages encrypted files."
  version: "1.0.0"
servers:
  - url: http://localhost:8000
    description: Development server
tags:
- name: "Health"
  description: "Health check"
- name: "Metrics"
  description: "Prometheus scrape endpoint"
- name: "File upload"
  description: "Upload files"
- name: "File download"
  description: "Download files"
- name: "Usage"
  description: "Upload usage quotas"
paths:
  /health:
    get:
      tags:
        - "Health"
      summary: "Health check endpoint"
      operationId: "health"
      responses:
        "200":
          description: "Service is healthy"
          content:
            text/plain:
              schema:
                type: "string"
                example: "OK"
  /metrics:
    get:
      tags:
        - "Metrics"
      summary: "Prometheus text-format metrics"
      description: |
        Returns usage counters and gauges suitable for Prometheus scraping
        by the Grafana instance on Scaleway. Intended to be reachable only
        from the internal monitoring network; firewall or reverse-proxy
        allow-list in front of Cryptify.

        Exposed metrics:
          * `cryptify_uploads_total{channel}` — counter of finalized uploads.
          * `cryptify_upload_bytes_total{channel}` — counter of bytes.
          * `cryptify_storage_bytes` — gauge, current disk usage.
          * `cryptify_active_files` — gauge, current file count.
          * `cryptify_expired_files_total` — counter of uploads purged
             before finalization.

        The `channel` label is derived from the `X-Cryptify-Source` header,
        falling back to `Authorization`/`X-Api-Key` (→ `api`), then the
        `Origin` header (`website` / `staging-website`), then `User-Agent`
        (`outlook` / `thunderbird`), then `unknown`.
      operationId: "metrics"
      responses:
        "200":
          description: "Prometheus text exposition format"
          content:
            text/plain:
              schema:
                type: "string"
  /fileupload/init:
    post:
        tags:
        - "File upload"
        summary: "Initialize multipart file upload"
        operationId: "initFileUpload"
        requestBody:
          content:
            application/json:
              schema:
                type: "object"
                required:
                  - recipient
                  - mailContent
                  - mailLang
                  - confirm
                properties:
                  recipient:
                    type: "string"
                    format: "email"
                    example: "recipient@example.com"
                    description: "Email address of the recipient"
                  mailContent:
                    type: "string"
                    example: "Here is your encrypted file"
                    description: "Content to include in the email"
                  mailLang:
                    type: "string"
                    enum: ["EN", "NL"]
                    example: "EN"
                    description: "Email language (EN or NL)"
                  confirm:
                    type: "boolean"
                    example: true
                    description: "Whether to send a confirmation email to the sender"
                  notifyRecipients:
                    type: "boolean"
                    default: true
                    example: true
                    description: "Whether to email each recipient with a download link. Optional; defaults to true. Set to false to upload silently when the encrypted payload reaches recipients through another channel and a Cryptify-sent notification would be a duplicate."
        responses:
          "200":
            description: "Successful operation"
            headers:
                cryptifytoken:
                  description: "Identifies the initial version of the file to be uploaded. Needs to be passed into the file part upload request."
                  required: true
                  schema:
                    type: "string"
            content:
              application/json:
                schema:
                  type: "object"
                  required:
                    - uuid
                    - recovery_token
                  properties:
                    uuid:
                      type: "string"
                      format: "uuid"
                      description: "Unique identifier for the file upload"
                    recovery_token:
                      type: "string"
                      description:
                        "Bearer credential for the cross-refresh-resume
                        status endpoint (`GET /fileupload/{uuid}/status`).
                        The client should store this alongside the UUID
                        (e.g. in IndexedDB) and present it in an
                        `X-Recovery-Token` header to recover from a
                        page refresh, tab crash, or navigate-away-and-back.
                        Hex-encoded 32-byte random."
  /fileupload/{uuid}:
    put:
      tags:
      - "File upload"
      summary: "Upload a file part"
      description:
        "Append a single chunk to the upload identified by `uuid`.\n\n
        **Idempotent retry contract.** A chunk PUT whose response was lost
        in flight can be safely retried with the *previous* `cryptifytoken`
        value (the one the client sent on the failed attempt) at the same
        `Content-Range` offset and with the same body. The server detects
        this case — the request matches the cached `(prev_token, offset,
        length, sha256)` of the most recently committed chunk — and
        replays the previously returned `cryptifytoken` without
        re-writing the file or double-counting against quotas. If the
        request looks like a retry but the body bytes differ, the server
        responds 400; clients must not retry the same offset with
        different bytes.\n\n
        Retries are only honoured for the *most recently committed*
        chunk. If a client falls behind by more than one chunk it must
        start a new upload."
      operationId: "uploadFilePart"
      parameters:
      - in: "header"
        name: "cryptifytoken"
        description:
          "Identifies the version of the upload file parts. Part of the header from the last fileupload response. On a retry of a chunk whose response was lost, send the *previous* token (the one originally sent on the failed PUT)."
        schema:
          type: "string"
        required: true
      - in: "header"
        name: "Content-Range"
        description:
          "Which offset of a file is sent, example: `bytes 200-1000/*`."
        schema:
          type: "string"
        required: true
      - in: "path"
        name: "uuid"
        required: true
        description: "The unique identifier received when initializing file upload."
        schema:
          type: "string"
          format: "uuid"
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: "string"
              format: "binary"
      responses:
        "200":
          description: "Successful operation."
          headers:
            cryptifytoken:
              required: true
              schema:
                description: "Identifies the new version of the upload file parts. Needs to be passed into the next file part upload request."
                type: "string"
        "409":
          description: "Server file parts cryptifytoken differs from cryptifytoken in request."
          headers:
            cryptifytoken:
              required: true
              schema:
                description:
                  "Identifies the version of the upload file parts. Needs to be passed into the next file part upload request."
                type: "string"
        "400":
          description: "One of the input parameters is incorrect."
          content:
              application/json:
                schema:
                  type: "object"
                  properties:
                    message:
                      type: "string"
        "404":
          description:
            "The upload session is not known to the server. Either the
            client never called `/fileupload/init`, the session was idle
            past the configured TTL and got evicted, or the on-disk file
            has been removed. Clients should not retry — start a new
            upload via `/fileupload/init`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadSessionNotFound"
        "413":
          description: "The upload exceeds the per-upload size limit (5 GB for non-API-key uploads, 100 GB for API-key uploads)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayloadTooLarge"

  /fileupload/finalize/{uuid}:
    post:
      tags:
      - "File upload"
      summary: "Finalize multipart file upload and send mail to recipient"
      operationId: "finalizeFileUpload"
      parameters:
      - in: "header"
        name: "Content-Range"
        description:
          "Indicates the final file size: `bytes */1073741824`."
        schema:
          type: "string"
        required: true
      - in: "path"
        name: "uuid"
        description: "The unique identifier received when initializing file upload."
        required: true
        schema:
          type: "string"
          format: "uuid"
      responses:
        "200":
          description: "Successful operation"
        "409":
          description: "Server file parts cryptifytoken differs from cryptifytoken in request"
          headers:
            cryptifytoken:
              required: true
              schema:
                description: "Identifies the version of the upload file parts. Needs to be passed into the next file part upload request."
                type: "string"
        "400":
          description: "One of the input parameters is incorrect."
          content:
              application/json:
                schema:
                  type: "object"
                  properties:
                    message:
                      type: "string"
        "404":
          description:
            "The upload session is not known to the server (see
            `/fileupload/{uuid}` 404 for details). Clients should not
            retry — start a new upload via `/fileupload/init`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadSessionNotFound"
        "413":
          description: "The sender has exceeded the rolling 14-day upload limit (5 GB for non-API-key uploads, 100 GB for API-key uploads)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayloadTooLarge"
        "422":
          description: "Data is missing to form complete file."

  /fileupload/{uuid}/status:
    get:
      tags:
      - "File upload"
      summary: "Read upload state for cross-refresh resume"
      description:
        "Returns the rolling-token state of an in-flight upload so a
        client that lost track of the session (page refresh, tab crash,
        navigate-away-and-back) can rehydrate and feed the next chunk
        PUT through the idempotent-retry path
        (`PUT /fileupload/{uuid}`). Authenticates via the
        `X-Recovery-Token` header issued at `upload_init`. **Behaviour
        on resume conflict:** if two clients hold the same UUID and
        recovery token (e.g. two tabs), the first chunk PUT to land
        wins and the second sees a 4xx as soon as it tries to advance
        past the now-stale state — single-active-resumer semantics, no
        lease enforcement on the server side. A successful call also
        resets the session's idle eviction deadline so the very next
        chunk PUT does not 404 because the rehydrate window aged out."
      operationId: "uploadStatus"
      parameters:
      - in: "header"
        name: "X-Recovery-Token"
        description:
          "Bearer credential issued in the `recovery_token` field of
          the `upload_init` response. Compared in constant time on the
          server. Missing / empty → 401."
        schema:
          type: "string"
        required: true
      - in: "path"
        name: "uuid"
        required: true
        description: "The unique identifier received when initializing file upload."
        schema:
          type: "string"
          format: "uuid"
      responses:
        "200":
          description: "Successful operation."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadStatus"
        "401":
          description:
            "Missing or empty `X-Recovery-Token` header. Note: a
            *valid-format* token that simply does not match the stored
            value returns 404 with the same body shape as an evicted
            session, deliberately, so attackers cannot probe for live
            UUIDs by varying the token."
        "404":
          description:
            "The upload session is not known to the server, OR the
            recovery token does not match the stored value. The two
            cases are deliberately collapsed — same response shape as
            `PUT /fileupload/{uuid}` — to avoid leaking session
            existence."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadSessionNotFound"

  /usage:
    get:
      tags:
      - "Usage"
      summary: "Get rolling upload usage for a sender email"
      description:
        "Returns the bytes uploaded by the given email address in the last 14 days,
        together with the applicable limits. Frontends use this to warn the user
        before they hit the limit."
      operationId: "getUsage"
      parameters:
      - in: "query"
        name: "email"
        description: "The sender email address to query."
        required: true
        schema:
          type: "string"
          format: "email"
      responses:
        "200":
          description: "Usage information for the given email."
          content:
            application/json:
              schema:
                type: "object"
                required:
                  - email
                  - used_bytes
                  - limit_bytes
                  - window_days
                  - per_upload_limit_bytes
                properties:
                  email:
                    type: "string"
                    format: "email"
                  used_bytes:
                    type: "integer"
                    format: "int64"
                    description: "Bytes uploaded by this email in the rolling window."
                  limit_bytes:
                    type: "integer"
                    format: "int64"
                    description: "Rolling-window upload limit in bytes for the requesting sender (5 GB for non-API-key uploads, 100 GB for API-key uploads)."
                  window_days:
                    type: "integer"
                    description: "Length of the rolling window in days."
                  per_upload_limit_bytes:
                    type: "integer"
                    format: "int64"
                    description: "Maximum size of a single upload in bytes for the requesting sender (5 GB for non-API-key uploads, 100 GB for API-key uploads)."
                  resets_at:
                    type: "string"
                    format: "date-time"
                    nullable: true
                    description:
                      "RFC-3339 timestamp at which the oldest recorded upload
                      falls out of the rolling window, partially freeing quota.
                      Null if the sender has no recorded uploads."

  /filedownload/{uuid}:
    get:
      tags:
      - "File download"
      summary: "Download a file"
      operationId: "downloadFile"
      parameters:
      - in: "path"
        name: "uuid"
        required: true
        description: "The unique identifier received when initializing file upload."
        schema:
          type: "string"
          format: "uuid"
      responses:
        "200":
          description: "Successful operation."
          content:
            application/cryptify+octet-stream:
              schema:
                type: "string"
                format: "binary"
        "400":
          description: "One of the input parameters is incorrect."
          content:
              application/json:
                schema:
                  type: "object"
                  properties:
                    message:
                      type: "string"
        "404":
          description: "Uploaded file does not exist."

components:
  schemas:
    PayloadTooLarge:
      type: "object"
      required:
        - error
        - limit
        - used_bytes
        - limit_bytes
      properties:
        error:
          type: "string"
          description: "Human-readable explanation of which limit was hit."
        limit:
          type: "string"
          enum:
            - "per_upload"
            - "rolling_window"
          description: "Which limit tripped the 413 response."
        used_bytes:
          type: "integer"
          format: "int64"
          description:
            "Bytes already attributed to the sender in the relevant window.
            For per_upload, this is the bytes already written for the current
            upload before the rejected chunk."
        limit_bytes:
          type: "integer"
          format: "int64"
          description: "The limit value in bytes."
    UploadSessionNotFound:
      type: "object"
      required:
        - error
        - uuid
        - reason
      properties:
        error:
          type: "string"
          enum:
            - "upload_session_not_found"
          description: "Stable machine-readable error code for clients."
        uuid:
          type: "string"
          format: "uuid"
          description: "The upload UUID the request targeted."
        reason:
          type: "string"
          enum:
            - "expired_or_unknown"
            - "invalid_uuid"
            - "file_missing"
          description:
            "Why the session is not retrievable. `expired_or_unknown`
            means the session was either evicted after its idle TTL or
            never existed (clients cannot tell these apart, by design).
            `invalid_uuid` means the path UUID is malformed.
            `file_missing` means the in-memory session exists but the
            on-disk file is gone (server-state inconsistency)."
    UploadStatus:
      type: "object"
      required:
        - uploaded
        - cryptify_token
      properties:
        uploaded:
          type: "integer"
          format: "int64"
          description:
            "Total bytes the server has committed for this upload so far.
            The client should resume from this offset."
        cryptify_token:
          type: "string"
          description:
            "Current value of the rolling token. The client must send this
            as `cryptifytoken` on the next chunk PUT."
        prev_token:
          type: "string"
          description:
            "Token the client sent on the most recently committed chunk
            (i.e. the value of `cryptify_token` *before* that chunk
            advanced it). Combined with `prev_offset`, lets the client
            re-issue the most recent chunk on the idempotent-retry path
            (PUT `/fileupload/{uuid}`) if it is unsure whether the chunk
            was committed. Omitted until at least one chunk has been
            committed."
        prev_offset:
          type: "integer"
          format: "int64"
          description:
            "Byte offset where the most recently committed chunk started
            (i.e. `uploaded - chunk_len`). Omitted until at least one
            chunk has been committed."