# Token Auth Behavior

This document is focused on how `SESSIONEXPIRETIME` controls token/session behavior in:

- `generateToken($userId, $qry)`
- `verifyToken($rawToken, $qry = null)`

## Overview

Authentication uses file-backed session tokens stored on disk under `DOI_UPLOAD_TOKEN_PATH`.

Flow:

1. Login success calls `generateToken()` and returns a raw token string.
2. Every protected API call sends that token and is validated via `checkAuthToken()` -> `verifyToken()`.
3. `verifyToken()` enforces idle timeout and refreshes activity (`touch`) on valid requests.
4. Logout calls `logoutToken()` and removes the token file.

## What SESSIONEXPIRETIME Means

- Unit: **minutes**
- Purpose: session idle timeout window
- Used in both token creation and verification
- Rule in code:
  - if `SESSIONEXPIRETIME` is defined and `> 0`, that value is used
  - else fallback is `1440` (24 hours)

## Where It Is Used

### 1) In `generateToken()`

`generateToken()` calculates and stores:

- `expiry = time() + (SESSIONEXPIRETIME * 60)`

This is saved into token JSON, but runtime session validation is mainly driven by file activity time (`mtime`) inside `verifyToken()`.

### 2) In `verifyToken()`

`verifyToken()` checks:

- `lastModifiedTimestamp = filemtime(token_file)`
- if `time() - lastModifiedTimestamp > (SESSIONEXPIRETIME * 60)` -> token expired
- if not expired -> `touch(token_file)` to refresh activity time (sliding timeout)

This makes timeout **idle-based**, not strict fixed-expiry.

## Sliding Timeout Logic (Important)

Because `touch()` is called on every valid request:

- Active user keeps session alive.
- Inactive user gets logged out after `SESSIONEXPIRETIME` minutes.

Example with `SESSIONEXPIRETIME = 30`:

- User logs in at `10:00`
- API calls at `10:10`, `10:20`, `10:35` keep extending session
- If no call after `10:35`, session expires at around `11:05`

## Configuration Guidance

Set `SESSIONEXPIRETIME` in environment config files (minutes):

- lower value = stronger security, more frequent re-login
- higher value = better UX, longer exposure window if token leaks

Suggested baseline:

- Admin/staff portals: `15` to `60`
- Standard web session: `60` to `480`
- Current fallback in code: `1440` (use only if intentionally desired)

## Edge Cases

- If `SESSIONEXPIRETIME` is missing/invalid/<=0, code silently uses `1440`.
- If token file is missing/corrupt, validation fails immediately.
- On timeout, token file is deleted and `session_timeout` audit entry is attempted.

## Quick Verification Checklist

When changing `SESSIONEXPIRETIME`, verify:

- Login generates token successfully.
- Active requests keep session alive beyond initial timeout boundary.
- Idle session expires at expected minute mark.
- Timeout deletes token file.
- API starts returning unauthorized after expiry.

## Related Functions (Reference)

- `generateToken($userId, $qry)`: creates token and writes token file.
- `verifyToken($rawToken, $qry = null)`: enforces idle timeout using `SESSIONEXPIRETIME`.
- `checkAuthToken($token, $qry = null)`: wrapper that also checks `is_active=1` when DB object is provided.
- `logoutToken($rawToken)`: deletes token file.