EQEQO Auth API

Centralized authentication and authorization service for the Eqeqo ecosystem. Issues short-lived tokens, renews them atomically near expiry, and enforces access control with a DB-backed token cache plus periodic cleanup.

⚙️ Setup

Local setup

psql -U postgres -f db/run_all.sql
cp .env.example .env
cargo run

Tests Integration tests rely on the seeded api_auth DB from db/run_all.sql. Default server: http://127.0.0.1:7878

cargo test --test api_test

Environment:

AUTH_DATABASE_URL=postgres://USER:PASSWORD@HOST/api_auth
SERVER_PORT=7878
TOKEN_TTL_SECONDS=300
TOKEN_RENEW_THRESHOLD_SECONDS=30

Data reference: see ./db/DB.md (seeded dataset: IDs, users, services, roles, permissions).

🔐 Auth essentials

• All protected routes require the token: header (never pass tokens in URLs).
• Tokens are cached centrally in auth.tokens_cache; renewal is atomic when near expiry.
• Logout or user deletion revokes related tokens; a background job prunes expired tokens every ~60 seconds.
• Minimal logging per request records token, endpoint, timestamp, and IP.
• Tokens are stored hashed in the cache; user passwords are stored as bcrypt hashes (demo users seeded with bcrypt).

🚀 Quick request example

Example: fetching user data for “Juan” (id 7) from client servcli1 using an arbitrary token:

curl -X GET "http://127.0.0.1:7878/users/7" \
  -H "token: tok_example_123" \
  -H "x-client-id: servcli1"

x-client-id is optional metadata; the API currently only enforces the token header.

🧩 Endpoints

🔁 Token logic

• Generated at login (hash(secret + random + timestamp)). NO JWT nor similar.

• Stored centrally in auth.tokens_cache with payload and modified_at; token values are stored hashed (no plaintext).

• Tokens are issued per user (global); services query permissions by sending token: + person_id + service_id to /people/{person_id}/services/{service_id}.

• All protected requests must include token: header (no query params). /auth/login is the only public route.

• Short TTL (2–5 min) with atomic renewal near expiry to avoid contention.

• Revocation on logout or user deletion; cleanup job periodically removes expired tokens.

• /check-token can optionally validate user to avoid token misuse.

• No tokens in URLs.

• Minimal logging per request: token, endpoint, timestamp, IP.

• Background cleanup job trims expired tokens every ~60 seconds.

🧭 Use case diagram

sequenceDiagram
  autonumber
  actor UI as Frontend (UI)
  participant BACK as Backend (Stock / Sales / Manufacturing)
  participant AUTH as Auth API

  %% 1. Login
  UI->>AUTH: POST /auth/login { user, pass }
  AUTH-->>UI: { token }

  %% 2. Request from UI to Back
  UI->>BACK: GET /{service_id_string}/{user_id_string}\nheaders: token

  %% 3. Cache check + request to Out
  alt Valid local cache (<= 1 min)
    BACK-->>UI: responds using cached payload
  else Expired or missing cache, valid token in Out
    BACK->>AUTH: POST /check-token\n{ token, service_id, user_id } (token header, hashed in cache)
    AUTH-->>BACK: { valid: true, payload }
    BACK-->>UI: responds and saves payload in cache (1 min)
  else Expired or missing cache, invalid token in Out
    BACK->>AUTH: POST /check-token\n{ token, service_id, user_id } (token header, hashed in cache)
    AUTH-->>BACK: { valid: false }
    BACK-->>UI: 401 Unauthorized
  end

  %% 4. Writes always validated
  Note over BACK,AUTH: Write operations (POST / PATCH / DELETE)\nalways query Out without using local cache.

  %% 5. Logout
  UI->>AUTH: POST /auth/logout { token }
  AUTH-->>UI: 200 Logged out

MIT © Eqeqo