Usage Guide

Overview

SecShare is a self-hosted, authenticated file-sharing service. It gives each user a private space to store and retrieve files through a simple REST API and a lightweight web interface.

The core idea is ownership isolation: when you upload a file it belongs to your account only. No other user can list, download, or delete it. Every request that touches files must carry a valid access token, so files are never exposed anonymously.

Who it's for

• Individuals who want a private, no-frills place to keep documents accessible from anywhere.
• Small teams that need each member to hold their own set of files behind a login.
• Developers who want a clean REST backend to build on, or to use as a reference for JWT-secured file handling.
• Learning & security testing, where a compact, self-contained upload/download service is useful to study.

Getting started

1. Open the home page and choose Create account.
2. Enter your email and a password of at least 8 characters, then submit.
3. Switch to Sign in and log in with the same credentials.
4. You'll land on your dashboard, where you can upload files and see your storage usage.

The web app keeps you signed in across page reloads by storing your access token in the browser. Use Sign out to clear it.

Authentication

SecShare uses JWT bearer tokens. You obtain a token by logging in, then attach it to every protected request.

1. Register

curl -X POST https://your-host/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"supersecret"}'

2. Log in and capture the token

curl -X POST https://your-host/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"supersecret"}'

# → { "accessToken": "eyJhbGciOi..." }

3. Call a protected endpoint

curl https://your-host/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOi..."

Working with files

Upload

Send the file as multipart form data under the field name file:

curl -X POST https://your-host/api/files/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/report.pdf"

The response contains the stored file's id, name, size, content type, and creation time.

List your files

curl https://your-host/api/files \
  -H "Authorization: Bearer $TOKEN"

Download

curl https://your-host/api/files/<id> \
  -H "Authorization: Bearer $TOKEN" -O -J

Delete

curl -X DELETE https://your-host/api/files/<id> \
  -H "Authorization: Bearer $TOKEN"

Deletion is permanent and only works on files you own; requesting someone else's file returns 403 Forbidden.

Sharing files

Beyond keeping files private, you can deliberately share one of your files in three ways. You create a share with POST /api/files/{id}/shares (or from the dashboard), passing a type.

Public links

A tokenized URL anyone can open at the short path /s/<token>. Optionally protect it with a password, an expiry, and/or a maximum download count.

curl -X POST https://your-host/api/files/<id>/shares \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"LINK","password":"optional","expiresInMinutes":1440,"maxDownloads":5}'

Direct user grants

Grant access to a specific registered user by email. They'll find it under GET /api/files/shared-with-me.

Email audiences

Share with a whole email list at once. Each recipient gets their own account-less link, which can be emailed out automatically when mail delivery is enabled.

Security & scanning

Every upload is scanned synchronously, before it is stored. A built-in heuristic scanner always runs; when ClamAV is enabled it runs additionally for real-world coverage. If any engine flags the file, the upload is rejected with 400 Bad Request and nothing is written to disk.

API reference

Limits & rules

• Maximum file size: 50 MB per file.
• Allowed types: pdf, png, jpg, jpeg, txt, doc, docx, xlsx, zip.
• Password: minimum 8 characters at registration.
• Isolation: you can only access files owned by your account.

FAQ

Can other people see my files?

No. Files are scoped to the account that uploaded them. Only an administrator role can list files across all users.

What happens when my token expires?

Protected requests start returning 401 Unauthorized. Log in again to obtain a fresh token; the web app does this transition for you by signing you out.

Why was my upload rejected?

The most common reasons are an unsupported file extension or a file larger than 50 MB. The API responds with 400 Bad Request or 413 Payload Too Large and a short message explaining which rule was violated.

Is there a programmatic list of endpoints?

Yes. Call GET /api/info for a JSON summary of the service, its limits, and every endpoint.