1260 lines
52 KiB
Markdown
1260 lines
52 KiB
Markdown
# Portal Authentication (Phase 1) Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Gate each project's read-only client portal behind a secure per-project link + shared password.
|
|
|
|
**Architecture:** Add `portal_enabled` / `portal_password_hash` / `portal_link_token` to `Project`. A new `/portal/p/{link_token}` page resolves the project from the (unguessable) token and prompts for the password; on success it mints the *existing* signed session cookie — pinned to a **dedicated 1:1 portal client** for that project — so every existing client-scoped read-only route (overview, location, live/history/events) works unchanged and is automatically scoped to that one project. The interim magic-link / open-link entry points are retired.
|
|
|
|
**Why reuse the client cookie instead of re-keying routes to "project":** the existing scoped-data layer (`get_current_client` → `_client_project_ids` → `resolve_client_location`) is battle-tested in prod. Giving each portal-enabled project its own dedicated `Client` (slug `portal-<project.id>`, owning exactly that one project) yields per-project isolation with **zero route surgery**. `Project.client_id` is left untouched as substrate for the deferred per-client rollup.
|
|
|
|
**Tech Stack:** FastAPI, SQLAlchemy 2 + SQLite (raw-`sqlite3` migrations, no Alembic), Jinja2, argon2-cffi (new), pytest + Starlette TestClient (new — no test harness exists yet). Docker: deps are baked into the image, so new deps require a rebuild.
|
|
|
|
**Key existing references (verbatim from codebase):**
|
|
- `backend/database.py`: `Base`, `SessionLocal`, `get_db` (generator dependency). SQLite at `data/seismo_fleet.db`.
|
|
- `backend/models.py`: `Project` (table `projects`, `id` is caller-supplied `str(uuid.uuid4())`, no FK constraints/relationships), `Client` (slug unique), `ClientAccessToken`.
|
|
- `backend/portal_auth.py`: `SECRET_KEY` (env, default `"dev-insecure-change-me"`), `COOKIE_NAME="portal_session"`, `COOKIE_MAX_AGE=60*60*24*30`, `make_session_cookie(token_id)` → `{"tid","iat"}` signed cookie, `client_from_cookie`, `get_current_client`, `ensure_project_client`, `provision_preview_session`, `mint_link_token`, `PortalAuthError`, `PORTAL_OPEN_LINKS`.
|
|
- `backend/routers/portal.py`: `APIRouter(prefix="/portal")`. Routes `/portal/enter/{token}`, `/portal/open/{project_id}`, `/portal/logout`, `/portal/access`, `/portal`, `/portal/location/{id}`, `/portal/api/location/{id}/{live,history,events,thresholds}`, WS `/stream`. Cookie set with `max_age=COOKIE_MAX_AGE, httponly=True, samesite="lax"`. Scope helpers `_client_project_ids`, `resolve_client_location`, `active_unit_for_location`, `_client_locations`.
|
|
- `backend/main.py`: `app.include_router(portal.router)`; `PortalAuthError` handler; operator routes `/projects/{id}/portal-preview`, `/projects/{id}/portal-link` (create/list/revoke); `project_detail_page` passes `portal_open_links` to `projects/detail.html`.
|
|
- `templates/portal/base.html`: blocks `title`/`head`/`content`/`scripts`; shows client chip + Sign-out when `client` context var is truthy; globals `esc()`, `cssVar()`. `templates/portal/access_required.html`: lock-card splash branching on `reason`.
|
|
- `templates/projects/detail.html`: breadcrumb buttons (lines 21-41) + share modal & JS (lines 2101-2219) — the operator portal-sharing UI to replace.
|
|
- `backend/migrate_add_client_portal.py`: the raw-`sqlite3`, idempotent `PRAGMA table_info` + `ALTER TABLE ADD COLUMN` migration pattern.
|
|
|
|
---
|
|
|
|
## Task 1: Stand up the test harness + add dependencies
|
|
|
|
**Files:**
|
|
- Modify: `requirements.txt`
|
|
- Create: `requirements-dev.txt`
|
|
- Create: `tests/__init__.py` (empty)
|
|
- Create: `tests/conftest.py`
|
|
- Create: `tests/test_harness.py` (sanity test, deleted at end of task)
|
|
|
|
- [ ] **Step 1: Add the runtime dependency (argon2)**
|
|
|
|
Append to `requirements.txt`:
|
|
```
|
|
argon2-cffi==23.1.0
|
|
```
|
|
|
|
- [ ] **Step 2: Create the dev/test dependency file**
|
|
|
|
Create `requirements-dev.txt`:
|
|
```
|
|
-r requirements.txt
|
|
pytest==8.3.3
|
|
```
|
|
|
|
- [ ] **Step 3: Create the test package + fixtures**
|
|
|
|
Create `tests/__init__.py` (empty file).
|
|
|
|
Create `tests/conftest.py`:
|
|
```python
|
|
"""Test harness: a throwaway SQLite DB per test, get_db overridden, a TestClient
|
|
that does NOT run lifespan startup (so schedulers/SLMM polling stay off)."""
|
|
import os
|
|
import uuid
|
|
import pytest
|
|
from datetime import datetime
|
|
from sqlalchemy import create_engine
|
|
from sqlalchemy.orm import sessionmaker
|
|
from starlette.testclient import TestClient
|
|
|
|
from backend.database import Base, get_db
|
|
import backend.models as models # noqa: F401 (ensure all tables are registered on Base)
|
|
|
|
|
|
@pytest.fixture()
|
|
def db_session(tmp_path):
|
|
db_file = tmp_path / "test.db"
|
|
engine = create_engine(f"sqlite:///{db_file}", connect_args={"check_same_thread": False})
|
|
Base.metadata.create_all(bind=engine)
|
|
TestingSession = sessionmaker(autocommit=False, autoflush=False, bind=engine)
|
|
sess = TestingSession()
|
|
try:
|
|
yield sess
|
|
finally:
|
|
sess.close()
|
|
engine.dispose()
|
|
|
|
|
|
@pytest.fixture()
|
|
def client(db_session):
|
|
from backend.main import app # imported lazily so module side effects are contained
|
|
def _override():
|
|
try:
|
|
yield db_session
|
|
finally:
|
|
pass
|
|
app.dependency_overrides[get_db] = _override
|
|
# No `with` → lifespan/startup events do not run (no scheduler/SLMM threads).
|
|
c = TestClient(app)
|
|
yield c
|
|
app.dependency_overrides.clear()
|
|
|
|
|
|
@pytest.fixture(autouse=True)
|
|
def _reset_portal_lockout():
|
|
"""Portal lockout state is a module-global dict; clear it between tests so
|
|
one test's failed attempts can't lock out another."""
|
|
try:
|
|
import backend.portal_auth as _pa
|
|
if hasattr(_pa, "_failures"):
|
|
_pa._failures.clear()
|
|
except Exception:
|
|
pass
|
|
yield
|
|
|
|
|
|
def make_project(db_session, name=None, **kwargs):
|
|
"""Insert and return a Project with a unique name."""
|
|
p = models.Project(
|
|
id=str(uuid.uuid4()),
|
|
name=name or f"Proj {uuid.uuid4().hex[:8]}",
|
|
status="active",
|
|
created_at=datetime.utcnow(),
|
|
**kwargs,
|
|
)
|
|
db_session.add(p)
|
|
db_session.commit()
|
|
return p
|
|
```
|
|
|
|
- [ ] **Step 4: Add a sanity test that proves the harness boots**
|
|
|
|
Create `tests/test_harness.py`:
|
|
```python
|
|
def test_app_boots_and_serves(client):
|
|
r = client.get("/portal/access")
|
|
assert r.status_code == 200
|
|
|
|
|
|
def test_make_project_persists(db_session):
|
|
from tests.conftest import make_project
|
|
p = make_project(db_session, name="Harness Co")
|
|
assert p.id and p.name == "Harness Co"
|
|
```
|
|
|
|
- [ ] **Step 5: Bind-mount the source into the dev container (one-time, so code is live)**
|
|
|
|
The dev container bakes source at build time (only `data-dev` is bind-mounted), so it won't pick up code edits — which would force a rebuild per TDD change. Fix it once by mounting the source. In `docker-compose.override.yml`, under the `terra-view` service `volumes:`, add a source mount **above** the existing data mount so the data mount still wins for `/app/data`:
|
|
|
|
```yaml
|
|
volumes:
|
|
- .:/app
|
|
- ./data-dev:/app/data
|
|
```
|
|
(Local dev-env convenience — does not need to be committed with the feature.)
|
|
|
|
- [ ] **Step 6: Rebuild (bakes argon2), recreate with the mount, install pytest, run the sanity test**
|
|
|
|
```bash
|
|
cd /home/serversdown/terra-view
|
|
docker compose build terra-view && docker compose up -d terra-view
|
|
docker exec terra-view-terra-view-1 pip install -r requirements-dev.txt
|
|
docker exec terra-view-terra-view-1 python -m pytest tests/test_harness.py -v
|
|
```
|
|
Expected: both tests PASS. With the source mounted, later tasks need **no rebuild** — `docker exec … pytest` sees your edits live. (`pip install` of pytest is ephemeral; re-run it only if you recreate the container.)
|
|
|
|
- [ ] **Step 7: Remove the throwaway sanity test and commit**
|
|
|
|
```bash
|
|
rm tests/test_harness.py
|
|
git add requirements.txt requirements-dev.txt tests/__init__.py tests/conftest.py
|
|
git commit -m "test: stand up pytest harness + add argon2-cffi"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 2: Password hashing helpers
|
|
|
|
**Files:**
|
|
- Create: `backend/auth_passwords.py`
|
|
- Test: `tests/test_auth_passwords.py`
|
|
|
|
- [ ] **Step 1: Write the failing tests**
|
|
|
|
Create `tests/test_auth_passwords.py`:
|
|
```python
|
|
import pytest
|
|
from backend.auth_passwords import hash_password, verify_password, generate_password
|
|
|
|
|
|
def test_hash_is_not_plaintext_and_verifies():
|
|
h = hash_password("hunter2")
|
|
assert h != "hunter2"
|
|
assert h.startswith("$argon2")
|
|
assert verify_password("hunter2", h) is True
|
|
|
|
|
|
def test_verify_rejects_wrong_password():
|
|
h = hash_password("hunter2")
|
|
assert verify_password("nope", h) is False
|
|
|
|
|
|
def test_verify_is_safe_on_garbage_hash():
|
|
assert verify_password("anything", "not-a-real-hash") is False
|
|
|
|
|
|
def test_generated_password_is_strong_and_unique():
|
|
a, b = generate_password(), generate_password()
|
|
assert a != b
|
|
assert len(a) >= 12
|
|
```
|
|
|
|
- [ ] **Step 2: Run to verify failure**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_auth_passwords.py -v`
|
|
Expected: FAIL (`ModuleNotFoundError: backend.auth_passwords`).
|
|
|
|
- [ ] **Step 3: Implement the helpers**
|
|
|
|
Create `backend/auth_passwords.py`:
|
|
```python
|
|
"""Password hashing for the client portal — argon2id via argon2-cffi.
|
|
|
|
Kept separate from portal_auth (cookie signing) so the future operator auth can
|
|
reuse the same hasher. Never store or log raw passwords."""
|
|
import secrets
|
|
from argon2 import PasswordHasher
|
|
from argon2.exceptions import VerifyMismatchError, VerificationError, InvalidHashError
|
|
|
|
_ph = PasswordHasher()
|
|
|
|
|
|
def hash_password(raw: str) -> str:
|
|
"""Return an argon2id hash string for a raw password."""
|
|
return _ph.hash(raw)
|
|
|
|
|
|
def verify_password(raw: str, hashed: str) -> bool:
|
|
"""True iff raw matches the stored hash. Never raises."""
|
|
try:
|
|
return _ph.verify(hashed, raw)
|
|
except (VerifyMismatchError, VerificationError, InvalidHashError, Exception):
|
|
return False
|
|
|
|
|
|
def generate_password(n_bytes: int = 12) -> str:
|
|
"""A strong, URL-safe shareable password (~16 chars for n_bytes=12)."""
|
|
return secrets.token_urlsafe(n_bytes)
|
|
```
|
|
|
|
- [ ] **Step 4: Run to verify pass**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_auth_passwords.py -v`
|
|
Expected: PASS (4 tests).
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add backend/auth_passwords.py tests/test_auth_passwords.py
|
|
git commit -m "feat: argon2 password hashing helpers for the portal"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 3: Project portal columns + migration
|
|
|
|
**Files:**
|
|
- Modify: `backend/models.py` (the `Project` class, after `client_id` ~`models.py:195`)
|
|
- Create: `backend/migrate_add_project_portal_auth.py`
|
|
- Test: `tests/test_portal_migration.py`
|
|
|
|
- [ ] **Step 1: Add the three columns to the `Project` model**
|
|
|
|
In `backend/models.py`, inside `class Project`, immediately after the `client_id` line, add:
|
|
```python
|
|
# --- Client portal (Phase 1: per-project link + password gate) ---
|
|
portal_enabled = Column(Boolean, default=False) # is the portal open for this project
|
|
portal_password_hash = Column(String, nullable=True) # argon2 hash of the shared password
|
|
portal_link_token = Column(String, nullable=True, unique=True, index=True) # unguessable token in the secure link
|
|
```
|
|
|
|
- [ ] **Step 2: Write the failing migration test**
|
|
|
|
Create `tests/test_portal_migration.py`:
|
|
```python
|
|
import sqlite3
|
|
import importlib
|
|
|
|
|
|
def _columns(db_file):
|
|
conn = sqlite3.connect(db_file)
|
|
cols = {r[1] for r in conn.execute("PRAGMA table_info(projects)")}
|
|
conn.close()
|
|
return cols
|
|
|
|
|
|
def test_migration_adds_columns_and_is_idempotent(tmp_path, monkeypatch):
|
|
db_file = tmp_path / "seismo_fleet.db"
|
|
conn = sqlite3.connect(db_file)
|
|
conn.execute("CREATE TABLE projects (id TEXT PRIMARY KEY, name TEXT)")
|
|
conn.commit()
|
|
conn.close()
|
|
|
|
monkeypatch.chdir(tmp_path) # migration resolves data/ relative to cwd
|
|
(tmp_path / "data").mkdir()
|
|
(tmp_path / "data" / "seismo_fleet.db").write_bytes(db_file.read_bytes())
|
|
|
|
mod = importlib.import_module("backend.migrate_add_project_portal_auth")
|
|
mod.migrate()
|
|
cols = _columns(tmp_path / "data" / "seismo_fleet.db")
|
|
assert {"portal_enabled", "portal_password_hash", "portal_link_token"} <= cols
|
|
|
|
mod.migrate() # second run must not raise
|
|
assert {"portal_enabled", "portal_password_hash", "portal_link_token"} <= _columns(tmp_path / "data" / "seismo_fleet.db")
|
|
```
|
|
|
|
- [ ] **Step 3: Run to verify failure**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_portal_migration.py -v`
|
|
Expected: FAIL (`ModuleNotFoundError: backend.migrate_add_project_portal_auth`).
|
|
|
|
- [ ] **Step 4: Write the migration (copy the `migrate_add_client_portal.py` pattern)**
|
|
|
|
Create `backend/migrate_add_project_portal_auth.py`:
|
|
```python
|
|
#!/usr/bin/env python3
|
|
"""
|
|
Database migration: Project portal auth (Phase 1).
|
|
|
|
Adds the per-project portal gate columns to `projects`:
|
|
- portal_enabled (BOOLEAN, default 0)
|
|
- portal_password_hash (TEXT, nullable)
|
|
- portal_link_token (TEXT, nullable) [+ unique index]
|
|
|
|
Idempotent. Run once per existing DB:
|
|
docker exec terra-view-terra-view-1 python3 backend/migrate_add_project_portal_auth.py
|
|
"""
|
|
import sqlite3
|
|
from pathlib import Path
|
|
|
|
_COLUMNS = {
|
|
"portal_enabled": "BOOLEAN DEFAULT 0",
|
|
"portal_password_hash": "TEXT",
|
|
"portal_link_token": "TEXT",
|
|
}
|
|
|
|
|
|
def migrate():
|
|
possible_paths = [Path("data/seismo_fleet.db"), Path("data/sfm.db"), Path("data/seismo.db")]
|
|
db_path = next((p for p in possible_paths if p.exists()), None)
|
|
if db_path is None:
|
|
print(f"Database not found in any of: {[str(p) for p in possible_paths]}")
|
|
print("A fresh DB created via models.py will include these columns automatically.")
|
|
return
|
|
|
|
print(f"Using database: {db_path}")
|
|
conn = sqlite3.connect(db_path)
|
|
cursor = conn.cursor()
|
|
cursor.execute("PRAGMA table_info(projects)")
|
|
existing = {row[1] for row in cursor.fetchall()}
|
|
|
|
for col, ddl in _COLUMNS.items():
|
|
if col in existing:
|
|
print(f"○ Column already exists: projects.{col}")
|
|
continue
|
|
try:
|
|
cursor.execute(f"ALTER TABLE projects ADD COLUMN {col} {ddl}")
|
|
print(f"✓ Added column: projects.{col} ({ddl})")
|
|
except sqlite3.OperationalError as e:
|
|
print(f"✗ Failed to add projects.{col}: {e}")
|
|
|
|
# Unique index on the link token (separate from ADD COLUMN; idempotent via IF NOT EXISTS).
|
|
try:
|
|
cursor.execute("CREATE UNIQUE INDEX IF NOT EXISTS ix_projects_portal_link_token "
|
|
"ON projects (portal_link_token)")
|
|
print("✓ Ensured unique index: ix_projects_portal_link_token")
|
|
except sqlite3.OperationalError as e:
|
|
print(f"✗ Failed to create index: {e}")
|
|
|
|
conn.commit()
|
|
conn.close()
|
|
print("\n✓ Project portal-auth migration complete.")
|
|
|
|
|
|
if __name__ == "__main__":
|
|
migrate()
|
|
```
|
|
|
|
- [ ] **Step 5: Run to verify pass**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_portal_migration.py -v`
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add backend/models.py backend/migrate_add_project_portal_auth.py tests/test_portal_migration.py
|
|
git commit -m "feat: add per-project portal gate columns + migration"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 4: Portal session-mint + link-token + lockout helpers
|
|
|
|
**Files:**
|
|
- Modify: `backend/portal_auth.py` (append new helpers + a lockout store)
|
|
- Test: `tests/test_portal_auth_helpers.py`
|
|
|
|
These build on the existing `ensure_project_client`-style pattern but pin a **dedicated 1:1 portal client** to the project, and add link-token resolution + an in-memory lockout.
|
|
|
|
- [ ] **Step 1: Write the failing tests**
|
|
|
|
Create `tests/test_portal_auth_helpers.py`:
|
|
```python
|
|
import time
|
|
from tests.conftest import make_project
|
|
from backend import portal_auth as pa
|
|
from backend.models import Client, ClientAccessToken
|
|
from backend.auth_passwords import hash_password
|
|
|
|
|
|
def test_portal_client_for_project_is_1to1_and_idempotent(db_session):
|
|
p = make_project(db_session)
|
|
c1 = pa.portal_client_for_project(p, db_session)
|
|
c2 = pa.portal_client_for_project(p, db_session)
|
|
assert isinstance(c1, Client) and c1.id == c2.id
|
|
assert c1.slug == f"portal-{p.id}"
|
|
# exactly one client row for this project
|
|
assert db_session.query(Client).filter_by(slug=f"portal-{p.id}").count() == 1
|
|
|
|
|
|
def test_mint_portal_session_returns_usable_token_id(db_session):
|
|
p = make_project(db_session)
|
|
tid = pa.mint_portal_session(p, db_session)
|
|
tok = db_session.query(ClientAccessToken).filter_by(id=tid, revoked_at=None).first()
|
|
assert tok is not None
|
|
# the cookie built from it resolves back to this project's portal client
|
|
cookie = pa.make_session_cookie(tid)
|
|
client = pa.client_from_cookie(cookie, db_session)
|
|
assert client is not None and client.slug == f"portal-{p.id}"
|
|
|
|
|
|
def test_resolve_project_by_link_token(db_session):
|
|
p = make_project(db_session, portal_enabled=True, portal_link_token="tok-abc")
|
|
assert pa.resolve_project_by_link_token("tok-abc", db_session).id == p.id
|
|
assert pa.resolve_project_by_link_token("nope", db_session) is None
|
|
|
|
|
|
def test_resolve_project_ignores_disabled_portal(db_session):
|
|
make_project(db_session, portal_enabled=False, portal_link_token="tok-off")
|
|
assert pa.resolve_project_by_link_token("tok-off", db_session) is None
|
|
|
|
|
|
def test_lockout_after_max_attempts():
|
|
pa.clear_failures("k1")
|
|
assert pa.is_locked("k1") is False
|
|
for _ in range(pa.MAX_ATTEMPTS):
|
|
pa.register_failure("k1")
|
|
assert pa.is_locked("k1") is True
|
|
pa.clear_failures("k1")
|
|
assert pa.is_locked("k1") is False
|
|
```
|
|
|
|
- [ ] **Step 2: Run to verify failure**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_portal_auth_helpers.py -v`
|
|
Expected: FAIL (`AttributeError: module 'backend.portal_auth' has no attribute 'portal_client_for_project'`).
|
|
|
|
- [ ] **Step 3: Append the helpers to `backend/portal_auth.py`**
|
|
|
|
Add at the end of `backend/portal_auth.py`:
|
|
```python
|
|
# --- Phase-1 per-project password gate -------------------------------------------
|
|
# A portal-enabled project gets its OWN dedicated client (slug "portal-<project.id>")
|
|
# owning exactly that project, so the existing client-scoped routes are automatically
|
|
# per-project. Project.client_id is left untouched (deferred per-client rollup).
|
|
|
|
from backend.models import Project # local import; Project not needed above
|
|
|
|
|
|
def portal_client_for_project(project, db) -> Client:
|
|
"""Get-or-create the dedicated 1:1 portal client for a project."""
|
|
slug = f"portal-{project.id}"
|
|
client = db.query(Client).filter_by(slug=slug).first()
|
|
if client is None:
|
|
client = Client(id=str(uuid.uuid4()),
|
|
name=(project.client_name or project.name or "Client"),
|
|
slug=slug, active=True)
|
|
db.add(client)
|
|
db.flush()
|
|
return client
|
|
|
|
|
|
def mint_portal_session(project, db) -> str:
|
|
"""Ensure the project's portal client + an access token exist; return the token
|
|
id to seal into a session cookie. Reuses an existing token to avoid clutter."""
|
|
client = portal_client_for_project(project, db)
|
|
tok = db.query(ClientAccessToken).filter_by(client_id=client.id, revoked_at=None).first()
|
|
if tok is None:
|
|
tok = ClientAccessToken(id=str(uuid.uuid4()), client_id=client.id,
|
|
token_hash=hash_token(secrets.token_urlsafe(32)),
|
|
label="portal")
|
|
db.add(tok)
|
|
db.commit()
|
|
return tok.id
|
|
|
|
|
|
def resolve_project_by_link_token(link_token: str, db):
|
|
"""Return the portal-enabled Project for a link token, or None."""
|
|
if not link_token:
|
|
return None
|
|
return db.query(Project).filter_by(
|
|
portal_link_token=link_token, portal_enabled=True).first()
|
|
|
|
|
|
# In-memory brute-force lockout (per link_token+IP). Resets on restart; adequate for
|
|
# a read-only surface behind the UniFi edge. Single-worker dev; note multi-worker
|
|
# would need a shared store.
|
|
MAX_ATTEMPTS = 5
|
|
LOCK_SECONDS = 15 * 60
|
|
_failures: dict = {} # key -> (count, first_failure_epoch)
|
|
|
|
|
|
def is_locked(key: str) -> bool:
|
|
rec = _failures.get(key)
|
|
if not rec:
|
|
return False
|
|
count, first = rec
|
|
if count < MAX_ATTEMPTS:
|
|
return False
|
|
if (time.time() - first) > LOCK_SECONDS:
|
|
_failures.pop(key, None) # window expired
|
|
return False
|
|
return True
|
|
|
|
|
|
def register_failure(key: str) -> None:
|
|
count, first = _failures.get(key, (0, time.time()))
|
|
_failures[key] = (count + 1, first)
|
|
|
|
|
|
def clear_failures(key: str) -> None:
|
|
_failures.pop(key, None)
|
|
```
|
|
|
|
Note: `hash_token`, `secrets`, `uuid`, `time`, `Client`, `ClientAccessToken` are already imported at the top of `portal_auth.py`.
|
|
|
|
- [ ] **Step 4: Run to verify pass**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_portal_auth_helpers.py -v`
|
|
Expected: PASS (5 tests).
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add backend/portal_auth.py tests/test_portal_auth_helpers.py
|
|
git commit -m "feat: per-project portal session mint + link-token resolve + lockout"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 5: The password-gate page + the password prompt template
|
|
|
|
**Files:**
|
|
- Create: `templates/portal/password.html`
|
|
- Modify: `backend/routers/portal.py` (add GET + POST `/portal/p/{link_token}`; import `Form`, the new helpers, `verify_password`)
|
|
- Test: `tests/test_portal_gate.py`
|
|
|
|
- [ ] **Step 1: Create the password prompt template**
|
|
|
|
Create `templates/portal/password.html`:
|
|
```jinja
|
|
{% extends "portal/base.html" %}
|
|
{% block title %}{{ project_name }}{% endblock %}
|
|
{% block content %}
|
|
<div class="max-w-md mx-auto mt-20 text-center reveal">
|
|
<div class="panel inline-flex items-center justify-center w-16 h-16 rounded-2xl mb-6">
|
|
<svg class="w-7 h-7 text-[var(--text-dim)]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
|
|
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5"
|
|
d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"></path>
|
|
</svg>
|
|
</div>
|
|
<h1 class="text-2xl font-bold tracking-tight mb-1">{{ project_name }}</h1>
|
|
<p class="text-[var(--text-dim)] text-sm mb-6">Enter the password to view this monitoring portal.</p>
|
|
{% if error %}
|
|
<p class="text-[var(--lvl-bad)] text-sm mb-4">{{ error }}</p>
|
|
{% endif %}
|
|
<form method="post" action="/portal/p/{{ link_token }}" class="panel p-5 text-left">
|
|
<label class="block text-xs text-[var(--text-dim)] mb-1" for="password">Password</label>
|
|
<input id="password" name="password" type="password" autofocus required
|
|
class="w-full px-3 py-2 rounded-lg border border-[var(--border)] bg-[var(--panel-b)] text-[var(--text)] mb-4">
|
|
<button type="submit"
|
|
class="w-full px-4 py-2 rounded-lg bg-seismo-orange text-white font-medium hover:opacity-90">
|
|
View portal
|
|
</button>
|
|
</form>
|
|
</div>
|
|
{% endblock %}
|
|
```
|
|
|
|
- [ ] **Step 2: Write the failing route tests**
|
|
|
|
Create `tests/test_portal_gate.py`:
|
|
```python
|
|
from tests.conftest import make_project
|
|
from backend import portal_auth as pa
|
|
from backend.auth_passwords import hash_password
|
|
|
|
|
|
def _enabled_project(db_session, token="tok-1", password="secretpw"):
|
|
return make_project(db_session, portal_enabled=True, portal_link_token=token,
|
|
portal_password_hash=hash_password(password))
|
|
|
|
|
|
def test_get_prompt_renders_for_valid_token(client, db_session):
|
|
_enabled_project(db_session)
|
|
r = client.get("/portal/p/tok-1")
|
|
assert r.status_code == 200
|
|
assert "password" in r.text.lower()
|
|
|
|
|
|
def test_get_unknown_token_shows_generic_page(client, db_session):
|
|
r = client.get("/portal/p/does-not-exist")
|
|
assert r.status_code in (403, 404)
|
|
assert "password" not in r.text.lower() or "isn't valid" in r.text.lower()
|
|
|
|
|
|
def test_wrong_password_is_rejected(client, db_session):
|
|
_enabled_project(db_session, password="rightpw")
|
|
r = client.post("/portal/p/tok-1", data={"password": "wrongpw"}, follow_redirects=False)
|
|
assert r.status_code == 200 # re-renders the form, no cookie
|
|
assert "portal_session" not in r.headers.get("set-cookie", "")
|
|
|
|
|
|
def test_correct_password_sets_cookie_and_redirects(client, db_session):
|
|
_enabled_project(db_session, password="rightpw")
|
|
r = client.post("/portal/p/tok-1", data={"password": "rightpw"}, follow_redirects=False)
|
|
assert r.status_code == 303
|
|
assert r.headers["location"] == "/portal"
|
|
assert "portal_session=" in r.headers.get("set-cookie", "")
|
|
|
|
|
|
def test_lockout_after_five_wrong(client, db_session):
|
|
_enabled_project(db_session, token="tok-lock", password="rightpw")
|
|
for _ in range(5):
|
|
client.post("/portal/p/tok-lock", data={"password": "x"}, follow_redirects=False)
|
|
# 6th attempt — even the CORRECT password is refused while locked
|
|
r = client.post("/portal/p/tok-lock", data={"password": "rightpw"}, follow_redirects=False)
|
|
assert r.status_code == 200
|
|
assert "portal_session=" not in r.headers.get("set-cookie", "")
|
|
assert "too many" in r.text.lower()
|
|
```
|
|
|
|
- [ ] **Step 3: Run to verify failure**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_portal_gate.py -v`
|
|
Expected: FAIL (404 — routes not defined).
|
|
|
|
- [ ] **Step 4: Add the routes to `backend/routers/portal.py`**
|
|
|
|
Update the imports block in `backend/routers/portal.py`:
|
|
```python
|
|
from fastapi import APIRouter, Request, Depends, HTTPException, WebSocket, Form
|
|
```
|
|
and extend the `backend.portal_auth` import to add the new helpers:
|
|
```python
|
|
from backend.portal_auth import (
|
|
get_current_client, client_from_cookie, make_session_cookie, resolve_token,
|
|
provision_preview_session, PORTAL_OPEN_LINKS,
|
|
COOKIE_NAME, COOKIE_MAX_AGE,
|
|
resolve_project_by_link_token, mint_portal_session,
|
|
is_locked, register_failure, clear_failures,
|
|
)
|
|
from backend.auth_passwords import verify_password
|
|
```
|
|
|
|
Add these two routes (place them just after the existing `/portal/access` handler):
|
|
```python
|
|
@router.get("/p/{link_token}")
|
|
def portal_password_prompt(link_token: str, request: Request, db: Session = Depends(get_db)):
|
|
"""Secure per-project link: resolve the project from the token, prompt for the
|
|
shared password. Generic page if the token is unknown/disabled (no leak)."""
|
|
project = resolve_project_by_link_token(link_token, db)
|
|
if not project:
|
|
return templates.TemplateResponse(
|
|
"portal/access_required.html", {"request": request, "reason": "invalid"},
|
|
status_code=404)
|
|
return templates.TemplateResponse("portal/password.html", {
|
|
"request": request, "link_token": link_token,
|
|
"project_name": project.name, "error": None})
|
|
|
|
|
|
@router.post("/p/{link_token}")
|
|
def portal_password_submit(link_token: str, request: Request,
|
|
password: str = Form(...), db: Session = Depends(get_db)):
|
|
"""Verify the shared password; on success mint a project-scoped session cookie."""
|
|
project = resolve_project_by_link_token(link_token, db)
|
|
if not project:
|
|
return templates.TemplateResponse(
|
|
"portal/access_required.html", {"request": request, "reason": "invalid"},
|
|
status_code=404)
|
|
|
|
lock_key = f"{link_token}:{request.client.host if request.client else '?'}"
|
|
if is_locked(lock_key):
|
|
return templates.TemplateResponse("portal/password.html", {
|
|
"request": request, "link_token": link_token, "project_name": project.name,
|
|
"error": "Too many attempts. Try again in 15 minutes."}, status_code=200)
|
|
|
|
if not project.portal_password_hash or not verify_password(password, project.portal_password_hash):
|
|
register_failure(lock_key)
|
|
return templates.TemplateResponse("portal/password.html", {
|
|
"request": request, "link_token": link_token, "project_name": project.name,
|
|
"error": "Incorrect password."}, status_code=200)
|
|
|
|
clear_failures(lock_key)
|
|
token_id = mint_portal_session(project, db)
|
|
resp = RedirectResponse(url="/portal", status_code=303)
|
|
resp.set_cookie(COOKIE_NAME, make_session_cookie(token_id),
|
|
max_age=COOKIE_MAX_AGE, httponly=True, samesite="lax")
|
|
logger.info(f"[PORTAL] password ok for project {project.id[:8]} → session opened")
|
|
return resp
|
|
```
|
|
|
|
- [ ] **Step 5: Run to verify pass**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_portal_gate.py -v`
|
|
Expected: PASS (5 tests). (If a prior test left lock state, restart the container or run the file in isolation — lockout state is module-global by design.)
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add templates/portal/password.html backend/routers/portal.py tests/test_portal_gate.py
|
|
git commit -m "feat: per-project portal password gate (/portal/p/{token}) + lockout"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 6: Per-project scope isolation test
|
|
|
|
**Files:**
|
|
- Test: `tests/test_portal_scope.py`
|
|
|
|
Proves a session minted for project A cannot read project B's location.
|
|
|
|
- [ ] **Step 1: Write the test**
|
|
|
|
Create `tests/test_portal_scope.py`:
|
|
```python
|
|
import uuid
|
|
from datetime import datetime
|
|
from tests.conftest import make_project
|
|
from backend import portal_auth as pa
|
|
from backend.auth_passwords import hash_password
|
|
from backend.models import MonitoringLocation
|
|
|
|
|
|
def _sound_location(db_session, project):
|
|
loc = MonitoringLocation(
|
|
id=str(uuid.uuid4()), project_id=project.id, name="Site",
|
|
location_type="sound", created_at=datetime.utcnow())
|
|
db_session.add(loc)
|
|
db_session.commit()
|
|
return loc
|
|
|
|
|
|
def test_session_for_A_cannot_open_B_location(client, db_session):
|
|
a = make_project(db_session, portal_enabled=True, portal_link_token="ta",
|
|
portal_password_hash=hash_password("pw"))
|
|
b = make_project(db_session)
|
|
b_loc = _sound_location(db_session, b)
|
|
|
|
# Establish an A session
|
|
r = client.post("/portal/p/ta", data={"password": "pw"}, follow_redirects=False)
|
|
assert r.status_code == 303
|
|
|
|
# Try to open B's location page → 404 (not 403), no leak
|
|
r2 = client.get(f"/portal/location/{b_loc.id}")
|
|
assert r2.status_code == 404
|
|
```
|
|
|
|
Note: confirm `MonitoringLocation`'s required columns by checking `backend/models.py`; add any `nullable=False` fields the constructor needs (e.g. `sort_order` defaults). If the model requires extra non-null fields, set them in `_sound_location`.
|
|
|
|
- [ ] **Step 2: Run to verify pass (behavior already implemented by `resolve_client_location`)**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_portal_scope.py -v`
|
|
Expected: PASS. (If it fails on a missing non-null column, fix `_sound_location` per the note, not the app.)
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add tests/test_portal_scope.py
|
|
git commit -m "test: portal session is isolated to its own project (404 on others)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 7: Operator "Portal access" endpoints
|
|
|
|
**Files:**
|
|
- Modify: `backend/main.py` (add 4 routes near the existing `/projects/{id}/portal-*` routes ~`main.py:417-487`)
|
|
- Test: `tests/test_portal_access_admin.py`
|
|
|
|
- [ ] **Step 1: Write the failing tests**
|
|
|
|
Create `tests/test_portal_access_admin.py`:
|
|
```python
|
|
from tests.conftest import make_project
|
|
from backend.models import Project
|
|
|
|
|
|
def test_enable_creates_link_token_and_reports_state(client, db_session):
|
|
p = make_project(db_session)
|
|
r = client.post(f"/projects/{p.id}/portal-access/enable")
|
|
assert r.status_code == 200
|
|
body = r.json()
|
|
assert body["enabled"] is True
|
|
assert body["link_url"].endswith(f"/portal/p/{db_session.get(Project, p.id).portal_link_token}")
|
|
|
|
|
|
def test_set_password_returns_raw_once_and_stores_hash(client, db_session):
|
|
p = make_project(db_session)
|
|
client.post(f"/projects/{p.id}/portal-access/enable")
|
|
r = client.post(f"/projects/{p.id}/portal-access/password")
|
|
assert r.status_code == 200
|
|
raw = r.json()["password"]
|
|
assert len(raw) >= 12
|
|
fresh = db_session.get(Project, p.id)
|
|
assert fresh.portal_password_hash and fresh.portal_password_hash != raw
|
|
|
|
|
|
def test_disable_turns_off_and_rotates_token(client, db_session):
|
|
p = make_project(db_session)
|
|
client.post(f"/projects/{p.id}/portal-access/enable")
|
|
old = db_session.get(Project, p.id).portal_link_token
|
|
r = client.post(f"/projects/{p.id}/portal-access/disable")
|
|
assert r.status_code == 200
|
|
fresh = db_session.get(Project, p.id)
|
|
assert fresh.portal_enabled is False
|
|
assert fresh.portal_link_token != old
|
|
|
|
|
|
def test_get_state(client, db_session):
|
|
p = make_project(db_session)
|
|
r = client.get(f"/projects/{p.id}/portal-access")
|
|
assert r.status_code == 200
|
|
assert r.json() == {"enabled": False, "has_password": False, "link_url": None}
|
|
```
|
|
|
|
- [ ] **Step 2: Run to verify failure**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_portal_access_admin.py -v`
|
|
Expected: FAIL (404).
|
|
|
|
- [ ] **Step 3: Implement the four routes in `backend/main.py`**
|
|
|
|
Add after the existing `/projects/{project_id}/portal-link/{token_id}/revoke` route (~`main.py:487`):
|
|
```python
|
|
@app.get("/projects/{project_id}/portal-access")
|
|
async def project_portal_access_state(project_id: str, request: Request, db: Session = Depends(get_db)):
|
|
"""Current portal-access state for the operator panel."""
|
|
from backend.models import Project
|
|
p = db.query(Project).filter_by(id=project_id).first()
|
|
if not p:
|
|
return JSONResponse(status_code=404, content={"detail": "Project not found"})
|
|
link_url = (str(request.base_url).rstrip("/") + f"/portal/p/{p.portal_link_token}") \
|
|
if (p.portal_enabled and p.portal_link_token) else None
|
|
return {"enabled": bool(p.portal_enabled), "has_password": bool(p.portal_password_hash),
|
|
"link_url": link_url}
|
|
|
|
|
|
@app.post("/projects/{project_id}/portal-access/enable")
|
|
async def project_portal_access_enable(project_id: str, request: Request, db: Session = Depends(get_db)):
|
|
"""Turn the portal on; mint a link token if one doesn't exist yet."""
|
|
import secrets
|
|
from backend.models import Project
|
|
p = db.query(Project).filter_by(id=project_id).first()
|
|
if not p:
|
|
return JSONResponse(status_code=404, content={"detail": "Project not found"})
|
|
if not p.portal_link_token:
|
|
p.portal_link_token = secrets.token_urlsafe(24)
|
|
p.portal_enabled = True
|
|
db.commit()
|
|
link_url = str(request.base_url).rstrip("/") + f"/portal/p/{p.portal_link_token}"
|
|
return {"enabled": True, "has_password": bool(p.portal_password_hash), "link_url": link_url}
|
|
|
|
|
|
@app.post("/projects/{project_id}/portal-access/password")
|
|
async def project_portal_access_password(project_id: str, db: Session = Depends(get_db)):
|
|
"""Generate a fresh strong password, store its hash, return the raw once."""
|
|
from backend.models import Project
|
|
from backend.auth_passwords import hash_password, generate_password
|
|
p = db.query(Project).filter_by(id=project_id).first()
|
|
if not p:
|
|
return JSONResponse(status_code=404, content={"detail": "Project not found"})
|
|
raw = generate_password()
|
|
p.portal_password_hash = hash_password(raw)
|
|
db.commit()
|
|
return {"password": raw}
|
|
|
|
|
|
@app.post("/projects/{project_id}/portal-access/disable")
|
|
async def project_portal_access_disable(project_id: str, db: Session = Depends(get_db)):
|
|
"""Turn the portal off and rotate the link token (kills the old link)."""
|
|
import secrets
|
|
from backend.models import Project
|
|
p = db.query(Project).filter_by(id=project_id).first()
|
|
if not p:
|
|
return JSONResponse(status_code=404, content={"detail": "Project not found"})
|
|
p.portal_enabled = False
|
|
p.portal_link_token = secrets.token_urlsafe(24) # rotate so the old link 404s
|
|
db.commit()
|
|
return {"enabled": False}
|
|
```
|
|
|
|
- [ ] **Step 4: Run to verify pass**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_portal_access_admin.py -v`
|
|
Expected: PASS (4 tests).
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add backend/main.py tests/test_portal_access_admin.py
|
|
git commit -m "feat: operator portal-access endpoints (enable/password/disable/state)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 8: Operator "Portal access" panel (replace the share modal)
|
|
|
|
**Files:**
|
|
- Modify: `templates/projects/detail.html` (replace breadcrumb buttons lines 21-41 and the share modal + JS lines 2101-2219)
|
|
|
|
This is a UI task — verify manually in the browser.
|
|
|
|
- [ ] **Step 1: Replace the breadcrumb buttons (lines 21-41)**
|
|
|
|
Replace the whole `<!-- Client portal actions for this project -->` block (lines 21-41) with:
|
|
```html
|
|
<!-- Client portal access for this project -->
|
|
<div class="shrink-0 flex items-center gap-2">
|
|
<button type="button" onclick="openPortalAccess()"
|
|
class="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg border border-slate-600 bg-slate-700/40 text-gray-200 hover:bg-slate-700 transition-colors"
|
|
title="Manage this project's client portal access">
|
|
<svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
|
|
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
|
|
d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"></path>
|
|
</svg>
|
|
Portal access
|
|
</button>
|
|
<a href="/projects/{{ project_id }}/portal-preview" target="_blank" rel="noopener"
|
|
class="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg border border-seismo-orange/40 bg-seismo-orange/10 text-seismo-orange hover:bg-seismo-orange/20 transition-colors"
|
|
title="Preview this project's client portal in a new tab">
|
|
<svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
|
|
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"></path>
|
|
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M2.458 12C3.732 7.943 7.523 5 12 5c4.478 0 8.268 2.943 9.542 7-1.274 4.057-5.064 7-9.542 7-4.477 0-8.268-2.943-9.542-7z"></path>
|
|
</svg>
|
|
Preview
|
|
</a>
|
|
</div>
|
|
```
|
|
|
|
- [ ] **Step 2: Replace the share modal + JS (lines 2101-2219)**
|
|
|
|
Replace the entire `<!-- Share client portal link modal -->` block and its `<script>` (lines 2101-2219, ending just before `{% endblock %}`) with:
|
|
```html
|
|
<!-- Portal access modal -->
|
|
<div id="portal-access-modal" class="hidden fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4"
|
|
onclick="if(event.target===this)closePortalAccess()">
|
|
<div class="bg-white dark:bg-slate-800 rounded-xl shadow-xl w-full max-w-lg p-6">
|
|
<div class="flex items-center justify-between mb-1">
|
|
<h3 class="text-lg font-semibold text-gray-900 dark:text-white">Client portal access</h3>
|
|
<button onclick="closePortalAccess()" class="text-gray-400 hover:text-gray-600 dark:hover:text-gray-200">
|
|
<svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"/></svg>
|
|
</button>
|
|
</div>
|
|
<p class="text-sm text-gray-500 dark:text-gray-400 mb-4">
|
|
Send the client the link <em>and</em> the password. Read-only. Disabling rotates the link.
|
|
</p>
|
|
|
|
<div class="flex items-center justify-between mb-4">
|
|
<span class="text-sm font-medium text-gray-700 dark:text-gray-200">Portal enabled</span>
|
|
<button id="pa-toggle" onclick="togglePortalEnabled()"
|
|
class="px-3 py-1.5 text-sm rounded-lg border border-slate-300 dark:border-slate-600">…</button>
|
|
</div>
|
|
|
|
<div id="pa-details" class="hidden space-y-4">
|
|
<div>
|
|
<label class="block text-xs text-gray-500 dark:text-gray-400 mb-1">Portal link</label>
|
|
<div class="flex gap-2">
|
|
<input id="pa-link" readonly class="flex-1 px-3 py-2 text-sm rounded-lg border border-slate-300 dark:border-slate-600 bg-gray-50 dark:bg-slate-900 text-gray-800 dark:text-gray-200" />
|
|
<button onclick="copyField('pa-link', this)" class="px-3 py-2 text-sm rounded-lg bg-seismo-orange text-white hover:bg-orange-600">Copy</button>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<label class="block text-xs text-gray-500 dark:text-gray-400 mb-1">Password</label>
|
|
<div class="flex gap-2">
|
|
<input id="pa-pass" readonly placeholder="•••••••• (set one below)"
|
|
class="flex-1 px-3 py-2 text-sm rounded-lg border border-slate-300 dark:border-slate-600 bg-gray-50 dark:bg-slate-900 text-gray-800 dark:text-gray-200" />
|
|
<button onclick="copyField('pa-pass', this)" class="px-3 py-2 text-sm rounded-lg bg-seismo-orange text-white hover:bg-orange-600">Copy</button>
|
|
</div>
|
|
<button onclick="regeneratePassword()" class="mt-2 text-sm text-seismo-orange hover:text-seismo-navy font-medium">↻ Generate new password</button>
|
|
<p class="text-xs text-gray-400 mt-1">Shown once — copy it now. Regenerating invalidates the old one.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<script>
|
|
const PA_PROJECT_ID = "{{ project_id }}";
|
|
function openPortalAccess() { document.getElementById('portal-access-modal').classList.remove('hidden'); loadPortalAccess(); }
|
|
function closePortalAccess() { document.getElementById('portal-access-modal').classList.add('hidden'); }
|
|
|
|
function copyField(id, btn) {
|
|
const inp = document.getElementById(id); inp.select();
|
|
const done = () => { btn.textContent = 'Copied!'; setTimeout(() => btn.textContent = 'Copy', 1500); };
|
|
if (navigator.clipboard) navigator.clipboard.writeText(inp.value).then(done).catch(() => { document.execCommand('copy'); done(); });
|
|
else { document.execCommand('copy'); done(); }
|
|
}
|
|
|
|
async function loadPortalAccess() {
|
|
const j = await (await fetch(`/projects/${PA_PROJECT_ID}/portal-access`)).json();
|
|
renderPortalAccess(j);
|
|
}
|
|
function renderPortalAccess(j) {
|
|
const toggle = document.getElementById('pa-toggle');
|
|
const details = document.getElementById('pa-details');
|
|
toggle.textContent = j.enabled ? 'On — click to disable' : 'Off — click to enable';
|
|
toggle.className = 'px-3 py-1.5 text-sm rounded-lg border ' +
|
|
(j.enabled ? 'border-green-500 text-green-600 dark:text-green-400' : 'border-slate-300 dark:border-slate-600');
|
|
details.classList.toggle('hidden', !j.enabled);
|
|
if (j.enabled && j.link_url) document.getElementById('pa-link').value = j.link_url;
|
|
}
|
|
async function togglePortalEnabled() {
|
|
const on = document.getElementById('pa-toggle').textContent.startsWith('On');
|
|
const j = await (await fetch(`/projects/${PA_PROJECT_ID}/portal-access/${on ? 'disable' : 'enable'}`, { method: 'POST' })).json();
|
|
if (on) renderPortalAccess({ enabled: false, link_url: null });
|
|
else renderPortalAccess(j);
|
|
}
|
|
async function regeneratePassword() {
|
|
const j = await (await fetch(`/projects/${PA_PROJECT_ID}/portal-access/password`, { method: 'POST' })).json();
|
|
if (j.password) { const f = document.getElementById('pa-pass'); f.value = j.password; f.placeholder = ''; }
|
|
}
|
|
</script>
|
|
{% endblock %}
|
|
```
|
|
|
|
- [ ] **Step 3: Verify manually in the browser**
|
|
|
|
```bash
|
|
docker compose restart terra-view
|
|
```
|
|
Then open `http://localhost:1001/projects/<a-real-project-id>`, click **Portal access**:
|
|
- Toggle On → a link appears.
|
|
- Generate new password → a password appears.
|
|
- Copy buttons work.
|
|
- Open the link in a private window → password prompt → enter the generated password → lands on the project's read-only portal.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add templates/projects/detail.html
|
|
git commit -m "feat: operator Portal access panel (enable + password + link)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 9: Retire the interim magic-link / open-link entry points
|
|
|
|
**Files:**
|
|
- Modify: `backend/routers/portal.py` (remove `/portal/enter/{token}`, `/portal/open/{project_id}`)
|
|
- Modify: `backend/main.py` (remove `/projects/{id}/portal-link` create/list/revoke; repoint `/projects/{id}/portal-preview` to `mint_portal_session`; drop the `portal_open_links` template arg)
|
|
- Modify: `backend/portal_auth.py` (remove `PORTAL_OPEN_LINKS` + its warning)
|
|
- Test: `tests/test_retired_routes.py`
|
|
|
|
- [ ] **Step 1: Write the failing test (routes should be gone / preview still works)**
|
|
|
|
Create `tests/test_retired_routes.py`:
|
|
```python
|
|
from tests.conftest import make_project
|
|
|
|
|
|
def test_enter_and_open_are_gone(client, db_session):
|
|
assert client.get("/portal/enter/anything", follow_redirects=False).status_code == 404
|
|
assert client.get("/portal/open/anything", follow_redirects=False).status_code == 404
|
|
|
|
|
|
def test_portal_link_endpoints_are_gone(client, db_session):
|
|
p = make_project(db_session)
|
|
assert client.post(f"/projects/{p.id}/portal-link").status_code == 404
|
|
assert client.get(f"/projects/{p.id}/portal-links").status_code == 404
|
|
|
|
|
|
def test_preview_still_mints_a_session(client, db_session):
|
|
p = make_project(db_session)
|
|
r = client.get(f"/projects/{p.id}/portal-preview", follow_redirects=False)
|
|
assert r.status_code == 303
|
|
assert "portal_session=" in r.headers.get("set-cookie", "")
|
|
```
|
|
|
|
- [ ] **Step 2: Run to verify failure**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_retired_routes.py -v`
|
|
Expected: FAIL (the old routes still answer 200/303).
|
|
|
|
- [ ] **Step 3: Remove `/portal/enter/{token}` and `/portal/open/{project_id}` from `backend/routers/portal.py`**
|
|
|
|
Delete both route functions (`portal_enter` at `portal.py:94-110` and `portal_open` at `portal.py:113-132`). From the `backend.portal_auth` import line in `portal.py`, remove the now-unused `resolve_token`, `provision_preview_session`, `PORTAL_OPEN_LINKS` names (keep `make_session_cookie`, `mint_portal_session`, etc.).
|
|
|
|
- [ ] **Step 4: Update `backend/main.py`**
|
|
|
|
- Delete the three routes `project_portal_link_create`, `project_portal_links_list`, `project_portal_link_revoke` (`main.py:436-487`).
|
|
- In `project_portal_preview` (`main.py:417-433`), change the body to use the new mint helper:
|
|
```python
|
|
@app.get("/projects/{project_id}/portal-preview")
|
|
async def project_portal_preview(project_id: str, db: Session = Depends(get_db)):
|
|
"""Operator testing shortcut: open this project's client portal (no CLI)."""
|
|
from backend.models import Project
|
|
from backend.portal_auth import mint_portal_session, make_session_cookie, COOKIE_NAME, COOKIE_MAX_AGE
|
|
project = db.query(Project).filter_by(id=project_id).first()
|
|
if not project:
|
|
return JSONResponse(status_code=404, content={"detail": "Project not found"})
|
|
token_id = mint_portal_session(project, db)
|
|
resp = RedirectResponse(url="/portal", status_code=303)
|
|
resp.set_cookie(COOKIE_NAME, make_session_cookie(token_id),
|
|
max_age=COOKIE_MAX_AGE, httponly=True, samesite="lax")
|
|
return resp
|
|
```
|
|
- In `project_detail_page` (`main.py:407-414`), remove the `"portal_open_links": PORTAL_OPEN_LINKS,` context line.
|
|
- In the imports (`main.py:72`), change `from backend.portal_auth import PortalAuthError, PORTAL_OPEN_LINKS` to `from backend.portal_auth import PortalAuthError`.
|
|
|
|
- [ ] **Step 5: Remove `PORTAL_OPEN_LINKS` from `backend/portal_auth.py`**
|
|
|
|
Delete the `PORTAL_OPEN_LINKS = ...` assignment and its `if PORTAL_OPEN_LINKS: logger.warning(...)` block (`portal_auth.py:43-50`).
|
|
|
|
- [ ] **Step 6: Run to verify pass + full suite green**
|
|
|
|
```bash
|
|
docker exec terra-view-terra-view-1 python -m pytest tests/ -v
|
|
```
|
|
Expected: all tests PASS (including `test_retired_routes.py`). Fix any import errors surfaced by the removals.
|
|
|
|
- [ ] **Step 7: Commit**
|
|
|
|
```bash
|
|
git add backend/routers/portal.py backend/main.py backend/portal_auth.py tests/test_retired_routes.py
|
|
git commit -m "refactor: retire interim magic-link/open-link in favor of password gate"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 10: Harden the session cookie (Secure flag, env-driven)
|
|
|
|
**Files:**
|
|
- Modify: `backend/portal_auth.py` (add `COOKIE_SECURE`)
|
|
- Modify: `backend/routers/portal.py` + `backend/main.py` (pass `secure=COOKIE_SECURE` at the cookie set sites)
|
|
- Test: `tests/test_cookie_secure.py`
|
|
|
|
- [ ] **Step 1: Add the flag to `backend/portal_auth.py`**
|
|
|
|
Near `COOKIE_NAME`/`COOKIE_MAX_AGE`, add:
|
|
```python
|
|
# Set COOKIE_SECURE=true once the portal is served over HTTPS (TLS terminates at
|
|
# the Synology reverse proxy). Default false so plain-HTTP dev still works.
|
|
COOKIE_SECURE = os.getenv("COOKIE_SECURE", "false").lower() in ("1", "true", "yes")
|
|
```
|
|
|
|
- [ ] **Step 2: Write the failing test**
|
|
|
|
Create `tests/test_cookie_secure.py`:
|
|
```python
|
|
import importlib
|
|
from tests.conftest import make_project
|
|
from backend.auth_passwords import hash_password
|
|
|
|
|
|
def test_cookie_secure_flag_is_applied(monkeypatch, client, db_session):
|
|
import backend.portal_auth as pa
|
|
monkeypatch.setattr(pa, "COOKIE_SECURE", True, raising=False)
|
|
# also patch the name imported into the router module
|
|
import backend.routers.portal as pr
|
|
monkeypatch.setattr(pr, "COOKIE_SECURE", True, raising=False)
|
|
|
|
make_project(db_session, portal_enabled=True, portal_link_token="ts",
|
|
portal_password_hash=hash_password("pw"))
|
|
r = client.post("/portal/p/ts", data={"password": "pw"}, follow_redirects=False)
|
|
assert "secure" in r.headers.get("set-cookie", "").lower()
|
|
```
|
|
|
|
- [ ] **Step 3: Run to verify failure**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_cookie_secure.py -v`
|
|
Expected: FAIL (cookie has no `Secure`).
|
|
|
|
- [ ] **Step 4: Apply `secure=COOKIE_SECURE` at every `set_cookie` site**
|
|
|
|
In `backend/routers/portal.py`: add `COOKIE_SECURE` to the `backend.portal_auth` import, and in the `portal_password_submit` `set_cookie` call add `secure=COOKIE_SECURE`:
|
|
```python
|
|
resp.set_cookie(COOKIE_NAME, make_session_cookie(token_id),
|
|
max_age=COOKIE_MAX_AGE, httponly=True, samesite="lax",
|
|
secure=COOKIE_SECURE)
|
|
```
|
|
In `backend/main.py` `project_portal_preview`, import `COOKIE_SECURE` alongside the others and add `secure=COOKIE_SECURE` to its `set_cookie` call the same way.
|
|
|
|
- [ ] **Step 5: Run to verify pass**
|
|
|
|
Run: `docker exec terra-view-terra-view-1 python -m pytest tests/test_cookie_secure.py -v`
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add backend/portal_auth.py backend/routers/portal.py backend/main.py tests/test_cookie_secure.py
|
|
git commit -m "feat: env-driven Secure flag on portal session cookie"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 11: Docs, changelog, and rollout notes
|
|
|
|
**Files:**
|
|
- Modify: `CHANGELOG.md` (`[Unreleased]`)
|
|
- Modify: `docs/CLIENT_PORTAL.md` (note Phase-1 password gate supersedes the magic-link)
|
|
|
|
- [ ] **Step 1: Add a changelog entry**
|
|
|
|
Under `[Unreleased]` in `CHANGELOG.md`, add:
|
|
```markdown
|
|
### Portal authentication (Phase 1)
|
|
- Each project's client portal is now gated by a **secure per-project link + shared password** (argon2-hashed). Operators manage it from the project page's **Portal access** panel (enable, generate password, copy link).
|
|
- Brute-force lockout (5 tries / 15 min) on the password gate.
|
|
- Retired the interim magic-link / `PORTAL_OPEN_LINKS` open links.
|
|
- **Upgrade:** run `python3 backend/migrate_add_project_portal_auth.py` per DB. Set `COOKIE_SECURE=true` once served over HTTPS.
|
|
```
|
|
|
|
- [ ] **Step 2: Note the supersession in `docs/CLIENT_PORTAL.md`**
|
|
|
|
Add a short line at the top of `docs/CLIENT_PORTAL.md` pointing to the new spec/plan and noting the magic-link is retired in favor of the per-project password gate (see `docs/superpowers/specs/2026-06-15-portal-auth-design.md`).
|
|
|
|
- [ ] **Step 3: Run the full suite one last time**
|
|
|
|
```bash
|
|
docker exec terra-view-terra-view-1 python -m pytest tests/ -v
|
|
```
|
|
Expected: all green.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add CHANGELOG.md docs/CLIENT_PORTAL.md
|
|
git commit -m "docs: changelog + portal-auth Phase 1 notes"
|
|
```
|
|
|
|
---
|
|
|
|
## Rollout (after merge to dev)
|
|
|
|
1. Run the migration on each DB: `docker exec <container> python3 backend/migrate_add_project_portal_auth.py` (dev: `terra-view-terra-view-1`; prod: `terra-view-web-app-1`). Rebuild images first so `argon2-cffi` is present.
|
|
2. Set a real `SECRET_KEY` in prod (already required); set `COOKIE_SECURE=true` once behind TLS.
|
|
3. Enable a project's portal, set a password, and walk the link→password→dashboard flow over HTTPS before sending a client.
|
|
|
|
## Deferred (separate specs later)
|
|
|
|
- **Operator auth** (roles, UniFi edge, staged flip) — see `docs/superpowers/specs/2026-06-15-portal-auth-design.md` §Deferred A.
|
|
- **Full multi-tenancy** (per-client rollup, individual client accounts) — §Deferred B.
|