LeoVasanko/paskia
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Docs updates.

Browse Source
This commit is contained in:
LeoVasanko
2025-12-19 18:34:12 +00:00
parent 000501b718
commit 0bfb035f76
2 changed files with 27 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
API.md
+21 -16
View File
@@ -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=<token>`, `name=<display 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.
scripts/devserver.py
+6 -2
View File
@@ -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"