# Token Auth Behavior

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

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

## 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.

## What SESSIONEXPIRETIME Means

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

## Where It Is Used

### In `verifyToken()`

`verifyToken()` checks:

- `expireMinutes = (defined('SESSIONEXPIRETIME') && SESSIONEXPIRETIME > 0) ? SESSIONEXPIRETIME : 1440`
- `lastModifiedTimestamp = filemtime(token_file)`
- if `time() - lastModifiedTimestamp > (expireMinutes * 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 verification code: `1440` (24 hours)

## Edge Cases

- If `SESSIONEXPIRETIME` is missing/invalid/<=0, verification uses `1440`.
- If token file is missing/corrupt, validation fails immediately.
- On timeout, token file is deleted.

## 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 data and writes token file.
- `verifyToken($rawToken)`: enforces idle timeout using `SESSIONEXPIRETIME`.
- `checkAuthToken($token)`: wrapper that validates token and returns `user_id` or `false`.