handlers

Overview ¶

Package handlers — account_rules.go

What an account's e-mail and username may be, and how a refusal is said. Used by the self-service profile (auth_self.go) and by an administrator adding a user (users.go), so the two forms refuse the same things in the same words.

⚠⚠ Why this file exists (release-candidate sweep, 2026-09-21):

• the profile form saved "bu-bir-eposta-degil" as an e-mail address and answered "Profil kaydedildi"; logging in with an e-mail then failed with 401, because the account no longer had one;
• changing to another account's address answered 200 with the success message and changed nothing: UpdateUserEmail's unique-constraint error was thrown away (`_ = h.Store.UpdateUserEmail(...)`);
• a username with "ş" in it came back as raw English — `invalid username: 'ş' is not allowed (use a-z, 0-9, dot, dash, underscore)` — in the Turkish panel.

A refusal is `{"error": <code>, "message": <sentence in the reader's language>, "field": "email"|"username"}`: the code for code, the sentence for the person (extractError prefers `message`), the field so a form can put the sentence under the box it is about.

Package handlers - ai_doors.go

The explorer's operations behind the AI surface (task #114): copy, an app's action (file_convert), the operations queue, the trash, version history, 7z/TAR archives, one's own links and file requests - each an MCP tool and a REST route under /api/ai, both answering what the explorer's own route answers.

⚠⚠ They are not written again here. Each one runs the handler the explorer calls (Ops, AppPlugins, Trash, Versions, Archive, SharesMine, Share), in process, behind the same root confinement middleware - so the permission checks, the tenant boundary, the app rules (min_role, admin_only, applies, hidden actions) and the answers are the explorer's by construction, and a fix to one door is a fix to all three. What this file adds is only what the AI surface owes on top, before the handler runs:

• paths in the AI surface's own form (aiOps.resolveStorage): a bare path of a `root:` token resolves under its root, the bound user needs at least viewer, filex's own folders do not exist;
• end-to-end encryption with the AI surface's codes (ai_e2e.go): E2E_BOUNDARY, E2E_PLAINTEXT_REFUSED, E2E_ENCRYPTED - the explorer's route refuses some of these too, but without the code an agent matches on;
• no key: every write the handler judges through gate() - and every member an archive extraction lands - is judged as the AI surface's own (syspath.Keyless), so an encrypted folder's key file is never written, copied over or restored from here (keylessDoor).

The audit row of a write is its REST route's (auth.ActionForPath), written by the /api/ai group's AuditMiddleware for REST and by mcpAuditRow for the MCP tool, with the facts the handler adds (SetAuditTarget, AddAuditDetail) in both - the door passes the recorder through, it never opens a second one.

Package handlers - ai_doors_people.go

