mbkauthe/docs/env.md

MBKTech's reusable authentication system for Node.js applications.

# Environment Configuration Guide

[← Back to README](README.md)
This document describes the environment variables MBKAuth expects and keeps brief usage notes for each parameter. Validation and defaults are implemented in `lib/config/index.js` (it parses `mbkautheVar`, applies optional `mbkauthShared` fallbacks, normalizes values, and throws on validation failures).

## How configuration is provided
- Primary payload: `mbkautheVar` — a JSON string with app-specific keys.
- Optional shared defaults: `mbkauthShared` — a JSON string used only for missing or empty keys.
- Example: `mbkautheVar={"APP_NAME":"mbkauthe", ...}`

---

## Parameters (short descriptions)

- APP_NAME
  - Description: Application identifier used for access control.
  - Example: `"APP_NAME":"mbkauthe"`
  - Required: Yes

- Main_SECRET_TOKEN
  - Description: Primary token used for internal auth and validations.
  - Example: `"Main_SECRET_TOKEN":"my-secret-token"`
  - Required: Yes

- SESSION_SECRET_KEY
  - Description: Cryptographic key for sessions/cookies. Use a long random string.
  - Example: `"SESSION_SECRET_KEY":"<32+ random chars>"`
  - Required: Yes

- IS_DEPLOYED
  - Description: Deployment mode flag; affects cookie domain and localhost behavior.
  - Values: `true` / `false` / `f` (normalized to strings)
  - Example: `"IS_DEPLOYED":"false"`
  - Required: Yes

- DOMAIN
  - Description: App domain (e.g., `localhost` or `yourdomain.com`). Required when deployed.
  - Example: `"DOMAIN":"localhost"`
  - Required: Yes

- LOGIN_DB
  - Description: PostgreSQL connection string for auth (must start with `postgresql://` or `postgres://`).
  - Example: `"LOGIN_DB":"postgresql://user:pass@localhost:5432/mbkauth"`
  - Required: Yes
  - Create free postgres db: https://neon.com/

- MBKAUTH_TWO_FA_ENABLE
  - Description: Enable Two-Factor Authentication.
  - Values: `true` / `false` / `f`
  - Example: `"MBKAUTH_TWO_FA_ENABLE":"true"`
  - Required: Yes

- COOKIE_EXPIRE_TIME
  - Description: Session cookie lifetime (days).
  - Default: `2`
  - Example: `"COOKIE_EXPIRE_TIME":7`
  - Required: No

- DEVICE_TRUST_DURATION_DAYS
  - Description: Days a device remains trusted (skips some auth steps).
  - Default: `7`
  - Example: `"DEVICE_TRUST_DURATION_DAYS":30`
  - Required: No

- MAX_SESSIONS_PER_USER
  - Description: Maximum number of concurrent application sessions allowed per user. When creating a new session that would exceed this number, the oldest session(s) for that user are pruned to make room for the new session.
  - Default: `5`
  - Example: `"MAX_SESSIONS_PER_USER": 10`
  - Notes: Must be a positive integer. Validation is performed at startup by `lib/config/index.js`.
  - Required: No

- loginRedirectURL
  - Description: Post-login redirect path.
  - Default: `/dashboard`
  - Example: `"loginRedirectURL":"/dashboard"`
  - Required: No

- env
  - Description: Development flag to enable diagnostics (DB query monitor, debug endpoints).
  - Values: `dev` to enable; any other value disables.
  - Example: `env=dev`
  - Required: No

- bucket
  - Description: Optional external storage bucket name or identifier used for static assets or third-party integrations.
  - Default: an empty string `""` (no bucket configured)
  - Example: `"bucket":"s3-bucket-name"`
  - Usage: Future use in mbkbucket
  - Required: No

- GITHUB_LOGIN_ENABLED / GOOGLE_LOGIN_ENABLED
  - Description: Enable social login providers.
  - Default: `false`
  - If `GOOGLE_LOGIN_ENABLED=true`, `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are required.
  - If `GITHUB_LOGIN_ENABLED=true`, GitHub App client credentials are required.

- GITHUB_APP_SLUG
  - Description: GitHub App slug (optional for login flow in this package; useful for install/link flows handled elsewhere).
  - Required: No
  - Create GitHub App: https://github.com/settings/apps

- GITHUB_APP_CLIENT_ID / GITHUB_APP_CLIENT_SECRET
  - Description: GitHub App OAuth credentials used for user sign-in.
  - Required when `GITHUB_LOGIN_ENABLED=true`.

- GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET
  - Description: Legacy fallback keys if app-prefixed keys are not provided.

- GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
  - Description: Google OAuth credentials.
  - Required when `GOOGLE_LOGIN_ENABLED=true`.
  - Create Google OAuth: https://console.cloud.google.com/

---

## Quick examples
Development (.env):

```env
mbkautheVar={"APP_NAME":"mbkauthe","Main_SECRET_TOKEN":"dev-token","SESSION_SECRET_KEY":"dev-secret","IS_DEPLOYED":"false","DOMAIN":"localhost","LOGIN_DB":"postgresql://user:pass@localhost:5432/mbkauth_dev","MBKAUTH_TWO_FA_ENABLE":"false"}
mbkauthShared={"GITHUB_LOGIN_ENABLED":"false"}
```

Production (short):

```env
mbkautheVar={"APP_NAME":"mbkauthe","Main_SECRET_TOKEN":"prod-token","SESSION_SECRET_KEY":"prod-secret","IS_DEPLOYED":"true","DOMAIN":"yourdomain.com","LOGIN_DB":"postgresql://dbuser:secure@db:5432/mbkauth_prod","MBKAUTH_TWO_FA_ENABLE":"true"}
```

---

## Rules & best practices
- Boolean-like fields: use `"true"`, `"false"`, or `"f"` (the parser accepts booleans too and normalizes to strings).
- Numeric fields: must be positive numbers (e.g., `COOKIE_EXPIRE_TIME`, `DEVICE_TRUST_DURATION_DAYS`).
- `LOGIN_DB` must start with `postgresql://` or `postgres://`.
- Never commit `.env` to source control and use HTTPS in production (when `IS_DEPLOYED=true`).
- Use a >=32-char `SESSION_SECRET_KEY` and rotate secrets regularly.

For the exact validation messages and default application, consult `lib/config/index.js` (it will throw a comprehensive error if validation fails at startup).