JAYSON DERULO

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]"
+}
+```