What an agent does around a file besides its bytes (task #119, item 4): the bell (notifications_list, notification_read), a star (file_star), comments (file_comments, file_comment_add, file_comment_delete) and who may open an item (file_permissions, file_permission_users, file_permission_set, file_permission_revoke) - each an MCP tool and a REST route under /api/ai.

Like ai_doors.go these run the explorer's own handlers in process: the bell's (/api/notifications, root-confined), the star's, the comments' (with the comments.write permission its route asks) and the item permissions' (owner level and share.users, RBAC.md) - nothing is decided a second time here.

Package handlers - ai_e2e.go

End-to-end encryption on the AI surface: GET/POST /api/ai/* and the MCP file tools, and everything that writes through the same core (ShareX, the upload ticket).

The surface holds no key and never will, so it cannot decrypt a file or encrypt one. Before this file it did not know that either: file_read handed an agent an encrypted PDF as `mime: application/pdf, encoding: base64` (the agent took it for a broken PDF), file_list showed the folder's key file, and file_write put plaintext into an encrypted folder without a word (measured on v0.48.1, task #113). What it does now, each from one place:

• every row says `encrypted` and `e2e_root` (e2eRoots.mark, the rules the explorer's rows use);
• a read of ciphertext is refused with E2E_ENCRYPTED (encryptedRefusal);
• a write into an encrypted folder is refused with E2E_PLAINTEXT_REFUSED unless the caller says `allow_plaintext` (plaintextRefusal);
• a copy across the boundary is refused with E2E_BOUNDARY (e2e.GuardTransfer, the rule every transfer surface asks);
• the key file is left out of listings (syspath.Unlisted) and never written, moved or deleted from here (syspath.Keyless, through aiOps.gate);
• a public link into an encrypted folder is refused (publicLinkRefusal).

Recognising any of it is a catalogue lookup for the marker's row and a name test for `.fxe`: no content is read and no key is asked for.

Package handlers — ai_tags.go

Tags for agents: GET/POST /api/ai/tags and the MCP `file_tags` tool.

Until v0.43.0 an agent could FILTER by tag (`tag:` in file_search) but could neither read a file's tags nor set them — and there was one kind. With two kinds the agent has to be able to say which one it means, so this surface speaks the same {name, kind} items as the explorer's routes and runs the very same rules (tagOps, tags.go): personal = only the token's user sees it; team = the tenant, and needs edit permission on the file.

⚠ It never has a default kind. The explorer's legacy `tags: [names]` shape defaults new names to personal for old clients; an agent is new code, so it must name the kind of every tag it writes — an agent quietly publishing a label to the whole tenant, or hiding one the user meant to share, is exactly the kind of silent audience change the finding was about.

Package handlers — app_plugins.go

User surface for app plugins (internal/wasmplugin):

GET  /api/files/plugins/actions                          — what applies to this caller
POST /api/files/plugins/actions/{plugin}/{action}/run    — {storage_id, paths[], params} → 202 op | 200 surface
GET  /api/files/plugins/views/{plugin}/{view}            — ?storage_id=&path= → surface (event "open")
POST /api/files/plugins/views/{plugin}/{view}/event      — {storage_id, path, state, event, action_id, data} → surface | 202 op

Every run is authorised HERE, at submit: tenant ownership of the storage, ACL on every path (viewer to read, editor when the action writes), read-only storages refused for writing actions, encrypted folders refused (the server has no key), and the action's applies rule re-checked against the real files — the menu's client-side filter is a convenience, not a gate. The ops worker that later runs the job has no user of its own.

Package handlers — app_plugins_admin.go

Admin surface for app plugins (internal/wasmplugin, docs/APP-PLUGINS.md):

GET    /api/admin/app-plugins                — runtime facts + every plugin
POST   /api/admin/app-plugins[?dry_run=1]    — install: multipart {wasm?, ui?, manifest, signature?, grant} | JSON {github_repo, ref?, permissions} | JSON {url?, manifest_url, sha256?, permissions}
                                             (no module — `wasm`/`url` — for a language pack; wire.Manifest.IsLanguagePack)
GET    /api/admin/app-plugins/{id}
PATCH  /api/admin/app-plugins/{id}           — {"enabled": bool}
POST   /api/admin/app-plugins/{id}/rollback  — back to the version the last upgrade replaced
POST   /api/admin/app-plugins/{id}/upgrade   — same bodies as install
POST   /api/admin/app-plugins/updates/check  — check every app's source now (updates.go)
DELETE /api/admin/app-plugins/{id}
GET/PUT /api/admin/app-plugins/{id}/settings
GET/PUT /api/admin/app-plugins/{id}/overrides
GET    /api/admin/app-plugins/{id}/logs?after=N
GET/PUT /api/admin/app-plugins/{id}/thumbnails - the app's thumbnail limits (internal/wasmplugin/thumbnails.go)

⚠ Instance-wide, never tenant-scoped, for the same reason storage plugins are: a plugin's actions appear in every tenant's file menu. Only the supertenant may touch this surface.

⚠⚠ Installing, upgrading, going back, switching, removing and the action overrides need an administrator SIGNED IN to the panel (requireSession): an API key gets 403 and is pointed at /api/admin/plugin-requests. The review (?dry_run=1), the list, a detail, the logs and the update check stay open to an admin-scoped key.

Package handlers - app_store_intent.go

Installing an app from a store, and the licenses of paid apps (internal/appstore, docs/APP-PLUGINS.md → Installing from a store, Paid apps; docs/APP-PLUGINS-API.md → The store contract):

GET    /api/admin/app-plugins/stores                 - the trusted stores
POST   /api/admin/app-plugins/stores                 - {store, fingerprints}: trust a store with the keys shown
DELETE /api/admin/app-plugins/stores?store=<origin>  - stop trusting it
POST   /api/admin/app-plugins/store-intent           - {store, token}: read an install link → its review
POST   /api/admin/app-plugins/store-intent/install   - {handle, permissions, associations?, license_key?}
POST   /api/admin/app-plugins/store-intent/cancel    - {handle}
GET    /api/admin/app-plugins/licenses               - every paid app's license (the panel's warning band)
GET    /api/admin/app-plugins/{id}/license
PUT    /api/admin/app-plugins/{id}/license           - {key}: a new key, checked at once
POST   /api/admin/app-plugins/{id}/license/verify    - check now
GET    /api/files/plugins/license/{plugin}           - what the app reads about itself (fx.license.get())

Who may (the reasoning of app_plugins_admin.go and plugin_session_gate.go) ¶

Every admin route here is the PLATFORM OPERATOR's (requireSupertenant: an app runs for every tenant, so a tenant administrator gets 403) and needs an administrator SIGNED IN to the panel (requireSession): an API key of any scope - an admin key, a `root:`-confined key, an app token - is refused 403 session_required, on the reads too. Installing is already a person's decision; trusting a store decides whose install links are shown to that person at all, and a license key is not for a program to read back.

⚠ GET changes nothing here. Trusting a store is its own POST, naming the fingerprints the administrator was shown; the session cookie is SameSite Lax and every state-changing request passes the origin guard (internal/originguard), so a link or a page elsewhere cannot trust a store for anybody.

Package handlers - app_store_view.go

The embedded store screen (#162, docs/APP-PLUGINS.md → The store screen): filex draws a trusted store's catalog with its own components, read on the SERVER from the store's signed index (the browser never talks to the store; the Content-Security-Policy does not change), and a person who sees it leaves a request on the same Install requests list an API key uses.

The administrator's routes, inside /api/admin/app-plugins (the platform operator, signed in to the panel - AppStore.gate, as every store route):

GET    /store-view[?tenant=<id>]             - who sees the screen in a scope
PUT    /store-view                           - {tenant?, settings}
GET    /stores/connection?store=<origin>     - is this filex connected to the store
POST   /stores/connection                    - {store, code}: connect with the store's one-time code
DELETE /stores/connection?store=<origin>     - disconnect

A person's routes, /api/app-store (signed in to filex in a browser, or the desktop app's own pairing; any other API key is refused - this is a person's screen, its requests a person's words; personCaller):

GET  /api/app-store                          - {visible, stores}
GET  /api/app-store/catalog?store=<origin>   - the catalog, as filex verified it
GET  /api/app-store/media?store=&file=       - an icon of that catalog
GET  /api/app-store/requests                 - the requests this person left
POST /api/app-store/requests                 - {store, app, reason}: leave one

⚠ Nothing here installs, trusts or asks a store for an install link: those stay the administrator's (app_store_intent.go, plugin_requests.go).

Package handlers — app_ui.go

The server half of an app's OWN interface (docs/APP-PLUGINS-API.md → An app's own interface). The interface runs in a sandboxed frame with no network; what it asks for goes through filex's frame (AppFrame, the explorer), which calls these with the PERSON's session:

PUT  /api/files/plugins/ui/{plugin}/{view}/save?path=<qualified>        — a new version of an opened file
PUT  /api/files/plugins/ui/{plugin}/{view}/save?dir=<qualified>&name=   — a NEW file there ("save as")
POST /api/files/plugins/ui/{plugin}/{view}/call                        — the app's module (`ui_call`)

⚠⚠ Every check is made again HERE, whatever the frame already decided: the app is running, the view is its interface, the app was granted what the call needs (files:write for a save), the file is one the view applies to, and the person may write it (confinement, ACL editor, the write gate — locks, filex's own folders, a draft only its owner's). The frame is the person's own page, but a check that lives only in a page is a check a crafted request skips.

Package handlers — app_ui_call.go

POST /api/files/plugins/ui/{plugin}/{view}/call — an app's own interface asking its module (`ui_call`, docs/APP-PLUGINS-API.md → An app's own interface). The save half is app_ui.go.

Package handlers — app_ui_chunks.go

An app's interface saving a LARGE file: the explorer streams what the interface hands it (a ReadableStream, transferred into the explorer's page) in chunks of at most 8 MiB, each one request — a reverse proxy with a body limit (nginx's default is 1 MiB) lets every one of them through — into a spool file, and the file is written to the storage ONCE, when the last chunk arrives, through the same checks and the same commit as a one-shot save (app_ui.go):

PUT …/save?path=<q>&chunk=start            (body: first chunk)  → {session, received}
PUT …/save?session=<id>&offset=<n>          (body: next chunk)   → {session, received}
PUT …/save?session=<id>&offset=<n>&final=1  (body: last chunk)   → the save's answer

A session belongs to the person, the app, the view and the target it was started for; another caller naming it gets 404. An abandoned one is removed after uiChunkTTL.

Package handlers — audit.go ¶

GET /api/admin/audit?user_id=&action=&from=&to=&limit=50&offset=0

Package handlers — audit_targets.go

WHICH thing an audit row is about, in words a person reads.

⚠⚠ The Panel's Recent activity and the Audit page printed the KIND of thing and nothing else — "Kullanıcı: oluşturuldu — Kullanıcı", "Depo: senkron başlatıldı — Depo #1" (release-candidate sweep, 2026-09-21). A row stores a target TYPE and an id; the id of a user, a storage or a share is a number nobody can read, and a create has no id at all (its URL has none and the middleware never reads bodies).

Two halves, one answer (`target_name` on the wire):

• write time: the handler names what it made or removed (auth.SetAuditTarget → metadata.target_name). This is the only answer for something that no longer exists — "which user was deleted?";
• read time: an id that still resolves is named from the live row, so the rows written before this change read properly too.

⚠ Resolved through the SCOPED store the handler already holds: a tenant admin's list is filtered to its own users' rows (audit.go), and a name is only ever looked up for a row that survived that filter.

Package handlers — auth_providers.go

Admin → Identity providers: the sign-in providers this instance runs.

GET    /api/admin/auth-providers
POST   /api/admin/auth-providers                  (another instance of a driver)
PATCH  /api/admin/auth-providers/{name}
DELETE /api/admin/auth-providers/{name}           (an instance made with POST)
PUT    /api/admin/auth-providers/{name}/tenants   (which tenants sign in through it)
POST   /api/admin/auth-providers/{name}/test

{name} is the provider's slug: the driver's name for its first instance (`ldap`, `oidc`, ...), so every client that addressed "the LDAP" still does (docs/TENANT-ADMIN.md).

⚠⚠ Until v0.43.0 this page wrote `auth.<name>.*` settings that NOTHING read — sign-in was built from the environment only, once, at boot — and answered "configuration saved; restart the server" to a restart that changed nothing (release-candidate sweep, 2026-09-21). The owner's decision: the page really manages sign-in, and it can never lock the instance out. The rules live in internal/authsetup; this file enforces them at the door:

• a provider the environment defines is read-only here, and says where it comes from (409 environment_managed on a change);
• password sign-in and the recovery sign-in are the environment's — the page has no switch for either (409 not_managed_here);
• a save runs the real test first; switching a provider ON while its test fails needs `confirm_failed_test` (409 test_failed names the steps) - except an operating-system provider (windows), whose only proof is a real sign-in: its test must PASS, with `test_account` {username, password} sent on that request (used once, never stored or logged), and the account that passed becomes the super administrator (409 test_failed, no way round);
• switching off the last way an administrator can sign in is refused (409 last_sign_in_method); on a multi-tenant install a tenant's last way in is refused too unless the operator confirms it (`confirm_tenant_lockout`): the operator can always bind something back;
• a secret is sealed (FILEX_SECRET_KEY) and never sent back;
• a change is applied at once (authsetup.Live.Reload) and audited with the provider, the switch and the NAMES of the fields that changed.

Instance-wide: only the platform operator (supertenant admin) sees or changes any of it. A tenant administrator gets 403 — the sign-in of the whole instance, and its secrets, are not a tenant's to read; a tenant's own sign-in lives on its provider row (/api/admin/providers).

Package handlers — auth_self.go

Self-service auth endpoints (current user). All routes require an authenticated session and act on the principal in the request context.

GET    /api/auth/me              — current user
PATCH  /api/auth/profile         — update email/username/locale/timezone
POST   /api/auth/password        — change password (requires old)
POST   /api/auth/totp/enroll     — start TOTP enrollment
POST   /api/auth/totp/verify     — confirm TOTP enrollment with code
POST   /api/auth/totp/disable    — turn TOTP off (password + code)

Package handlers — comments.go (calisma:d3, v0.6 "Çalışma" (Work))

Node comment endpoints under /api/files:

GET    /api/files/comments?node_id=…   (auth) chronological live list
POST   /api/files/comments             (auth) {node_id, body} add
DELETE /api/files/comments/{id}        (auth) author-or-admin soft delete

ACL: anyone who can SEE the node (≥viewer, same aclAllowID gate the other file handlers use) may read and write its thread; delete is author-or-admin regardless of node level (enforced in internal/comments). Trashed/missing nodes 404 on both read and write.

An API token is held to its `comments` permission besides (task #157): reading asks auth.CommentsRead, adding and deleting auth.CommentsWrite - `comments:rw` in the token's list; the verb `write` does not stand in for it. The question is asked HERE, first thing, because this handler is every door's: the explorer's route, and /api/ai and the MCP tools, which run it in process (ai_doors_people.go). A browser session is judged by the account.

Package handlers — confine_guard.go

The token `root:` confinement, for the surfaces confine.Middleware cannot reach.

confine.Middleware (mounted on /api/files) rewrites the `?path=` query and the path fields of a JSON body, so every path-addressed read and every mutation is confined by construction. It cannot touch two shapes:

• an id-addressed request (`?id=`, `node_id`, a raw `?storage=`), because a numeric id is not a path there is nothing to rewrite; and
• a listing or search that walks a whole storage, because the rows come back AFTER the request the middleware saw.

Those are exactly the shapes handlers/thumb.go, handlers/versions.go, handlers/trash.go, handlers/shared.go and handlers/quota_storages.go already gate with confine.Root.Within. This file is the ONE place the rest of the package answers the same question, so a sixth copy of "resolve the storage, then Within" cannot drift from the other five. It is the confinement twin of the tenant guards in tenantown.go.

Package handlers — dashboard.go ¶

GET /api/admin/dashboard returns aggregated stats for the admin landing page: per-storage summary, user/share/session counts, queue depth, recent activity and a short capability summary.

Package handlers — demo_redact.go

What a public demo shows in the read-only admin pages it deliberately keeps visible. The demo guard (api/demo_guard.go) stops a visitor CHANGING the instance; this file stops the pages a visitor may still READ from handing out other people's data and the operator's secrets.

Package handlers — duplicates.go ¶

GET /api/admin/duplicates?limit=100&min_size=1 — admin-only report of files sharing (size, etag), i.e. byte-identical copies as far as the storage backend can tell (frozen v0.2 "Bul" contract #2).

Grouping runs in SQL (db.Store.ListDuplicateNodes: GROUP BY size, etag HAVING COUNT(*)>1 on live file nodes with a non-empty etag); the handler folds the flat rows into groups, computes total_waste = (count-1)*size and sorts groups by total_waste descending.

Package handlers — e2e_policy_admin.go

Who may encrypt (internal/e2epolicy), the administrator's half:

GET   /api/admin/e2e               — the policy the caller administers
PATCH /api/admin/e2e               — SESSION ONLY: {"policy": "off|admins|permitted|approval"}
GET   /api/admin/e2e/tenants       — SUPERTENANT: every tenant's ceiling and policy
PATCH /api/admin/e2e/tenants/{id}  — SUPERTENANT, SESSION ONLY: {"e2e_allowed": bool}
GET   /api/admin/e2e/requests[?status=pending|approved|rejected|expired|used|all]
POST  /api/admin/e2e/requests/{id}/approve — SESSION ONLY: {"note"?: "…"}
POST  /api/admin/e2e/requests/{id}/reject  — SESSION ONLY: {"reason"?: "…"}

A tenant administrator lists and decides their own tenant's requests only; another tenant's id answers 404, like an id nobody has (tenantown.go). The platform operator (the supertenant's administrator on a multi-tenant install) lists every tenant's requests and decides only the platform's own: another tenant's answers 403 not_decidable, and its row says `decidable: false` (operator decision 2026-10-03).

Whose policy "the caller administers" is decided by the tenant scope auth.TenantResolver attached, never by the request: a tenant administrator holds their own tenant's row, the supertenant's administrator the supertenant's own row — another tenant's policy is that tenant's decision; the operator's lever is the ceiling — and a single-tenant install's administrator the instance setting `e2e.policy`.

⚠ A change is a person's (sessionOnly): an admin-scoped API key may read the policy, not change it. The policy decides who may make data readable only by its key holders, and the ceiling is the operator's.

⚠ requireSupertenant and sessionOnly are called in the handler, never as a route middleware — the reasoning of supertenant.go.

The audit rows are written here through e2epolicy.Audit, not by the audit middleware (auth.ActionForPath skips /api/admin/e2e): one change is one row that names the tenant and says what the value was and what it became.

Package handlers — e2e_policy_files.go

Who may encrypt (internal/e2epolicy), the explorer's half:

POST /api/files/e2e/allowed   - may I encrypt here? {"items":[{"path":"Depo://a","kind"?:"folder"|"new_folder"|"file"}]} → {"encrypt":["allowed"|"request"|"denied",…]}
POST /api/files/e2e/requests  - leave a request: {"path":"Depo://a/b","kind":"folder"|"new_folder"|"file","reason":"…"}
GET  /api/files/e2e/requests  — the caller's own requests

A request is what the approval policy asks of somebody who holds files.encrypt: an administrator of their tenant approves it on Admin → Encryption (handlers/e2e_policy_admin.go), and the approval opens one encryption of its kind there, once, for seven days.

The service writes the audit rows; /api/files/e2e/requests is not one of the file paths the audit middleware records (auth.shouldAudit), so one event is one row.

Package handlers — external_admin.go

Admin CRUD for external services (OnlyOffice, Drawio, Mermaid, …).

GET    /api/admin/external
PATCH  /api/admin/external/{name}
POST   /api/admin/external/{name}/test

Package handlers - file_types_admin.go

Admin → Plugins → Default apps (internal/assoc, docs/APP-PLUGINS.md → Default apps):

GET    /api/admin/file-types           - every kind something besides filex handles, and every kind with a rule
PUT    /api/admin/file-types/{ext}     - {open?: {order, off} | null, thumbnail?: {order, off} | null}; null = back to the default
DELETE /api/admin/file-types/{ext}     - both capabilities back to the default

⚠ Instance-wide, like the apps whose handlers it orders: a tenant administrator gets 403 supertenant_only. A change needs an administrator signed in to the panel (an API key reads, and gets 403 session_required): switching a thumbnail handler back on hands an app the bytes of every file of that kind, which is the same kind of decision as an action override (PutOverrides). Refused on the demo instance. Each change writes its audit row (file_association.update / .reset) with what it was and what it is.

Package handlers — login_security.go

The administrator's side of the sign-in attempt limit (internal/loginguard): its settings, the locks in force, and the recent wrong attempts. Frozen contract for the admin SPA and for /api/ai/admin (and its MCP tools):

GET   /api/admin/login-security
      → {settings, limits, trusted_proxies_effective, trusted_proxies_source,
         trusted_defaults:{auto, loopback, private, link_local},
         trusted_addresses, trusted_proxies_auto:{in_use, environment,
         runtime, networks, excluded_gateways, excluded_self, interfaces,
         warning, warning_detail, resolved_at}, untrusted_forwarders:
         [{address, first_seen, last_seen, count, public, relay}],
         untrusted_forwarders_total, your_ip, your_ip_allowlisted}
PATCH /api/admin/login-security   partial body, same keys as `settings`
      → the GET answer (400 {error:"invalid_setting", field, message} on a
        bad value; nothing is written unless every field is valid)
GET   /api/admin/login-security/locks?scope=&locked=1&limit=
      → {items:[{id, scope, subject, fails, limit, lock_level, locked,
         locked_until, retry_after, window_start, last_fail_at, last_ip,
         last_protocol}], now}
POST  /api/admin/login-security/unlock   {scope, subject} | {all:true}
      → {ok, unlocked}
GET   /api/admin/login-security/attempts?action=&from=&to=&limit=&offset=
      → {items:[{id, action, identifier, ip, protocol, reason, scope, via,
         changed_fields, at, metadata}], total}

On a public demo (DemoMode) every address a visitor or the operator wrote is "hidden on the demo" in all of these answers (demo_redact.go); your_ip, the reader's own, is not.

Instance-wide ¶

Every value here is one global row, and a lock or an address is not a tenant's own: the whole surface is the platform operator's (requireSupertenant, asked INSIDE each method because /api/ai/admin and the MCP tools mount these same handler instances).

Memory first ¶

With a running limiter (Guard) every answer here is the limiter's memory — the settings and the counters it decides with — and every change goes through it: a setting is written to the table and put in force at once, an unlock lifts the lock in memory and deletes the row. Without one (a store with no limiter) the table is read and written directly.

What is never here ¶

No password, ever: the counters hold an identifier and an address, the audit rows hold the same plus the door and the reason.

Package handlers contains one file per logical HTTP route group.

Package handlers — meta.go ¶

Starred / Recently-opened endpoints, and the row shape the tag listings share with them. All require an authenticated user; starred and recent are PER-USER (stored on user_node_meta). Tags — personal and team since v0.43.0 — have their own file, tags.go.

POST /api/files/manager/star        body {node_id, starred: bool}
GET  /api/files/manager/star/list?storage_id=…&limit=
POST /api/files/manager/recent      body {node_id}
GET  /api/files/manager/recent?limit=

Package handlers — nfsexports.go

GET    /api/auth/nfs-exports            — list the caller's own exports
POST   /api/auth/nfs-exports            — mint one (the PATH is shown ONCE)
POST   /api/auth/nfs-exports/{id}/state — enable / disable
DELETE /api/auth/nfs-exports/{id}       — revoke permanently

⚠⚠ The path returned by POST is the whole credential. Anyone who can reach the NFS port and knows it can mount the export as this account — NFSv3 has no other way to bind an identity that does not require Kerberos. It is shown once, stored hashed, and the UI says all of this plainly rather than letting somebody discover it from a mount table.

Package handlers — notification_digest.go

The notification digest's HTTP half (internal/notify digest.go):

GET   /api/notifications/settings       — the person's own urgent choices beside their mutes (notifications.go)
PATCH /api/notifications/settings       — {urgent_overrides: {"<event>": bool}}; absent keeps them
GET   /api/admin/notifications/digest   — the defaults the caller administers
PATCH /api/admin/notifications/digest   — {window_minutes: 1-15, urgent_events: [...] | null}

and the View the digest's background pass judges a person's rows through (DigestViewer): the bell this handler gives them, built without a request.

Whose defaults an administrator holds is decided by the tenant scope auth.TenantResolver attached, never by the request — the rule of Admin → Encryption (e2e_policy_admin.go): a tenant's administrator holds their own tenant's, the supertenant's administrator the supertenant's, a single-tenant install's administrator the instance's (scope 0).

Package handlers - openwith.go ¶

Endpoints (0.50, docs/APP-PLUGINS.md → Default apps):

GET    /api/me/open-with         (auth) → {"choices": {ext: handler}}
PUT    /api/me/open-with/{ext}   (auth) ← {"handler": "builtin" | "onlyoffice" | "app:<app>/<view>"} → {"choices": …}
DELETE /api/me/open-with/{ext}   (auth) → {"choices": …}
DELETE /api/me/open-with         (auth) → {"choices": {}}

"Always open this kind with this app" - ONE record per ACCOUNT (the maintainer, 2026-10-01): the browser, the desktop app and every embed read and write the same choices. A person who picked an app for .board files in the browser gets it in the desktop app too; where that app cannot open the file (it is not offered there, or the administrator switched it off for the kind) the next handler that is on opens it, and the choice is kept for where it can.

⚠⚠ NOT a key of the per-surface document. That document is PUT whole, so a shared key in it would be overwritten by whichever surface wrote last with whatever it read at boot - a choice made on the desktop undone by a palette change in a browser tab opened before it. So the choices are their own row (user_prefs, surface "account", `{"openWith": {…}}`), changed one kind at a time, and the surface document only CARRIES them on the way out: GET /api/me/prefs puts them in as `openWith` (the JSON string the client has always read), PUT /api/me/prefs drops the key (userprefs.go).

⚠ Adoption, once: an account whose row has never held a choice takes the `openWith` of its most recently written surface document (web or desktop), the one that was in use last. Choices are not merged across documents: which device's choice for a kind is "right" is not knowable, and the last one written is the one the person saw last.

Package handlers - panel_search.go

The admin panel's search (task #168, docs/ADMIN-PANEL.md → Search): the people, groups, API keys, apps, storages and shares that match a query, in one answer, and the person's recent searches.

⚠⚠ Nothing is listed again here. Each kind is read by running, in process, the very handler the panel's own page calls (the Users page's GET /api/admin/users, the API / MCP page's GET /api/admin/ai-tokens, …) behind the very gate its route has (handlers.RequireAdminPermission for the delegated pages, auth.RequireAdmin for the rest) - routes.go registers each source next to the route it reads, with the same gate value. So who may find what is, by construction, who may open what: a delegated administrator holding admin.users finds people and groups and nothing else, a tenant's administrator finds their own tenant's (the handlers' tenant filters and the tenant-scoped store), and a kind whose list refuses the reader is left out of the answer - never an error. The pattern is the AI surface's doors (ai_doors.go).

What this file adds is only the matching, and the shape of a row: an id, a label, a detail line, the other words a row answers to. A row never carries what the list it came from must not hand on - an API key's value is not in that list to begin with (only its hash is stored), a share's link token and address are dropped here, and nothing else is copied but the named fields.

Pages, settings and files are not here: the panel finds its own pages and settings from its menu (web/src/lib/adminSearch.ts), and files through the explorer's own search (GET /api/files/search).

Package handlers — plugin_requests.go

Plugin install requests (internal/pluginreq, docs/APP-PLUGINS.md → Install requests, docs/PLUGINS.md → Install requests):

POST /api/admin/plugin-requests                — leave a request (API key or session)
GET  /api/admin/plugin-requests[?status=…]     — list (pending by default; `all` for every state)
GET  /api/admin/plugin-requests/{id}           — one request, with its frozen manifest and review
POST /api/admin/plugin-requests/{id}/approve   - SESSION ONLY: install what the request froze; {"associations"?: [...]}
                                                 (a request from the store screen: {"license_key"?} - asks the
                                                 store for a fresh install link; the install is the store review's)
POST /api/admin/plugin-requests/{id}/reject    — SESSION ONLY: {"reason"?: "…"}

⚠⚠ Why this exists (owner, 2026-09-28): an API key may no longer install, upgrade, remove or re-permission a plugin (requireSession). It may leave a request; an administrator signed in to the panel decides. Approve and reject are therefore session-only here AND there is no MCP tool for either (ai_admin.go): a key that could approve its own request would be the old hole with an extra step.

⚠ Instance-wide like the plugins themselves: in multi-tenant mode only the supertenant may leave, read or decide a request (requireSupertenant). A tenant administrator gets 403.

The service writes the audit rows itself (created, approved, rejected, expired, superseded), so these routes are skipped by the audit middleware (auth.ActionForPath) and one event is one row, whichever door it came in by.

Package handlers — plugins.go ¶

Admin surface for storage plugins (internal/plugin, docs/PLUGINS.md):

GET    /api/admin/plugins              — every plugin with its live state
POST   /api/admin/plugins              — install: multipart {name, file[, source]} | JSON {name,url,sha256[,source]} | JSON {name,source} | JSON {name,kind:"remote",address,token}
GET    /api/admin/plugins/{id}
PATCH  /api/admin/plugins/{id}         — {"enabled"?: bool, "source"?: string}
POST   /api/admin/plugins/{id}/restart
POST   /api/admin/plugins/{id}/upgrade — multipart {file} | JSON {"from_source": true}
POST   /api/admin/plugins/updates/check — read every source now; installs nothing

⚠⚠ Nothing updates itself (plugin/updates.go): a binary plugin that names a source is checked daily and its row says when a newer version is there; the administrator's {"from_source": true} upgrade installs it.

DELETE /api/admin/plugins/{id}

⚠⚠ Install, upgrade, PATCH and DELETE need an administrator SIGNED IN to the panel (requireSession): an API key gets 403 and is pointed at /api/admin/plugin-requests, where it may leave a request instead. Reading (the list, one plugin, the update check) stays open to an admin-scoped key.

⚠ Instance-wide, never tenant-scoped: a plugin is a PROCESS filex runs (or a service it trusts with storage credentials), so in multi-tenant mode only the supertenant may touch this surface. A tenant admin gets 403, not an empty list, so the boundary is visible.

Package handlers — protection.go ("Koru" v0.4)

Admin protection-settings surface, frozen contract:

GET   /api/admin/protection → {"trash_retention_days":30,"versions_keep_n":0,
                               "share_max_ttl_days":7,"shares_over_max_ttl":0,
                               "drafts_limit":50,"drafts_limit_min":1,
                               "drafts_limit_max":1000,
                               "antivirus":{ … see protectionAntivirusStatus }}
PATCH /api/admin/protection → {trash_retention_days?, versions_keep_n?,
                               share_max_ttl_days?, drafts_limit?,
                               av_save_scan_window_minutes?,
                               av_max_scan_mb?, av_enabled?, av_mode?,
                               av_clamd_addr?}

The values live in the settings table (`trash.retention_days`, `versions.keep_n`, `share.max_ttl_days`, `drafts.limit`, `antivirus.enabled`, `antivirus.mode`, `antivirus.clamd_addr`, `antivirus.save_scan_window_minutes`, `antivirus.max_scan_mb`). `shares_over_max_ttl` is a read-only count of EXISTING live links that outlive the ceiling — they are reported, never shortened (see share.CountOverMaxTTL).

The antivirus block: STATUS fields and SETTING fields ¶

They are separated on purpose, because they can disagree and the disagreement is the interesting part. A SETTING is what the settings table holds — what an admin last saved. A STATUS field is what this process is actually doing. `scan_enabled` can be true while `enabled` is false (switched on, nothing to reach), and both can be true while `reachable` is false (clamd configured, clamd down).

⚠⚠ `av_enabled`, `av_mode` and `av_clamd_addr` take effect AT THE NEXT RESTART, in both directions, because the scan pipeline is wired once at boot (internal/server registers the queue handler and hands the upload surfaces an enqueue function). The response says so twice: the settings are echoed back immediately, and `restart_pending` is true for as long as the stored configuration differs from what this process booted with. The two live settings — the save-scan window and the size ceiling — are read at the point of use and are never pending.

⚠ The scanner BINARY is still not admin-writable, and for the original reason: it is a path this server EXECUTES, so a writable field for it would turn an admin account into arbitrary command execution. A clamd ADDRESS is a different thing — a dial target, never executed — and is writable, with its shape validated at save time (antivirus.AddrSetting.Check). It does let an admin point scanning at an arbitrary TCP endpoint, which is worth stating plainly, but it is the same authority an admin already has when configuring a storage backend's endpoint.

Package handlers — public_api.go

ONE PUBLIC SURFACE. Everything a stranger reaches through a filex link — a download share, a file request, an app plugin's page — is answered here as JSON, so the SPA can render all three with one shell, one PIN gate, one expiry story and the instance's own branding.

GET  /api/public/branding                  — who this instance says it is
GET  /api/public/ui-locales/{code}         — one language an app adds: its strings
GET  /api/public/s/{token}                 — a share's state
POST /api/public/s/{token}/pin             — answer the PIN → unlock cookie
POST /api/public/s/{token}/event           — an app page's surface event
GET  /api/public/s/{token}/file/{ref}      — a copy an app page exposed
GET  /api/public/d/{token}                 — a file request's state
POST /api/public/d/{token}/pin             — answer the PIN → unlock cookie
POST /api/public/d/{token}/upload          — the drop itself (multipart)

⚠ NOTHING HERE IS AUTHENTICATED, and nothing here leaks. The token is the only capability; a wrong or unknown one is 404 with no other detail, and a dead one is 410 with the same shape for every reason it could be dead. The creator's address, the storage's name and the file's path never appear.

⚠ Every answer is `Cache-Control: no-store` and `X-Robots-Tag: noindex` EXCEPT /branding and /ui-locales, the two things here that are not about a link: who the instance is and the words it speaks. Both are deliberately cacheable (every public page fetches them).

⚠ The PIN gate is internal/share's — five strikes then ten minutes, counted on the share row, answered with an HMAC cookie that carries no PIN. It is the same gate the no-JS pages use, and the same one the app pages used to have to themselves.

Package handlers — public_shell.go

WHICH ANSWER A PUBLIC LINK GIVES.

/s/{token} and /d/{token} have three possible readers and must keep serving all three:

1. a JavaScript browser — gets the SPA shell (the branded public surface: PIN gate, expiry, visit counter, the app page when the link carries one);
2. a browser with no JavaScript, or one the shell could not load in — gets the Go pages that have always been here: the file, a PIN form, an explanation. Reduced to that, and kept, because a share link is opened by strangers on whatever browser they have;
3. something that is not a browser at all — `curl -O`, wget, a download manager, a backup script — gets the BYTES, exactly as before.

The rules below are the whole decision. They are written as a function rather than as a middleware so both handlers make the same call in one place, and so a test can ask the question without a router.

Package handlers — quota.go ¶

Endpoints:

GET   /api/files/quota/me                            (auth)
GET   /api/files/quota/storages                      (auth, quota_storages.go)
GET   /api/admin/users/{id}/quota                    (admin)
POST  /api/admin/users/{id}/quota                    (admin)
PATCH /api/admin/users/{id}/quota                    (admin)
POST  /api/admin/users/{id}/quota/recompute          (admin)

The flat forms — /api/admin/quota/{user_id} and /api/admin/quota/{user_id}/recompute — are the original spelling and are still served. Note both take a USER id: there is no per-provider quota (see docs/MULTI-TENANCY.md, "Not yet").

Package handlers — quota_storages.go

Endpoint:

GET /api/files/quota/storages   (auth)

"How full is this drive", for somebody who is not an administrator.

The admin panel has always had this number: `/api/admin/storages` enriches every row with `stats.total_size_bytes` (handlers/storages.go), which is what the Home page's storage card printed for an operator and for nobody else. The only other figure in reach was `/api/files/quota/me`, and that is a per-USER sum across every storage — printing it under one drive's name would be a number about the person wearing a label about the drive.

So this answers the same quantity the admin row carries, for the storages the caller is allowed to see, and nothing about the ones they are not.

Package handlers — replication_targets.go

/api/admin/replication-targets — CRUD for the new backup-only entity. Replication targets are NOT regular storages: operators never write to them, they don't show up in the Depolar list, and the file explorer never lists them as a virtual root. Each entry is a backup sink that a primary storage can fan its writes out to via `storages.replica_target_id`.

Package handlers — s3keys.go ¶

Self-service management of S3 access keys (migration 00026).

GET    /api/auth/s3-keys            — list the caller's own keys
POST   /api/auth/s3-keys            — mint one (the secret is shown ONCE)
POST   /api/auth/s3-keys/{id}/state — enable / disable without deleting
DELETE /api/auth/s3-keys/{id}       — revoke permanently

Self-service and not admin-only on purpose: the requirement is that every credential the product issues can connect at exactly its own permission, and a key that only an administrator can mint is a key most people never get. The permission ceiling is enforced by protocolauth.Issue, not by who is asking — a key can only ever narrow what its owner already has.

Package handlers — save_text.go

`/api/files/save-text` accepts plain-text writes from the SFC's code editor (Monaco) + markdown viewer "edit" mode. The SFC posts:

POST /api/files/save-text
{ "path": "<adapter>://<rel>", "content": "..." }

We resolve the storage from the adapter prefix, write the content through the storage Driver, then refresh the cache row's metadata (size + mtime + etag where the driver supplies one).

Whitelist: only files matching a text/code MIME class are saveable here. Binary edits go through OnlyOffice's callback channel.

Antivirus ¶

This surface does NOT call writehook.OnFileWritten, and that omission was the gap: the hook enqueues an antivirus scan, so routing every Ctrl+S through it would have queued a ClamAV pass per keystroke-burst — and the answer taken instead was to scan nothing, which made the editor a way to introduce a file that is never scanned on an install where every uploaded file is. The two branches below now split it the way the behaviour actually splits:

create (no node row for the path)  → scan immediately, like an upload
save   (node row already existed)  → schedule one scan, debounced

The debounce lives in the queue (not_before + a coalescing key), not in a timer in this process, so a restart mid-window does not lose the pending scan. See queue.AntivirusScanner.EnqueueAfterSave.

The write event ¶

The scan is the only thing this surface schedules for itself. The EVENT goes through the shared gate like every other write surface -- writehook.EmitWritten, which is OnFileWritten minus the antivirus half it has already taken care of -- so the editor is not a place where webhook subscribers hear something different from the browser upload that wrote the same file. The two branches split the event exactly as they split the scan:

create (no node row for the path)  -> file.uploaded
save   (node row already existed)  -> file.updated

Same `existing` fact, one decision, two consequences. Until this was wired the editor announced NOTHING at all: a file created or rewritten in the browser reached no webhook and no notification bell, so an integration watching a folder simply did not see edits happen.

Package handlers — search_admin.go

Admin endpoints for the embedded Bleve full-text index.

GET  /api/admin/search/stats     — index stats
POST /api/admin/search/rebuild   — drop and rebuild the index from nodes

Package handlers — shared.go ¶

"Shared with me": everything the caller reaches through a per-item grant somebody else gave them, rather than through their own role on a storage.

GET /api/files/manager/shared-with-me?limit=&offset=

The data has always existed in `file_grants`, but nothing could answer this question: Grants.List is path-scoped ("who can see THIS folder") and owner-only, so a user had no way to find out what had been shared with them unless they were told the path. That is the one item on a Drive-style navigation panel with no backing endpoint (issue #14).

Package handlers — shares_admin.go

Admin views/actions over all shares (every user, not just current user).

GET    /api/admin/shares
POST   /api/admin/shares/{id}/revoke
DELETE /api/admin/shares/{id}

Package handlers — shares_mine.go

"Paylaştıklarım" / "My shares" — the USER-scoped half of the share surface, and the one audited door to a link's PIN.

GET /api/shares           the links the caller created (paginated)
GET /api/shares/{id}/pin  that link's PIN, to its creator or to an admin

Why this file exists ¶

Until now the only list of shares was /api/admin/shares behind the admin panel, so somebody without admin rights could not see their own links at all: they minted a link from the explorer, the dialog showed it once, and after that the only way back to it was to mint another one. Every other self-service credential surface in this product (API tokens, S3 keys, SSH keys, NFS exports) already has this half. Shares did not.

⚠ This is NOT a second admin listing. It reads the SAME store query (ListAllShares) with the caller pinned as the creator, the same tenant filter and the same row envelope. What it drops is the part that is about everybody rather than about the caller — the creator's address, which on this screen is always the person reading it.

Package handlers — sshkeys.go

GET    /api/auth/ssh-keys            — list the caller's own keys
POST   /api/auth/ssh-keys            — register one (authorized_keys line)
POST   /api/auth/ssh-keys/{id}/state — enable / disable without deleting
DELETE /api/auth/ssh-keys/{id}       — remove permanently

⚠ This screen is a PREREQUISITE for the SFTP endpoint, not a follow-up: `ssh-copy-id` cannot work against filex. It appends to `~/.ssh/authorized_keys` over a shell, and filex has no shell — so without a place to paste a key, public-key authentication is unreachable and everybody falls back to sending their account password to a file server.

Package handlers — storage_drivers.go

GET /api/admin/storage-drivers — the config contract of every
registered storage driver (see storage/descriptor.go).

Why its own admin route instead of a field on /api/capabilities: capabilities is public (embedders and the share/drop pages fetch it without a session) and already hot; driver config schemas — including which fields hold credentials, and the operator-facing hints for them — are only useful to an admin building a storage. `storage_drivers: []string` stays on capabilities untouched for every existing caller.

Package handlers — storages_admin.go

Extra admin actions on storages beyond plain CRUD:

POST /api/admin/storages/test            — try a connection without saving
POST /api/admin/storages/discover        — list the folders under a root, to mount several at once
GET  /api/admin/storages/{id}/sync-runs  — recent runs for one storage
GET  /api/admin/storages/{id}/drift      — recent sync conflicts

Package handlers — supertenant.go ¶

ONE gate for the admin surfaces that are INSTANCE-WIDE.

The distinction the /api/admin block does not draw for you ¶

Every route under /api/admin has already passed `auth.RequireAdmin`, and `auth.TenantResolver` has attached the requester's tenant scope. Neither of those denies anything by itself: the resolver only labels the request, and the scoped store filters exactly three list queries (storages, enabled storages, users). So in multi-tenant mode "admin" means *an* admin — of any tenant — and a route whose effect is instance-wide is, by default, open to all of them.

Most admin routes are fine with that because their DATA belongs to a tenant. A handful do not: they read and write a single global row, or drive a single process, that every tenant then lives with. Those are the ones that must ask this question, and the consequence of forgetting is not a leak but a takeover — the tenant admin of the smallest customer switching antivirus off for the whole platform, or repointing the shared document server at a host they control.

Single-tenant installs are untouched, by construction ¶

`auth.TenantResolver` returns the next handler unchanged when multi-tenant mode is off (auth/tenant_middleware.go), so NO scope is ever attached and `tenant.FromContext` reports absence. Absence means "unscoped" and passes here. The ordinary admin of a non-multi-tenant instance therefore still administers everything, with no flag to thread and nothing to configure — the gate is invisible until somebody turns tenancy on.

Why the gate lives in the handler and not on the route ¶

Because the route is not the only door. `/api/ai/admin` (handlers/ai_admin.go `Register`) mounts the SAME handler instances behind an `admin`-scoped API token, and the MCP admin tools drive those same methods in-process through `AIAdmin.invoke`. A chi middleware in routes.go would gate the browser's door and leave the other two standing open. A check at the top of the method is on the inside of all three.

Package handlers — surface_conditions.go

The HOST half of `show_when` / `required_when`.

The contract (APP-PLUGINS-API.md → Fields, PLUGIN-KIT.md → Screens) makes a plugin author two promises about a field that depends on another field:

"Both are checked on the client AND re-checked by the host at submit: a
 value belonging to a hidden field is dropped before the job runs, so it
 cannot arrive as a surprise, and a `required_when` field left empty
 refuses the job."

The browser half is `packages/core/src/lib/surfaceConditions.ts`, called from `usePluginSurface` on every event it posts. This file is the other half, and it is a LINE-BY-LINE port of that file rather than a second opinion about the same rules: the two halves have to agree exactly, or a plugin gets one answer on screen and another in its job.

⚠ Why the host has to ask the plugin what the screen looks like. A surface is not in the manifest — the plugin DRAWS it per event — so the host has no standing list of fields to check against. At a submit it therefore asks the plugin to draw the screen these values belong to (one `change` call, the same question the browser asks on every keystroke), reads the form fields out of that answer, and applies the rules to the values before the real event is handed over. The conditions are then evaluated by the same cascade the browser uses, so neither side can be talked into a different answer by a crafted request.

⚠ It strips the VALUES, not the job's params. The params are the plugin's own map — it may compute, rename or default anything in there — and dropping keys out of it would delete the plugin's own work. The values are the person's answers, which is exactly what the promise is about; a plugin that never sees a hidden field's answer cannot put it in a job.

Package handlers — sync_admin.go

Admin views over sync runs (cross-storage list + per-run detail).

GET  /api/admin/sync-runs
GET  /api/admin/sync-runs/{id}

Package handlers — tags.go ¶

Personal and team tags (v0.43.0, migration 00055).

GET  /api/files/manager/tags?node_id=…     the tags on one file the caller can see
GET  /api/files/manager/tags?storage_id=…  the tags in use in one storage
GET  /api/files/manager/tags/all           every tag the caller can see
POST /api/files/manager/tags               set a file's tags
GET  /api/files/manager/tagged?tag=…[&kind=personal|team]

The finding this answers ¶

⚠⚠ Tags used to be ONE shared label per file (node_meta `tag:<name>`), with no owner and no tenant, although routes.go introduced them as "Per-user metadata". Measured on v0.42 (tester, 2026-09-22, and reproduced here before the fix): user A tagged a file "Müşteri Teklifi"; user B's and the admin's `tags/all` answered `["müşteri teklifi"]`; B's `POST {tags:[]}` answered 200 and the tag was gone for A; and with multi-tenancy on, tenant bravo's `tags/all` listed tenant alpha's tag. The name had also been lower-cased.

# The rules (the owner's decision: "personal ve team olarak ikiye ayrılır, tenant based tagging yapılır")

• PERSONAL — one person's own label, like a star. Only its owner sees it, adds it or removes it. Anyone who can see a file may personal-tag it.
• TEAM — shared with everyone in the TENANT who can see the file. Adding or removing one needs EDIT permission on the file (the ACL level, `editor` or `owner`); a viewer sees team tags and cannot change them.
• A team tag never crosses a tenant boundary. A confined caller (a tenant in multi-tenant mode) sees its own tenant's team tags plus tenant-0 ones ("the instance": made before a tenant existed on that storage); never another tenant's. An unconfined caller — single-tenant mode, where the tenant IS the instance, or the platform supertenant, which already reaches every storage — sees every team tag on the files it can see.
• A tag is only ever named to someone who can see at least one file that carries it: a tag NAME is information too ("Layoffs Q4").

What an old client gets ¶

A `POST {node_id, tags:[names]}` with no `kind` — every client before v0.43.0 — creates PERSONAL tags. Deliberately the narrow default:

1. A request that does not say who should see a label must not show it to anyone else. The finding WAS an unintended audience; defaulting the old shape to team would reproduce it for every stale tab and script.
2. It always works. Any caller who can see a file may personal-tag it; a team default would turn a viewer's old client into a stream of 403s.
3. It is what the code always claimed ("per-user"), and what the tester expected.

Names in that list that match a tag the file ALREADY carries keep that tag as it is (team stays team) — an old client round-trips the list it read, and an untouched team tag in it is not a change. A team tag the old client leaves OUT is a removal, and needs edit permission like any other.

Case ¶

Names keep the case they were typed in; two names are one tag when internal/tagname.Key says so (case-folded, Turkish I/ı/İ/i merged, NFC). See that package for why strings.EqualFold is not the rule.

Package handlers: tenant_self.go

A tenant runs itself (docs/TENANT-ADMIN.md):

GET    /api/admin/tenant                                  the tenant: addresses, sign-in, domains
POST   /api/admin/tenant/auth-providers                   its own OIDC or LDAP
PATCH  /api/admin/tenant/auth-providers/{name}
DELETE /api/admin/tenant/auth-providers/{name}
POST   /api/admin/tenant/auth-providers/{name}/test
POST   /api/admin/tenant/domains                          {domain}: an own domain, pending
POST   /api/admin/tenant/domains/{id}/check               look at its CNAME now
PUT    /api/admin/tenant/domains/{id}/certificate         {cert_pem, key_pem}: bring a certificate
DELETE /api/admin/tenant/domains/{id}/certificate
DELETE /api/admin/tenant/domains/{id}
PUT    /api/admin/tenant/insecure                         {allow}: the operator's switch

WHOSE tenant: a tenant's administrator acts on their own and nothing else; the platform operator (an unconfined administrator) names one with `?tenant=<id>`. Another tenant's id from a tenant's administrator is 404, the same answer as a tenant that does not exist (handlers/tenantown.go).

The rules the owner decided (2026-09-30, 2026-10-01):

• a tenant's administrator adds their OWN OIDC or LDAP only - the operating-system providers and the header proxy are the operator's, and binding a shared provider is the operator's too;
• a tenant's own provider is guarded (internal/netguard, LDAP only over ldaps:// or StartTLS, the CA pasted, never a file on the server) unless the operator ticked "allow insecure and internal-network providers" for the tenant - which only the operator may change, audited;
• the last way a tenant's administrator can sign in is never switched off by that administrator;
• an own domain is proven by a CNAME to the tenant's platform subdomain, belongs to one tenant at a time, and may carry the tenant's own certificate.

Package handlers — tenantown.go ¶

ONE ownership predicate for the admin routes that take a raw {id}.

A different question from supertenant.go ¶

`supertenant.go` asks "may this tenant touch an instance-wide switch" and answers 403 when it may not — the SURFACE is being refused and the operator needs to read why. This file asks a narrower and more dangerous question: "does the caller's tenant own the ROW it just named". The routes here are legitimate tenant features — a tenant admin absolutely may reset their own user's password, revoke their own share, purge their own trash. They may not do it to somebody else's, and until this file existed nothing asked.

That distinction is why the failure is worse than an over-broad control. Measured on the pre-fix build (`TestOwnership_ForeignIdsAreRefused`), an admin of one tenant reached FIFTEEN of sixteen id-taking admin routes belonging to another tenant — including `POST /users/{id}/reset-password`, which answered 200 and returned the other customer's new cleartext password in the response body, and `GET /storages/{id}`, which returns the storage's whole config blob (for an S3 or SFTP storage: the access key and secret).

Why 404 and not 403 ¶

A 403 confirms the row exists. Repeat it over an id range and the endpoint becomes a census of the platform's other customers — how many storages, how many users, which ids are live. A foreign id must be indistinguishable from one that never existed, so these refusals borrow the shape of the "not found" the handler would otherwise have produced.

Single-tenant installs are untouched, by construction ¶

Same mechanism as supertenant.go: `auth.TenantResolver` attaches no scope when multi-tenant mode is off, absence means "unscoped", and unscoped passes every predicate here. There is no flag to set. The supertenant passes too — the platform operator must keep being able to administer a tenant's rows, including recovering a locked-out tenant admin.

Why the check lives in the handler ¶

Because the chi route is not the only door — `/api/ai/admin` mounts the same handler instances behind an admin-scoped API token and the MCP admin tools drive them in-process. Same reasoning as supertenant.go; see its header.

Package handlers — trash.go ¶

Endpoints:

GET  /api/files/manager/trash                          (auth)  list trashed
POST /api/files/manager/restore                        (auth)  body {node_id}
DELETE /api/admin/trash/{id}                           (admin) immediate single purge
POST /api/admin/trash/empty?older_than_days=N          (admin) start a batch purge
GET  /api/admin/trash/empty                            (admin) that purge's progress

Package handlers — userprefs.go ¶

Endpoints:

GET /api/me/prefs?surface=web   (auth)  → {"surface": "...", "prefs": <object>}
PUT /api/me/prefs?surface=web   (auth)  ← {"prefs": <object>}

What a person chose about the interface itself — theme, palette, density, language. One JSON document per person PER SURFACE (`web` | `desktop`), stored by migration 00047. The account's "open with" choices (0.50) are NOT part of it: GET carries them as `openWith`, PUT drops the key, and /api/me/open-with changes them (openwith.go).

⚠⚠ WHY THE SERVER. The owner picked a theme in one browser and the other browser did not have it. `localStorage` is per BROWSER, never per person: a second machine, a private window, a cleared site and the desktop app are each a fresh empty set of choices, with nothing to notice and no error.

⚠ NOT a replacement for the view prefs (00039, viewprefs.go). Those are how each FOLDER was left and are written on every navigation; these are the surface's own appearance and are read once at sign-in. Two tables because they change at completely different rates and one of them is per folder.

⚠ A caller only ever reaches THEIR OWN row. There is no user id in the path or the body, and the only identity this file consults is the session's, so there is nothing for a client to substitute.

Package handlers — users_admin.go

Admin-only extra actions on users.

POST /api/admin/users/{id}/reset-password

Package handlers — versions.go ¶

Endpoints under /api/files/versions.

GET    /api/files/versions?node_id=…             (viewer) list snapshots
POST   /api/files/versions/snapshot              (editor) snapshot now
POST   /api/files/versions/restore               (editor) restore one
DELETE /api/admin/versions/{id}                  (admin)  hard delete

⚠⚠ Every one of them takes a raw node id, so every one of them resolves the node and authorizes it FIRST — see authorizedNode. Until that existed the only gate here was tenancy, which meant that on a single-tenant install (the vast majority) there was no gate at all: a `viewer` account could POST /restore and overwrite the live bytes of any file whose node id it could name, and POST /snapshot to write objects into any storage on the box.

Package handlers — viewprefs.go ¶

Endpoints:

GET /api/files/manager/view-prefs   (auth)  → {"prefs": <object>, "instance_default": <object|null>}
PUT /api/files/manager/view-prefs   (auth)  ← {"prefs": <object>}

How each person left each folder — view mode, sort key and direction, plus their column widths, order and visibility. One JSON document per user, stored against the user row by migration 00039.

⚠⚠ WHY THIS IS SERVER-SIDE at all, when theme, density and the start page are not. `localStorage` is per BROWSER, not per person: on a shared machine the next account to sign in inherits the previous one's folder arrangements, silently and with no error. The owner ruled that out explicitly ("her user kendi görünümünü görür"), and a server-side document also follows a person to the desktop app and to their other machines, which is what that sentence really asks for.