Skip to content

Bot protection (CAPTCHA) ​

filex can put a bot check on the forms anybody can post without an account: the sign-in, a demo's one-click sign-in, the PIN of a protected link and the upload into a file request. The check is Cloudflare Turnstile (free, cookieless, invisible to most people) or Google reCAPTCHA v2 (the checkbox). It is off until you turn it on, so an upgrade changes nothing for an installation that does not.

When the provider cannot be reached, the form is neither left open nor shut: the browser does a short proof of work instead (one to three seconds on a desktop), and the administrators are told. See When the provider is down.


Turning it on ​

  1. Create a widget at the provider. For Turnstile: the Cloudflare dashboard → Turnstile → Add widget, mode Managed, and the host name filex is served on (a host name covers its subdomains). The site does not have to be proxied by Cloudflare. For reCAPTCHA: a v2 "I'm not a robot" key pair at the admin console.
  2. In filex: Admin → Bot protection. Pick the provider, paste the site key and the secret key, choose the forms, Test the keys (filex asks the provider with the keys on the page: is it reachable, does it take the secret), Save.

Or from the environment, for an installation provisioned from compose:

yaml
environment:
  CAPTCHA_PROVIDER: turnstile
  CAPTCHA_SITE_KEY: 0x4AAAAAAA...
  CAPTCHA_SECRET: ${CAPTCHA_SECRET}      # from your secret store
  CAPTCHA_FORMS: login,share_password,file_request   # optional; default: all

The secret typed on the page is sealed with the installation's encryption key (FILEX_SECRET_KEY, CONFIGURATION.md → The secret key) and never shown again: the page says only that one is stored. An installation without FILEX_SECRET_KEY cannot store it there; give it through CAPTCHA_SECRET.

The settings ​

SettingPanelEnvironmentDefaultValues
captcha.providerProviderCAPTCHA_PROVIDERnone (off)none, turnstile, recaptcha
captcha.site_keySite keyCAPTCHA_SITE_KEY-the provider's public key; it goes to the browser
captcha.secretSecret keyCAPTCHA_SECRET-the provider's secret; sealed in the database, never answered
captcha.formsFormsCAPTCHA_FORMSevery formlogin, demo_login, share_password, file_request (comma-separated in the environment)
captcha.fallbackWhen the provider cannot be reached: Local check / RefuseCAPTCHA_FALLBACKlocallocal; off (Refuse) answers 503 instead of the proof of work (for tests only)
captcha.verify_timeout_msProvider timeout (ms)CAPTCHA_VERIFY_TIMEOUT_MS40001000-15000; each call to the provider, tried twice at most

Which value is in force: the panel, then the environment, then off - field by field. A field you saved on the page wins over its variable; a field you cleared there is the variable's again.

⚠ This is not how filex's other database settings use the environment. Those read their variable once, at the first boot, into the database (CONFIGURATION.md), and the variable is inert after that. The bot check's variables are read live whenever the panel's field is empty: the order is the one every product that shares this bot check uses. Changing CAPTCHA_SITE_KEY in compose and restarting therefore takes effect, unless the page holds a site key of its own.

A provider is chosen and a key is missing - no site key, no secret, a stored secret that does not open (did FILEX_SECRET_KEY change?), or a secret the provider refuses - is a misconfiguration, not "off": the protected forms are checked with the local proof of work and the administrators are told until the keys are fixed. The protection never switches itself off.

The forms ​

FormWhat it protects
loginThe password sign-in on the sign-in page, including the recovery sign-in an SSO installation offers (SSO.md), on the platform's address and on every tenant's
demo_loginA demo's one-click sign-in with its documented account (DEMO.md); any other account on a demo is login
share_passwordThe PIN a protected link asks for: a download share, an app's page and a file request (SHARING.md)
file_requestThe upload into a file request (SHARING.md → File requests)

filex has no self-registration and no "forgot password" form (accounts come from an administrator, a directory or SSO, and only an administrator resets a password), so it has no register or password_reset form.

What a visitor sees ​

