diff options
Diffstat (limited to 'auth')
| -rw-r--r-- | auth/README.md | 26 | ||||
| -rw-r--r-- | auth/clear_sessions.md | 46 | ||||
| -rw-r--r-- | auth/login.md | 69 | ||||
| -rw-r--r-- | auth/logout.md | 27 | ||||
| -rw-r--r-- | auth/status.md | 61 |
5 files changed, 229 insertions, 0 deletions
diff --git a/auth/README.md b/auth/README.md new file mode 100644 index 0000000..de81c28 --- /dev/null +++ b/auth/README.md @@ -0,0 +1,26 @@ +# Authentication + +[back to index](../README.md) + +How sessions work. Login to get a token, send it on every request, logout when done. + +Not that hard see? + +## Pages + +- [Login](login.md) `POST /auth/login` authenticate and get a session token +- [Logout](logout.md) `POST /auth/logout` kill yourself +- [Status](status.md) `GET /auth/status` check if your session is still alive and when it kills itself +- [Clear Sessions](clear_sessions.md) `POST /auth/clear-sessions` adminier: nuke all sessions for a specific user + +## How it works + +1. call `/auth/login` with credentials using ur sign in methodick. +2. get a magic session token back +3. send that token as `Authorization: Bearer <token>` on every damn request after that +4. when youre done call `/auth/logout` to kill yourself +5. sessions expire after a configurable timeout if you dont use them + +Sessions should optionally be able to persist across server restarts (server should only store a hash of the token in the database, never the raw token itself obviously). On restart it loads them hash brownies back. + +Each user should have a max number of concurrent sessions (configurable). When you go over the limit the oldest session gets deported to hell automatically to make room for the new one. diff --git a/auth/clear_sessions.md b/auth/clear_sessions.md new file mode 100644 index 0000000..4c597ee --- /dev/null +++ b/auth/clear_sessions.md @@ -0,0 +1,46 @@ +# POST /auth/clear-sessions + +[back to auth](README.md) /// [home](../README.md) + +Adminier endpoint to nuke all active sessions for a specific user. Useful when you need to force someone to relogin or if an account might be compromised. + +Requires a power level equal to or greater than `min_clear_sessions_power` (configurable). + +## Request Body + +```json +{ + "user_id": 42 +} +``` + +| Field | Type | Required | Notes | +|-----------|---------|----------|----------------------------------------------| +| `user_id` | integer | yes | the user whose sessions you want to kill duh | + +## Success Response (200) + +```json +{ + "success": true, + "sessions_cleared": 3, + "user_id": 42 +} +``` + +`sessions_cleared` tells you how many sessions were murdered. If the user had no active sessions its 0 and thats still a success. + +## Error Responses + +| Code | When | +|------|-----------------------------| +| 401 | no token or invalid session | +| 403 | your power level is too low | + +The 403 error message optionally may tell you what power level is required. + +## Notes + +- this only affects the targeted users sessions obv. your own stays alive +- works on any user including yourself if you want to nuke your own other sessions +- cleared sessions are removed from both the in memory cache and the database (if persistent sessions are on and supported obv.) diff --git a/auth/login.md b/auth/login.md new file mode 100644 index 0000000..ea9ea46 --- /dev/null +++ b/auth/login.md @@ -0,0 +1,69 @@ +# POST /auth/login + +[back to auth](README.md) /// [home](../README.md) + +Authenticate and get a session token. No auth required (obviously). + +## Request Body + +```json +{ + "method": "password", + "username": "admin", + "password": "secret" +} +``` + +## Fields + +| Field | Type | Required | Notes | +|----------------|--------|---------------|-----------------------------------------------| +| `method` | string | yes | `password`, `pin` or `token` | +| `username` | string | password, pin | required for password and pin methods | +| `password` | string | password | only for password method | +| `pin` | string | pin | only for pin method | +| `login_string` | string | token | only for token method (NFC cards, badges etc) | + +## Auth Methods + +### password +Standard username + password. No EyePee Restrictions. + +### pin +Short numeric PIN for quick auth (like kiosk scenarios). The clients IP **must** be whitelisted in the servers security config or its a 403. This is a hard requirement, there should never be a bypass for this. ever. seriously. (unless you are dumb enough to set whitelisted IP's to 0.0.0.0/0 for whatever reason but then thats your own fault dumbass) + +### token +Login string based auth for things like NFC card scans or badge readers. Same deal as PIN, clients IP **must** be whitelisted or its 403. + +## Success Response + +```json +{ + "success": true, + "token": "your-session-token-here", + "user": { + "id": 1, + "username": "admin", + "name": "Full Name", + "role": "administrators", + "power": 100 + } +} +``` + +Store the `token` and send it on all future requests as `Authorization: Bearer <token>`. + +The `user` object gives you basic info about whos logged in. `power` is the users power level (1 lowest, 100 highest) which determines what jsonderulo lets them do. + +## Error Responses + +| Code | When | +|------|------------------------------------------------------------------------------| +| 400 | missing required fields for the chosen method | +| 401 | wrong password, wrong pin, wrong login_string, user not found, user inactive | +| 403 | IP not whitelisted (pin and token methods only) | +| 500 | database error | + +## Concurrent Sessions + +Each user should have a max number of concurrent sessions (configurable per power level + a global default). When a user logs in and is already at the limit the **oldest** session should get automatically evicted from json derulos premises! diff --git a/auth/logout.md b/auth/logout.md new file mode 100644 index 0000000..4d0d469 --- /dev/null +++ b/auth/logout.md @@ -0,0 +1,27 @@ +# POST /auth/logout + +[back to auth](README.md) /// [home](../README.md) + +Kill your yourself. Requires a valid session token obviously. + +## Request + +No sexy json derulo body needed. Just send the token in the header: +``` +Authorization: Bearer <token> +``` + +## Success Response + +```json +{ + "success": true, + "message": "Logged out successfully" +} +``` + +## Error Response + +| Code | When | +|------|-----------------------------------------------| +| 401 | no token provided or token is invalid/expired | diff --git a/auth/status.md b/auth/status.md new file mode 100644 index 0000000..354ea9b --- /dev/null +++ b/auth/status.md @@ -0,0 +1,61 @@ +# GET /auth/status + +[back to auth](README.md) /// [home](../README.md) + +Check if your session is still alive and get details about it. + +## Request + +No body. Token in header: +``` +Authorization: Bearer <token> +``` + +## Valid Session Response (200) + +```json +{ + "success": true, + "valid": true, + "user": { + "id": 1, + "username": "admin", + "name": "Full Name", + "role": "administrators", + "power": 100 + }, + "session": { + "created_at": "2026-02-14T10:30:00Z", + "last_accessed": "2026-02-14T11:45:00Z", + "timeout_minutes": 120, + "remaining_seconds": 5400, + "expires_at": "2026-02-14T13:45:00Z" + } +} +``` + +The `session` object tells you when the session was created, when it was last used, how long the timeout is, how many seconds are left and when itll expire if nothing happens. + +If session refresh on activity is enabled (which it should be by default) then `last_accessed` gets updated on every request so the session keeps extending as long as youre actively bothering jsonderulo. + +## Invalid/Expired Session Response (401) + +```json +{ + "success": true, + "valid": false, + "message": "Session expired or invalid [request_id: 12345678]" +} +``` + +Note that `success` is still true here because the status check itself worked fine, the session is just dead lol. Check the `valid` field to know if the session is actually alive. + +## No Token Response (401) + +```json +{ + "success": false, + "valid": false, + "error": "No authorization token provided [request_id: 12345678]" +} +``` |