# File Backend

## Purpose

The file slice handles binary file upload and download. Uploaded files are stored either on
local disk (development) or in Google Cloud Storage (production), selected at request time. The
`file` table records file metadata (name, URLs, owning relation) and is written indirectly by the
file DAL when entity relations are persisted, not by the upload endpoint itself.

## Slice Files (by layer)

- Route: `src/routes/file.ts` (thin wiring; `GET /download`, `POST /upload/:table/:field`).
- Controller: `src/api/controllers/file.controller.ts` (custom — `download` and `upload`). `download`
  calls `assertCanDownloadFile` before serving.
- Service (BLL): `src/services/file.ts` (`uploadLocal`, `downloadLocal`, `uploadGCloud`,
  `downloadGCloud`, `deleteGCloud`, `initGCloud`) for the storage I/O, plus
  `src/services/file-access.ts` (`assertCanDownloadFile`) for the per-file authorization. Both
  upload and download require JWT; local handlers reject path traversal. Download enforces a
  per-file tenant/ownership check: the file's owning organization (resolved from its `privateUrl`
  via the uploader `createdById`) must match the requester's organization, unless the requester
  has global access; files with no tracked row are denied. (Upload-side per-file ownership and a
  typed frontend upload client are still open — tracked in the file workstream.)
- Repository (DAL): `src/db/api/file.ts` (`FileDBApi` — `replaceRelationFiles`, `_addFiles`,
  `_removeLegacyFiles`); persists/removes `file` rows for entity relations. Note: this DAL imports
  `@/services/file` to call `deleteGCloud` (see Behavior / Notes).
- Model: `src/db/models/file.ts`.
- Shared used: `api/http/request.ts` (`paramStr`), `middlewares/upload.ts` (`processFile` multer
  wrapper), `shared/config.ts` (`config.uploadDir`, `config.gcloud.bucket`, `config.gcloud.hash`),
  `shared/errors/validation.ts` (`ValidationError`, in the DAL).

## API

- `GET /api/file/download?privateUrl=<path>` -> downloads the file. **Requires JWT authentication**
  (`passport.authenticate('jwt')`) **and per-file ownership**: `assertCanDownloadFile` resolves the
  file's owning organization (via `FileDBApi.findOwnerOrganizationIdByPrivateUrl`, which reads the
  uploader `createdById`) and returns `403` (`ForbiddenError`) unless the requester has global
  access or shares that organization; an untracked `privateUrl` is also `403`. The controller then
  dispatches to `downloadGCloud` when `NODE_ENV === 'production'` or `NEXT_PUBLIC_BACK_API` is set,
  otherwise `downloadLocal`.
  - Local: missing `privateUrl` -> `404`; a `privateUrl` that escapes the upload dir (path
    traversal via `..`) -> `403` (`resolveWithinUploadDir`); otherwise streams via `res.download`
    from `config.uploadDir`.
  - GCloud: serves `${hash}/${privateUrl}` from the bucket; file missing or error -> `404`
    `{ message }`.
- `POST /api/file/upload/:table/:field` -> uploads a single file. Requires JWT authentication
  (`passport.authenticate('jwt')`). The folder is computed as `:table/:field`. Dispatches to
  `uploadGCloud` when `NODE_ENV === 'production'` or `NEXT_PUBLIC_BACK_API` is set, otherwise
  `uploadLocal`. The multipart form field name is `file`; the destination filename is taken from the
  request body field `filename`.
  - Local: no `req.currentUser` -> `403`; missing file -> `400`; missing `filename` -> `500`;
    success -> `200` (empty body). Errors -> `500` with the stringified error.
  - GCloud: missing file -> `400` `{ message }`; success -> `200`
    `{ message, url }` where `url` is the public `storage.googleapis.com` URL; errors -> `500`
    `{ message }`.

## Access Rules

- Upload requires a valid JWT (route-level passport auth). The local upload path additionally
  rejects when `req.currentUser` is absent (`403`) and when an `entity` validation is supplied
  (`403`); the controller calls `uploadLocal` with `entity: null`, so the entity branch is not
  exercised from this endpoint.
- Download has no authentication middleware and performs no ownership check; access is governed
  solely by knowing the `privateUrl`.

## Tenant Scope

None enforced in this slice. Neither upload nor download filters by organization; files are keyed
by the `:table/:field` folder, the `filename`, and (for GCloud) the configured `hash` prefix. The
`file` model has no `organizationId` column.

## Data Contract

`file` model columns: `id` (UUID, PK), `belongsTo` (string, nullable), `belongsToId` (UUID,
nullable), `belongsToColumn` (string, nullable), `name` (string, required, non-empty),
`sizeInBytes` (integer, nullable), `privateUrl` (string, nullable), `publicUrl` (string, required,
non-empty), `createdAt`, `updatedAt`, `deletedAt` (paranoid soft delete), `createdById` (UUID,
nullable), `updatedById` (UUID, nullable). Associations: `belongsTo` users as `createdBy` and
`updatedBy`.

In the DAL (`replaceRelationFiles` / `_addFiles`), each new file requires `name` and `publicUrl`,
otherwise `ValidationError('iam.errors.fileNameRequired')` is raised.

## Behavior / Notes

- Storage backend is chosen per request from `NODE_ENV` / `NEXT_PUBLIC_BACK_API`: GCloud in
  production, local disk otherwise.
- The upload middleware (`src/middlewares/upload.ts`) uses multer memory storage with a 10 MB file
  size limit on the field named `file`. The controller passes `maxFileSize: 10 * 1024 * 1024` to
  `uploadLocal`, though that value is not consulted by `uploadLocal` (the limit comes from multer).
- `services/file.ts` still operates directly on Express `Request`/`Response` (streaming
  upload/download). This is a documented architecture exception: the import-boundaries test
  (`src/shared/architecture/import-boundaries.test.ts`) allows the BLL→HTTP dependency only for
  `services/file.ts` and `services/auth.ts`.
- `src/db/api/file.ts` imports `@/services/file` (calling `deleteGCloud` when removing legacy
  files), which is a DAL→BLL dependency. The same import-boundaries test caps DAL→BLL violations at
  one, and this file is the allowed one.
- `FileDBApi.replaceRelationFiles` syncs a relation's files: it deletes existing `file` rows not
  present in the input (removing the GCloud object first when `privateUrl` is set) and creates rows
  for inputs marked `new`.

## Tests

No dedicated `file` unit/e2e test exists. The architecture test
`src/shared/architecture/import-boundaries.test.ts` references this slice by name in its
BLL→HTTP and DAL→BLL debt-ceiling assertions.

## Related

- `search.md` (the other backend infrastructure slice).
- Architecture contract: `backend/docs/backend-architecture.md`.