directus-extension-constrained-file-interface/README.md

Add file upload/select interface that allows for folder, storage, and MIME type constraints.

# Directus Constrained File Interface

⚠️ Experimental. Please expect breaking changes without major version bumps until this extension reaches `1.0.0`.

Extended from the default Directus `file` interface to let you enforce folder, storage, and allowed MIME type restrictions when selecting or uploading files.

- Limit uploaded/selected files to a specific storage medium (must exist in Directus STORAGE_LOCATIONS).
- Limit uploaded/selected files to specific folder (must already exist in Directus).
- Limit the MIME type(s) allowed for uploaded/selected files (exact matches only).

The ideal would be that Directus eventually supports these constraints out of the box with the default file interface, in which case this extension would become redundent.

Note: this is a UI interface only. It does not enforce any restrictions when uploading/selecting files via the Directus API.

See also the multi-file variant: (`directus-extension-constrained-files-interface`)[https://www.npmjs.com/package/directus-extension-constrained-files-interface].

## Installation

Install into your Directus project's extension directory:

```sh
npm install directus-extension-constrained-file-interface
# or
pnpm add directus-extension-constrained-file-interface
# or
bun add directus-extension-constrained-file-interface
```

If `EXTENSIONS_AUTO_RELOAD` is enabled, the extension will show up in Directus automatically after installation. Otherwise, restart the Directus instance.

## Usage

In Directus' Data Model editor, add a field to a collection and choose the `Constrained File` interface. Alternatively, if creating/updating the schema via the API, specify `constrained-file` as the interface, e.g.

```json
{
  "field": "secure-file-upload",
  "type": "uuid",
  "meta": {
    "interface": "constrained-file",
    "options": {
      "storageConstraint": "s3_backup",
      "folderConstraint": "00000000-0000-0000-0000-000000000000",
      "mimeTypesConstraint": "image/png,image/jpeg",
      "enableCreate": true,
      "enableSelect": true
    }
  }
}
```

Remember to add the appropriate relations etc.

Below are the available options when configuring the field:

| Option                      | Description                                                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| storageConstraint           | Storage driver key uploads must use. Empty = use default storage.                                                            |
| folderConstraint            | Folder ID to constrain selection/upload. Empty = any folder.                                                                 |
| mimeTypesConstraint         | Comma-separated list of exact MIME types (e.g. `image/png,image/jpeg`). Empty = no restriction. Wildcards are not supported. |
| filter                      | Additional system filter merged with the above constraints.                                                                  |
| enableCreate / enableSelect | Toggle create (upload) and library selection buttons.                                                                        |

## Versioning

See [CHANGELOG](CHANGELOG.md) for changes.

## License

MIT © Entle