On the sign-in page and on a public link's page, the widget sits above the form's button. Turnstile in managed mode usually decides by itself in a second; sometimes it asks for a click. The form waits for its answer and sends it with the request; after every attempt - a wrong password too - the widget gives a new one.

  • JavaScript is needed. The check runs in the browser. While a link's PIN or a file request's upload is protected, the pages filex draws for a browser without JavaScript (/s/<token>?nojs=1, the classic /d/<token> page) and a PIN in the address (?pin=, X-Filex-Pin) are refused with 422 - JavaScript needed: none of them can carry the check, and a bot would otherwise use them to go around it. A link without a PIN still downloads with curl as before; the form that is not protected is as it was.
  • The CLI cannot answer a bot check either. While login is protected, filex client login with a password is refused and says so: create an API key in the browser (Connections → API keys) and use it with FILEX_TOKEN (CLI.md). Nothing goes around the check.
  • The desktop app signs in through the browser (DESKTOP.md), on the same sign-in page, so it sees the same widget.
  • An ad blocker that keeps the provider's script from loading is not an outage (filex can still reach the provider): the widget says it could not be loaded and asks to allow it.

How a form is checked ​

The form sends the provider's token with the request (captcha_token; the providers' own names cf-turnstile-response and g-recaptcha-response are read too). Before anything else - before a password is compared or a PIN attempt counted - filex asks the provider's siteverify:

