Fileserver REST API

Lightweight Python/Flask REST API that exposes file-server functionality using underlying Linux user accounts for authentication and authorization. Designed to be embedded or extended by other services.

Key Features

• User/session management via system accounts and session tokens.
• File and directory operations (list, download, upload, create directory, delete), respecting Linux filesystem permissions.
• Partial content / Range support for downloads.
• OpenAPI specification included for endpoint reference.

See the OpenAPI spec at openapi.yaml for full API details and examples.

Getting Started

Prerequisites:

• Python 3.8+ (3.11 recommended)
• Virtual environment tooling (venv)
• Linux system user management access for test accounts

1. Create and activate a virtual environment

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure environment variables

Create a .env file from .env.sample or export variables directly. Example:

export APPLICATION_NAME=fileserver

3. (Optional) Create a test user

Use the provided script to create a limited test user and application directory:

sudo ./scripts/create_user.sh -u testuser -a fileserver

Notes:

• Do not use your real system account — the server performs filesystem operations as the authenticated Linux user.
• Validate permissions with su - testuser after creation.

Running the Server

Start the server:

python run.py

Run with the Flask CLI

You can also run the application using the Flask CLI which will pick up the application module or factory.

Factory-based (recommended when using an app factory):

export FLASK_APP=fileserver:create_app
# optional: enable debug mode
export FLASK_ENV=development
flask run --host=0.0.0.0 --port=5000

Notes:

• If python-dotenv is installed, Flask CLI will automatically load a .env file in the project root, allowing you to set APPLICATION_NAME, TOKEN_TTL_SECONDS, or other environment variables there.
• When running via flask run the same privilege considerations apply: switching effective UID/GID requires the process to run with suitable privileges.

The API base path is /api by default. Use the OpenAPI file for exact endpoints.

Local Auth Provider

The repository includes a local authentication helper service (reads /etc/shadow) for environments where in-process PAM is not suitable. This service listens on 127.0.0.1:5001 and requires appropriate privileges.

Start/stop the local provider from the project root:

./start_auth.sh
./stop_auth.sh

Service logs and PID are stored under authserver/.

Usage Examples

• Authenticate: POST /api/login (HTTP Basic) -> returns bearer token
• Use returned token: Authorization: Bearer <token> for subsequent requests
• Logout: POST /api/logout invalidates the session token

An end-to-end example is in rest-tests.http.

Security and Permissions

• Operations execute with the effective identity of the authenticated Linux user. If the process cannot switch identities, operations run under the server process user and may fail with 403/404 due to filesystem permissions.
• The local auth provider reads /etc/shadow and must run with appropriate privileges — avoid exposing it publicly.

Development and Testing

• Run unit/integration tests if present (no test runner included by default).
• Use the included rest-tests.http for manual API testing with VS Code REST Client or similar tools.

Docker

Quick usage:

Build: docker build -t fileserver-demo .

Run (foreground): docker run --rm -p 5000:5000 -p 5001:5001 --name fileserver-demo fileserver-demo

Notes:

• Image base: python:12-slim.
• APPLICATION_NAME set to FileServerDemo in the image.
• A system user testuser with password testpassword is created inside the container.
• The container starts the local auth provider and then the Flask app.

Contributing

Please follow repository standards when contributing:

• Open issues for bugs or feature requests
• Create small, focused pull requests with clear descriptions
• Respect security practices when handling system user credentials

See CONTRIBUTION.md for more details.

License

see LICENSE

Authors / Maintainers

• See repository metadata and commit history for authorship information.

References

• OpenAPI: openapi.yaml
• Example tests: rest-tests.http

---

How to use in a host project

You can embed this repository into a larger project (for example a VueJS frontend + Python backend monorepo) in a few simple ways. Below are recommended placements, install instructions, and configuration notes.

• Recommended paths when adding as a git sub-repo:

  • services/fileserver — for a microservice-oriented layout
  • backend/fileserver — if your host repo already groups backend services
  • vendor/fileserver-rest or third_party/fileserver-rest — if you prefer to vendor the dependency

• Add as a submodule (keeps history and upstream link):

git submodule add <repo-url> services/fileserver
git submodule update --init --recursive

• Development install (host project's venv):

pip install -e services/fileserver

• How to run / import from the host backend:

• Import the application factory from the package and use it in your host application:

from fileserver import create_app
app = create_app()
# or import/run the provided run.py if you prefer the bundled runner

• Useful environment variables (when embedding):

• LOCAL_PROVIDER_URL — override the local auth provider endpoint (default http://127.0.0.1:5001/verify).

• ENABLE_CORS — set to 1 or true to enable CORS for /api/* (requires flask-cors in the environment).

• TOKEN_BACKEND — set to redis to use Redis for token storage (default: in-memory).

• REDIS_URL — required when TOKEN_BACKEND=redis, e.g. redis://localhost:6379/0.

• Vue / Vite dev server proxy example (so the frontend can call /api without CORS in dev):

// vite.config.js
export default {
  server: {
    proxy: {
      '/api': 'http://localhost:5000',
    },
  },
}

• Quick run example from host project (after pip install -e):

export ENABLE_CORS=1
export LOCAL_PROVIDER_URL=http://127.0.0.1:5001/verify
python -m fileserver.run

Notes:

• For production it's often preferable to run this service as a separate container/service and route from your frontend or API gateway. When running separately, ensure CORS or proxying is configured appropriately.
• The default in-memory token backend is fine for single-process development. For multi-process or clustered deployments set TOKEN_BACKEND=redis and provide REDIS_URL.