Python API and scoped API tokens

[krokicki]

Adds scoped API tokens and a Python client, so users can drive Fileglancer from a script or notebook instead of only from the browser.

The motivating workflow, which now works end to end:

import neuroglancer
from fileglancer import Fileglancer

fg = Fileglancer()                                    # reads FILEGLANCER_URL / FILEGLANCER_TOKEN
link = fg.create_data_link("/data/alice/sample.zarr")

state = neuroglancer.ViewerState()
state.layers["sample"] = neuroglancer.ImageLayer(source=f"zarr://{link.url}")

print(fg.create_ng_link(state.to_json(), title="sample"))

How it works

One branch, every route. Token auth is resolved inside auth.get_current_user, the single function all ~49 authenticated routes already depend on. No route was edited, no endpoint changed signature, and cookie users are unaffected — the only edit to shared code is a guard that is a no-op for cookie requests.

Deny-by-default scopes. A path-prefix table maps request paths to files / links / jobs, with GET/HEAD requiring :read and everything else :write. Anything unlisted is unreachable by token, which is what keeps /api/ssh-keys, /api/apps, /api/catalog, /api/preference, /api/ticket and /api/tokens itself session-only — including the case that a token cannot mint another token. A test enumerates app.routes and fails if a new authenticated route is neither scoped nor explicitly session-only, so this cannot drift silently.

Which scopes exist is a server decision. api_token_scopes defaults to everything except files:write and jobs:write. Both amount to full access to the user's files — jobs:write accepts free-form pre_run/post_run shell that runs as the user, so it reaches every file regardless of the files:* scopes granted — so an admin opts into them per server. Enforced at creation and at verification, so removing a scope revokes it from tokens that already hold it rather than only restricting new ones.

Paths, not internal identifiers. The client takes absolute POSIX paths and resolves them to (file share, relative path) entirely client-side, mirroring resolvePathToFsp in the frontend. Nothing was added to the REST API to support it.

Reviewing this

The diff is large but layered; each commit is self-contained and tested. Suggested order:

1. fileglancer/auth.py — the scope table and get_user_from_token. This is the security boundary; everything else is downstream of it.
2. fileglancer/database.py + the migration — token storage. Secrets are stored as SHA-256 only and compared with hmac.compare_digest.
3. fileglancer/server.py — the three /api/tokens routes and the origin-check guard.
4. fileglancer/client.py — the client, readable top to bottom.
5. The frontend: apiTokenQueries.ts, then ApiTokens.tsx and the three dialogs.

Worth a careful look:

• get_user_from_token — the intersection of granted scopes with server-enabled scopes is what makes api_token_scopes a real control. The two 403s are worded differently on purpose: a missing scope is the user's to fix by minting a new token, a disabled one is not, so that message names the administrator.
• The origin-check skip. server.get_current_user skips enforce_request_origin for bearer auth, because a token is not ambient the way a cookie is. The safety property is that auth.get_current_user never falls back to the cookie once an fgt_ bearer is present — otherwise a cross-origin page could pair a junk token with ambient cookies and skip the check. test_bearer_token_never_falls_back_to_cookie_auth pins it.
• jobs:write is documented as full-account access in both the create dialog and the user docs, rather than implying containment it does not have.

Testing

• Backend 917 passing, including a suite for the restricted-scope configuration and one asserting a token loses a scope the server has since disabled.
• Frontend 330 passing.
• One Playwright spec covering create → secret shown once → revoke through the confirmation, asserting the captured secret string is absent from the page afterwards.
• scripts/api_walkthrough.py steps through every client method interactively for manual verification. Verified end to end against a live server: 24 steps, no residue.

Notes for the reviewer

• Docs live in a separate PR: Document the Python API and API tokens fileglancer-docs#24 — a new Features page covering token creation, scopes, paths, data links, the Neuroglancer workflow, jobs, and errors.
• docs/config.yaml.template documents api_token_scopes for admins.
• The design spec is at docs/superpowers/specs/2026-08-24-python-api-design.md, with an Amendments section recording where the implementation deliberately diverged from it — the no-match error no longer enumerating mount points, the dropped cross-language resolver fixture, and three others.
• Access logs identify token requests. AccessLogMiddleware previously resolved identity from the session cookie only, so every programmatic request logged -. Lines now read [rokickik fgt:4e626080362d], giving an admin the user and the exact token to revoke. The token id is the public half — an independent CSPRNG draw, not a prefix of the secret — and is already stored in plaintext and shown in the GUI.
• Known and deferred: cancel_job and the client's context-manager methods are untested. An invalid token still logs -, since it never resolves to an identity.

@StephanPreibisch @JaneliaSciComp/fileglancer @stuarteberg

[mkitti]

Is the only way to set FILEGLANCER_URL through the environment?

[krokicki]

Is the only way to set FILEGLANCER_URL through the environment?

No, you can also set it when creating the API object:

fg = Fileglancer(url="https://your-fileglancer-server", token="fgt_...")

[mkitti]

I think it would be clearer to say os.environ.get("FILEGLANCER_URL") and os.environ.get("FILEGLANCER_TOKEN") here. It took me a minute to realize that this was not string interpolation.

[mkitti]

We should do more validation of the URL and token in this constructor.