From 3bf9702b23a78033b1722c226205f67044ad39dc Mon Sep 17 00:00:00 2001 From: Leo Vasanko Date: Fri, 19 Dec 2025 18:34:12 +0000 Subject: [PATCH] Docs updates. --- API.md | 37 +++++++++++++++++++++---------------- scripts/devserver.py | 8 ++++++-- 2 files changed, 27 insertions(+), 18 deletions(-) diff --git a/API.md b/API.md index b3588b1..be8ce2d 100644 --- a/API.md +++ b/API.md @@ -17,42 +17,47 @@ Use these tables when integrating Paskia authentication into your app. | GET | `/auth/api/settings` | Paskia configuration | Returns RP info + base paths + session cookie name | | POST | `/auth/api/user-info` | Full user profile | Basic information, credentials, sessions, permissions | | POST | `/auth/api/logout` | Terminate session and delete session cookie | Signs out of the current site | -| POST | `/auth/api/validate` | Validate and renew session cookie | Optional query: `perm=` (repeatable) | +| POST | `/auth/api/validate` | Validate and renew session cookie | Optional query: `perm=` (repeatable), `max_age=` | | GET | `/auth/api/forward` | Validate access (Caddy/Nginx) | 204 on success; 401/403 otherwise (HTML if requested) | -The `forward` endpoint takes query arguments `perm=` and `max_age=` for specific requirements on the validation of the current session. - +The `validate` and `forward` endpoints take query arguments `perm=` and `max_age=` for specific requirements on the validation of the current session. ### User JSON API: `/auth/api/user/*` | Method | Path | Used for | Notes | |---:|---|---|---| | PUT | `/auth/api/user/display-name` | Update the user’s display name | Body: JSON `{ "display_name": "..." }` | -| POST | `/auth/api/user/logout-all` | Terminate all user sessions and clear cookie | Clears current cookie | +| POST | `/auth/api/user/logout-all` | Terminate all user sessions | Clears current host cookie | | DELETE | `/auth/api/user/session/{session_id}` | Terminate one session | Session IDs are server-issued | | DELETE | `/auth/api/user/credential/{uuid}` | Delete a credential | Requires recent authentication | | POST | `/auth/api/user/create-link` | Create a device-add link | Requires recent authentication | +These are used mostly from the user profile panel and modify the current user. + ### Admin API: `/auth/api/admin/*` -Normally only used via admin panel. +Normally only used via admin panel, requires auth admin permissions and can modify any users, orgs and permissions the session has access to. + +E.g. Org admin cannot see anything of the other orgs that he has no admin access to. Master admin `auth:admin` can see everything and create and manage orgs. ### WebSockets: `/auth/ws/*` | Path | Used for | Notes | |---|---|---| -| `WS /auth/ws/authenticate` | Passkey authentication | Returns a `session_token` | -| `WS /auth/ws/register` | Register a new credential | Optional query: `reset=`, `name=` | -| `WS /auth/ws/remote-auth/request` | Start a cross-device login/registration request | Returns a pairing code | -| `WS /auth/ws/remote-auth/permit` | Approve/deny a pairing code | Used from an already-authenticated device | +| `WS /auth/ws/authenticate` | Passkey authentication | Returns a session token | +| `WS /auth/ws/register` | Register a new credential | Adding another passkey to current user or via reset token | +| `WS /auth/ws/remote-auth/request` | Start a cross-device login/registration request | Used from unauthenticated client | +| `WS /auth/ws/remote-auth/permit` | Approve/deny a pairing code | Used to accept the request, if same words are entered | + +These are for internal use only, but are documented here because they are the core piece in all passkey operations. ### Auth host mode (`--auth-host`) -| Path / type | What happens on non-auth hosts | -|---|---| -| `/auth/api/*` | Served normally | -| `/auth/api/user/*` | 404 | -| `/auth/api/admin/*` | 404 | -| `/auth/ws/*` | 404 | +On the auth host: +- The Web UI is served at site root (e.g. admin UI at `/admin/`), and the `/auth/...` equivalents (e.g. `/auth/admin/`) redirect to the root paths. +- All of the API stays under `/auth/api/*` +- Auth WebSockets remain at `/auth/ws/*` but take connections from other hosts to issue sessions for each of those. -On the auth host itself some Web UI paths are made available at site root instead, but API stays in `/auth/api` and is fully accessible. +On non-auth hosts: +- `/auth/api/*` is served normally. +- `/auth/api/user/*`, `/auth/api/admin/*`, and `/auth/ws/*` don't exist. diff --git a/scripts/devserver.py b/scripts/devserver.py index f2955c9..5d16f73 100755 --- a/scripts/devserver.py +++ b/scripts/devserver.py @@ -118,7 +118,9 @@ def parse_endpoint( return host, port, None, False -def run_vite(vite_url: str, vite_host: str | None, vite_port: int, auth_host: str | None = None): +def run_vite( + vite_url: str, vite_host: str | None, vite_port: int, auth_host: str | None = None +): """Spawn the frontend dev server (deno, npm, or bunx) as a background process.""" devpath = Path(__file__).parent.parent / "frontend" if not (devpath / "package.json").exists(): @@ -163,7 +165,9 @@ def run_vite(vite_url: str, vite_host: str | None, vite_port: int, auth_host: st vite_env = os.environ.copy() if auth_host: vite_env["PASKIA_AUTH_HOST"] = auth_host - vite_process = subprocess.Popen(full_cmd, cwd=str(devpath), shell=False, env=vite_env) + vite_process = subprocess.Popen( + full_cmd, cwd=str(devpath), shell=False, env=vite_env + ) except Exception as e: stderr.write( f"┃ ⚠️ Vite couldn't start: {e}\n"