What happenedAnswer
The form is not protected, or the check is offthe request goes on as before
No token, a token of the wrong shape (longer than the provider's tokens, characters outside A-Z a-z 0-9 . _ -; refused without asking the provider), a token already used, or the provider said no (success: false, or an HTTP 4xx - 429 included)422 {error, message, captcha: <reason>}: the widget is reset, a new attempt needs a new answer
The provider could not be reached: no connection, no answer in time, an HTTP 5xx, an answer that is not its JSON, internal-error (each asked twice)409 with a local challenge (below)
The keys cannot work (misconfiguration: invalid-input-secret, missing-input-secret, sitekey-secret-mismatch, invalid-keys, or a key missing on this side)409 with a local challenge, and the administrators are told
The provider is down and captcha.fallback is off503

⚠ A 4xx from the provider is never an outage. If it were, anybody could make the provider rate-limit a form (429) and earn the cheap proof of work instead of the widget. bad-request is a refused token too: the token comes from the client.

A token is accepted once: filex keeps the ones it accepted for five minutes and refuses them again (the provider refuses a reused one as well).

When the provider is down ​

The 409 carries a challenge; the browser solves it in a Web Worker (a progress bar and the words "The verification service cannot be reached; your browser is doing a short check instead") and sends the same form again by itself with the solution (captcha_local). The visitor waits a few seconds and the form goes through.

  • The 409 raises an outage flag for 120 seconds. A solution is accepted only while it is up: once the provider answers again, a solution is refused with 422 fallback_inactive and the widget comes back - so a bot cannot skip the widget with the cheap proof of work while the provider is fine.
  • A solution is accepted once.
  • The script not loading in the browser is told apart on the server: the page asks POST /api/captcha/local/challenge, and filex hands a challenge out only when it cannot reach the provider either (or the keys cannot work); otherwise it answers 409 provider and the page asks to allow the widget.

The local proof of work ​

The browser finds a number: the challenge gives a salt, a SHA-256 hash and a signature, and the browser tries 0, 1, 2… until sha256(salt + number) is the hash (at most maxnumber, 200000 by default - one to three seconds on a desktop, under eight on a phone). The server keeps no state for a challenge: its HMAC signature over the hash says the server issued it, the salt carries its end (10 minutes), and the solution's signature is spent once.

The format is a contract shared with the other products that run this bot check (ALTCHA-like): base64 of {"algorithm":"SHA-256","salt":"<32 hex>?expires=<unix>","number":N,"hash":"…","signature":"…"}, checked in a fixed order (bad_payload, bad_algorithm, bad_salt, expired, bad_number, bad_signature, bad_hash, replayed). Its twenty test vectors are in the repository (backend/internal/captcha/testdata/captcha-local-vectors.json, pinned by hash); the server and the browser's solver are both tested against them.

File requests: the upload pass ​

A file request's upload is one multipart request carrying every file. A refusal sent while the browser is still sending the body cannot be read by it - the connection closes under the upload - so the check runs first, on a small request, and its yes is a pass:

  1. POST /api/public/d/<token>/captcha with {captcha_token} (or {captcha_local} during an outage) → {pass, expires_at}.
  2. POST /api/public/d/<token>/upload with the header X-Captcha-Pass: <pass>.

The pass is signed, names this one link, lives ten minutes and is spent by the upload. Without one the upload is refused (422 missing_pass / bad_pass) before a byte of its body is read.

Alarms and metrics ​

The administrators are told on the operator notifications (the bell, and the e-mail, push and webhook channels set up in NOTIFICATIONS.md), in each reader's language:

EventWhen
captcha_fallbackMore than one form in ten minutes was checked with the local proof of work. Once per ten minutes; the last reason in it (no answer in time, no connection, a server error…).
captcha_misconfiguredThe keys cannot work (above). Once an hour per reason.

/metrics counts the local challenges handed out: filex_captcha_fallback_total{cause="unreachable"|"misconfigured"} (METRICS.md).

Several instances, tenants and the page's security headers ​

  • Several instances behind one address share the outage flag and the once-only marks through the database (table captcha_marks): the instance that answered 409 and the one that receives the solution are not always the same. Set the same FILEX_SECRET_KEY on all of them - the challenges are signed with a key derived from it, and without it each instance signs with a key of its own and refuses the others' challenges.
  • Tenants. The bot check is one setting for the whole installation, the platform operator's (MULTI-TENANCY.md). A tenant's own address and a realm typed on the sign-in form are checked with it: nobody gets around it by naming a tenant.
  • Content-Security-Policy. While the check is on, filex's pages allow the provider's widget frame (frame-src https://challenges.cloudflare.com, or https://www.google.com for reCAPTCHA). A reverse proxy that adds a policy of its own must allow the provider's script and frame too, and blob: for the proof of work's worker.

API ​

Method & pathWhoWhat
GET /api/captcha/configanybody{provider, site_key, script, fallback, forms, misconfigured, fallback_active, local_field, token_field} - what a form draws. No secret.
POST /api/captcha/local/challengeanybody200 {captcha: "fallback", challenge} when the server cannot reach the provider either; 409 {captcha: "provider"} when it can; 404 when off.
POST /api/public/d/{token}/captchaanybodyA file request's upload pass.
GET /api/admin/captchaplatform operatorThe settings: what the panel holds (stored), what is in force (effective) and where each field came from (sources: db, env, default); misconfigured, fallback_active, fallback_total. has_secret, never the secret.
PATCH /api/admin/captchaplatform operator{provider?, site_key?, secret?, clear_secret?, forms?, clear_forms?, fallback?, verify_timeout_ms?}; an empty string clears a field (the environment applies again). 400 captcha_bad_value / captcha_out_of_bounds, 409 captcha_no_secret_key. The audit row names the fields, never a value.
POST /api/admin/captcha/testplatform operator{provider?, site_key?, secret?} (the page's values, saved or not) → {ok, reachable, secret_ok, codes, misconfigured, cause, message}.

The protected requests carry the fields in their JSON body: POST /api/auth/login (login / demo_login), POST /api/public/s/{token}/pin and POST /api/public/d/{token}/pin (share_password). The refusals are filex's error envelope (API-ERRORS.md) with the bot check's own field:

json
{"error": "captcha_required", "message": "Please confirm that you are not a robot, then try again.", "captcha": "missing_token"}
{"error": "captcha_fallback", "message": "…", "captcha": "fallback", "challenge": {"algorithm": "SHA-256", "salt": "…", "hash": "…", "signature": "…", "maxnumber": 200000}}

Testing ​

Cloudflare publishes test keys that work on any host, localhost included: site key 1x00000000000000000000AA passes and 2x00000000000000000000AB blocks; secret 1x0000000000000000000000000000000AA passes and 2x0000000000000000000000000000000AA fails. The passing test key hands out the same dummy token every time, so on one installation a second success within five minutes is refused as replayed - a real key never does that. To see the fallback, point the server's call at an address that does not answer: CAPTCHA_TURNSTILE_SITEVERIFY=http://127.0.0.1:1/ (and CAPTCHA_RECAPTCHA_SITEVERIFY) - for tests only, never in production.

Released under the MIT License.