make kestrel a tak server, so that it can send and receive pois as cots data

docs/auth.md

@@ -0,0 +1,106 @@
+# Authentication
+
+KestrelOS supports **local login** (username/email + password) and optional **OIDC** (single sign-on with an identity provider). All users must sign in to use the app.
+
+---
+
+## Local login
+
+### First run: bootstrap admin
+
+On first start, if the database has no users, KestrelOS creates an **admin** account:
+
+- **If you set env vars:**  
+  `BOOTSTRAP_EMAIL` and `BOOTSTRAP_PASSWORD`  
+  → That account is created (identifier = email, role = admin).
+
+- **If you do not set them:**  
+  A default admin is created with identifier **`admin`** and a **random password**.  
+  The password is printed in the terminal—copy it and sign in at **/login**.
+
+After first login, change the password or add users via **Members** (admin only).
+
+### Signing in (local)
+
+1. Open **/login** (or you’ll be redirected there when visiting a protected page).
+2. Enter **Email or username** (identifier) and **Password**.
+3. Click **Sign in**. You’re redirected to the map or the page you came from.
+
+Local users can always use this form. Their password is stored hashed in the database.
+
+---
+
+## OIDC config and sign up
+
+OIDC lets users sign in with an external identity provider (IdP), e.g. Keycloak, Auth0, or your organization’s IdP. There is **no “sign up” inside KestrelOS** for OIDC: accounts are created when a user signs in for the first time (first-time OIDC login creates a KestrelOS user linked to that IdP identity).
+
+### Enabling OIDC
+
+Set these environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OIDC_ISSUER` | Yes | IdP issuer URL (e.g. `https://auth.example.com/realms/myrel`). |
+| `OIDC_CLIENT_ID` | Yes | OIDC client ID. |
+| `OIDC_CLIENT_SECRET` | Yes | OIDC client secret. |
+| `OIDC_LABEL` | No | Button label (default: "Sign in with OIDC"). |
+| `OIDC_REDIRECT_URI` | No | Callback URL (default: `{APP_URL}/api/auth/oidc/callback`). |
+| `OIDC_SCOPES` | No | Scopes (default: `openid profile email`). |
+
+The app derives the redirect URI if not set:
+
+- Prefer **`NUXT_APP_URL`** or **`APP_URL`** (e.g. `https://kestrelos.example.com`).  
+  Callback = `{that base}/api/auth/oidc/callback`.
+- Otherwise it uses **`HOST`**, **`PORT`**, and **`NODE_ENV`** (e.g. `http://localhost:3000/api/auth/oidc/callback`).
+
+### IdP configuration
+
+In your IdP:
+
+1. Create an **OIDC client** (confidential, or public with PKCE if supported).
+2. Set **Redirect URI** to:  
+   `https://<your-kestrelos-host>/api/auth/oidc/callback`  
+   (or the same with `http` for local dev).
+3. Copy **Client ID** and **Client Secret** into `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET`.
+4. Set **Issuer** in `OIDC_ISSUER` (issuer URL from the IdP’s discovery document).
+
+### OIDC sign-in flow
+
+1. User opens **/login** and clicks the OIDC button (e.g. “Sign in with OIDC”).
+2. They are redirected to the IdP to sign in (and sign up at the IdP if needed).
+3. After success, the IdP redirects back to KestrelOS with an authorization code.
+4. KestrelOS exchanges the code for tokens and creates or finds the user (by `oidc_issuer` + `oidc_sub`), then logs them in.
+
+**Sign up:** Done at the IdP. The first time a user completes OIDC login, KestrelOS creates a new user; no separate “sign up” page in KestrelOS.
+
+### OIDC and ATAK/iTAK
+
+OIDC users don’t have a KestrelOS password. To use **ATAK or iTAK** with “Use Authentication,” they must set an **ATAK password** once in the web app:
+
+1. Sign in with OIDC.
+2. Go to **Account**.
+3. Under **ATAK / device password**, set and confirm a password, then save.
+
+They then use their **KestrelOS username** (identifier) and this **ATAK password** in the TAK client. See [ATAK and iTAK](atak-itak.md).
+
+---
+
+## Roles
+
+- **Admin** — Can manage users (add, edit, delete, change roles), edit POIs, and add/edit devices (via API).
+- **Leader** — Can edit POIs and add/edit devices (via API). Cannot change user roles.
+- **Member** — Can view map, cameras, and POIs; can use Share live. Cannot edit POIs or manage devices.
+
+Only admins can change roles (Members page).
+
+---
+
+## Summary
+
+| Goal | Action |
+|------|--------|
+| First-time setup | Set `BOOTSTRAP_EMAIL` / `BOOTSTRAP_PASSWORD` or use printed default admin password. |
+| Local sign-in | Use **/login** with identifier and password. |
+| Enable SSO | Set `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` (and optional `OIDC_LABEL`, `OIDC_REDIRECT_URI`). |
+| “Sign up” with OIDC | Users sign up at the IdP; first OIDC login in KestrelOS creates their account. |
+| Use ATAK/iTAK as OIDC user | Set **ATAK password** under **Account** in the web app. |