feat(m2): auth, JWT, invitations, bootstrap, RTOps SPA pages

Crypto + tokens
- app/core/security.py: Argon2id PasswordHasher (time_cost=2, memory_cost=
  64 MiB, parallelism=2) + opaque-token SHA-256 helpers (raw token shown
  once, only the hash lives in the DB).
- app/core/jwt_tokens.py: HS256, claims iss/sub/type/jti/iat/exp. Access
  1h, refresh 30d.

Services
- services/auth.py: login, refresh with token rotation + reuse-detection
  chain revoke, logout (idempotent), change_password (forces logout-all).
- services/invitations.py: create, preview, accept, revoke. Default 7d TTL.
- services/bootstrap.py: seeds the 3 system groups (admin/redteam/blueteam),
  consumes the install token, attaches the first user to admin.
- core/install_token.py: mints, persists in settings, marks consumed,
  regenerate hook for /diag/reset.

API
- POST /setup (consume install token, create 1st admin) + GET /setup
  (status).
- POST /auth/{login,refresh,logout,change-password} + GET /auth/me.
- POST /invitations + GET /invitations + GET /invitations/preview/<token> +
  POST /invitations/accept/<token> + POST /invitations/<id>/revoke.
- POST /diag/reset: test-only kill switch (truncate auth tables + mint
  fresh install token). Allowed in dev too (with WARNING log) so the e2e
  suite can run against a make-up stack; production locked out.

Middleware
- @require_auth populates g.current_user (snapshot dataclass, session
  closed before request handler runs).
- @require_perm(*codes): atomic perm union check; admin group bypasses.
  Perm catalogue lands in M3, scaffolding here.
- flask-limiter: 10/min/IP on /auth/login & /auth/refresh, 5/min on
  /auth/change-password & /setup, 10–20/min on invitation endpoints.
  Disabled in APP_ENV=test.

CLI
- flask --app app.cli metamorph print-install-token [--force]
- flask --app app.cli metamorph seed-mitre (M4 placeholder)

Refresh cookie metamorph_refresh: HttpOnly + Secure (localhost is a secure
context for modern browsers) + SameSite=Strict + Path=/api/v1/auth/.

Email validation: app.api._validation.Email permissive RFC-shape regex so
internal TLDs (.local/.corp/.test) are accepted — pydantic.EmailStr's
deliverability check is too strict for red-team labs.

Frontend
- lib/{api,auth}.ts: access token in module memory, refresh cookie,
  automatic 401-retry via /auth/refresh, useAuth() hook.
- components/{Layout,RequireAuth}.tsx + ui/{TextField,Alert}.tsx.
- pages/{Login,Setup,Register,Profile}.

Testing
- tests/test_auth_flow.py: 15 integration tests (24 backend total).
- e2e/tests/m2-auth.spec.ts: 8 Playwright tests (20 e2e total).
- tasks/testing-m2.md.

DoD: make test-api → 24 passed, make e2e → 20 passed; spec-reviewer pass
applied (Secure unconditional, refresh limit 10/min/IP).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/app/api/_validation.py

@@ -0,0 +1,30 @@
+"""Lightweight email validator that tolerates internal/lab TLDs (.local, .corp, …).
+
+`pydantic.EmailStr` relies on `email-validator` with `globally_deliverable=True`,
+which rejects RFC 6761 special-use domains. Red-team and corporate intranet
+deployments routinely use such suffixes — we accept any RFC-shape email and
+defer deliverability checks to the operator.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Annotated
+
+from pydantic import AfterValidator
+
+# Permissive RFC-shape pattern: local-part 1..64 chars, domain has at least one
+# dot, each label is 1..63 chars of letters/digits/hyphens, total ≤ 254.
+_EMAIL_RE = re.compile(
+    r"^(?=.{1,254}$)[A-Za-z0-9._%+\-]{1,64}@[A-Za-z0-9](?:[A-Za-z0-9\-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9\-]{0,61}[A-Za-z0-9])?)+$"
+)
+
+
+def _validate_email(value: str) -> str:
+    v = value.strip()
+    if not _EMAIL_RE.match(v):
+        raise ValueError("not a valid email address")
+    return v.lower()
+
+
+Email = Annotated[str, AfterValidator(_validate_email)]

backend/app/api/auth.py

@@ -0,0 +1,157 @@
+"""Authentication endpoints.
+
+`POST /auth/login` returns the access token in the body and sets the refresh
+token in an HTTPOnly cookie scoped to `/api/v1/auth/`. The cookie is
+`Secure; SameSite=Strict` and only the matching paths can read it.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from flask import Blueprint, g, jsonify, make_response, request
+from pydantic import BaseModel, Field, ValidationError
+
+from app.api._validation import Email
+from app.core.auth_decorators import require_auth
+from app.core.config import settings
+from app.core.rate_limit import limiter
+from app.services import auth as auth_svc
+
+bp = Blueprint("auth", __name__, url_prefix="/auth")
+log = logging.getLogger("metamorph.api.auth")
+
+REFRESH_COOKIE_NAME = "metamorph_refresh"
+REFRESH_COOKIE_PATH = "/api/v1/auth/"
+
+
+class LoginPayload(BaseModel):
+    email: Email
+    password: str = Field(min_length=1)
+
+
+class ChangePasswordPayload(BaseModel):
+    current_password: str = Field(min_length=1)
+    new_password: str = Field(min_length=8)
+
+
+def _set_refresh_cookie(resp, token: str, expires_at) -> None:
+    resp.set_cookie(
+        REFRESH_COOKIE_NAME,
+        token,
+        expires=expires_at,
+        httponly=True,
+        secure=True,  # spec §M2; localhost is a secure context for modern browsers
+        samesite="Strict",
+        path=REFRESH_COOKIE_PATH,
+    )
+
+
+def _clear_refresh_cookie(resp) -> None:
+    resp.set_cookie(
+        REFRESH_COOKIE_NAME,
+        "",
+        expires=0,
+        httponly=True,
+        secure=True,  # spec §M2; localhost is a secure context for modern browsers
+        samesite="Strict",
+        path=REFRESH_COOKIE_PATH,
+    )
+
+
+def _read_refresh_cookie() -> str | None:
+    return request.cookies.get(REFRESH_COOKIE_NAME)
+
+
+def _serialize_pair(pair: auth_svc.TokenPair) -> dict:
+    return {
+        "access_token": pair.access_token,
+        "token_type": "Bearer",
+        "user_id": str(pair.user_id),
+    }
+
+
+@bp.post("/login")
+@limiter.limit("10 per minute")
+def login():
+    try:
+        payload = LoginPayload.model_validate(request.get_json(silent=True) or {})
+    except ValidationError as e:
+        return jsonify({"error": "invalid_request", "details": e.errors()}), 400
+    try:
+        pair = auth_svc.login(payload.email, payload.password)
+    except auth_svc.InvalidCredentials:
+        return jsonify({"error": "invalid_credentials"}), 401
+
+    resp = make_response(jsonify(_serialize_pair(pair)))
+    _set_refresh_cookie(resp, pair.refresh_token, pair.refresh_expires_at)
+    return resp
+
+
+@bp.post("/refresh")
+@limiter.limit("10 per minute")
+def refresh_endpoint():
+    raw = _read_refresh_cookie()
+    if not raw:
+        return jsonify({"error": "no_refresh_cookie"}), 401
+    try:
+        pair = auth_svc.refresh(raw)
+    except auth_svc.TokenRevoked:
+        resp = make_response(jsonify({"error": "token_revoked"}), 401)
+        _clear_refresh_cookie(resp)
+        return resp
+    except auth_svc.InvalidCredentials:
+        resp = make_response(jsonify({"error": "invalid_refresh"}), 401)
+        _clear_refresh_cookie(resp)
+        return resp
+
+    resp = make_response(jsonify(_serialize_pair(pair)))
+    _set_refresh_cookie(resp, pair.refresh_token, pair.refresh_expires_at)
+    return resp
+
+
+@bp.post("/logout")
+def logout():
+    raw = _read_refresh_cookie()
+    if raw:
+        auth_svc.logout(raw)
+    resp = make_response(jsonify({"ok": True}))
+    _clear_refresh_cookie(resp)
+    return resp
+
+
+@bp.get("/me")
+@require_auth
+def me():
+    u = g.current_user
+    return jsonify(
+        {
+            "id": str(u.id),
+            "email": u.email,
+            "display_name": u.display_name,
+            "locale": u.locale,
+            "is_admin": u.is_admin,
+            "groups": sorted(u.group_names),
+            "permissions": sorted(u.permissions),
+        }
+    )
+
+
+@bp.post("/change-password")
+@require_auth
+@limiter.limit("5 per minute")
+def change_password():
+    try:
+        payload = ChangePasswordPayload.model_validate(request.get_json(silent=True) or {})
+    except ValidationError as e:
+        return jsonify({"error": "invalid_request", "details": e.errors()}), 400
+    try:
+        auth_svc.change_password(g.current_user.id, payload.current_password, payload.new_password)
+    except auth_svc.InvalidCredentials:
+        return jsonify({"error": "current_password_incorrect"}), 400
+    except ValueError as e:
+        return jsonify({"error": "weak_password", "message": str(e)}), 400
+
+    resp = make_response(jsonify({"ok": True}))
+    _clear_refresh_cookie(resp)
+    return resp

backend/app/api/invitations.py

@@ -0,0 +1,146 @@
+"""Invitation endpoints — admin issues, invitee previews + accepts."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+
+from flask import Blueprint, g, jsonify, make_response, request
+from pydantic import BaseModel, Field, ValidationError
+
+from app.api._validation import Email
+from app.core.auth_decorators import require_auth, require_perm
+from app.core.rate_limit import limiter
+from app.services import invitations as inv_svc
+
+bp = Blueprint("invitations", __name__, url_prefix="/invitations")
+log = logging.getLogger("metamorph.api.invitations")
+
+
+class CreateInvitationPayload(BaseModel):
+    email_hint: Email | None = None
+    group_ids: list[uuid.UUID] = Field(default_factory=list)
+    ttl_days: int | None = Field(default=None, ge=1, le=30)
+
+
+class AcceptInvitationPayload(BaseModel):
+    email: Email
+    password: str = Field(min_length=8)
+    display_name: str | None = None
+
+
+@bp.post("")
+@require_auth
+@require_perm("invitation.create")
+def create():
+    try:
+        payload = CreateInvitationPayload.model_validate(request.get_json(silent=True) or {})
+    except ValidationError as e:
+        return jsonify({"error": "invalid_request", "details": e.errors()}), 400
+
+    from datetime import timedelta
+
+    ttl = (
+        timedelta(days=payload.ttl_days)
+        if payload.ttl_days is not None
+        else inv_svc.INVITATION_TTL
+    )
+    result = inv_svc.create_invitation(
+        created_by_user_id=g.current_user.id,
+        email_hint=payload.email_hint,
+        group_ids=payload.group_ids,
+        ttl=ttl,
+    )
+    log.info(
+        "metamorph.invitation.created",
+        extra={
+            "invitation_id": str(result.invitation_id),
+            "by_user_id": str(g.current_user.id),
+            "expires_at": result.expires_at.isoformat(),
+        },
+    )
+    return make_response(
+        jsonify(
+            {
+                "id": str(result.invitation_id),
+                "token": result.raw_token,  # shown ONCE
+                "expires_at": result.expires_at.isoformat(),
+            }
+        ),
+        201,
+    )
+
+
+@bp.get("")
+@require_auth
+@require_perm("invitation.read")
+def list_active():
+    rows = inv_svc.list_active()
+    return jsonify(
+        [
+            {
+                "id": str(r.id),
+                "email_hint": r.email_hint,
+                "expires_at": r.expires_at.isoformat(),
+                "groups": [g.name for g in r.pre_assigned_groups],
+            }
+            for r in rows
+        ]
+    )
+
+
+@bp.post("/<invitation_id>/revoke")
+@require_auth
+@require_perm("invitation.revoke")
+def revoke(invitation_id: str):
+    try:
+        iid = uuid.UUID(invitation_id)
+    except ValueError:
+        return jsonify({"error": "invalid_id"}), 400
+    ok = inv_svc.revoke(iid)
+    if not ok:
+        return jsonify({"error": "not_revocable"}), 404
+    return jsonify({"ok": True})
+
+
+@bp.get("/preview/<token>")
+@limiter.limit("20 per minute")
+def preview(token: str):
+    p = inv_svc.preview(token)
+    return jsonify(
+        {
+            "is_valid": p.is_valid,
+            "reason": p.reason,
+            "email_hint": p.email_hint,
+            "expires_at": p.expires_at.isoformat(),
+            "groups": p.groups,
+        }
+    )
+
+
+@bp.post("/accept/<token>")
+@limiter.limit("10 per minute")
+def accept(token: str):
+    try:
+        payload = AcceptInvitationPayload.model_validate(request.get_json(silent=True) or {})
+    except ValidationError as e:
+        return jsonify({"error": "invalid_request", "details": e.errors()}), 400
+    try:
+        user_id = inv_svc.accept(
+            token,
+            email=payload.email,
+            password=payload.password,
+            display_name=payload.display_name,
+        )
+    except inv_svc.InvitationExpired:
+        return jsonify({"error": "invitation_expired"}), 410
+    except inv_svc.InvitationConsumed:
+        return jsonify({"error": "invitation_consumed"}), 410
+    except inv_svc.InvitationRevoked:
+        return jsonify({"error": "invitation_revoked"}), 410
+    except inv_svc.InvitationError as e:
+        return jsonify({"error": "invitation_invalid", "message": str(e)}), 400
+    except ValueError as e:
+        return jsonify({"error": "invalid_request", "message": str(e)}), 400
+
+    return make_response(jsonify({"ok": True, "user_id": str(user_id)}), 201)

backend/app/api/setup.py

@@ -0,0 +1,79 @@
+"""Bootstrap endpoint — consumes the install token to create the first admin."""
+
+from __future__ import annotations
+
+import logging
+
+from flask import Blueprint, jsonify, make_response, request
+from pydantic import BaseModel, Field, ValidationError
+
+from app.api._validation import Email
+from sqlalchemy import select
+
+from app.core.rate_limit import limiter
+from app.db.session import session_scope
+from app.models.auth import User
+from app.services.bootstrap import (
+    BootstrapError,
+    bootstrap_admin,
+    ensure_system_groups,
+)
+
+bp = Blueprint("setup", __name__, url_prefix="/setup")
+log = logging.getLogger("metamorph.api.setup")
+
+
+class SetupPayload(BaseModel):
+    install_token: str = Field(min_length=20)
+    email: Email
+    password: str = Field(min_length=8)
+    display_name: str | None = None
+
+
+@bp.get("")
+def setup_status():
+    """Tell the SPA whether the bootstrap has already been done.
+
+    Used by the front to redirect to /setup vs /login on first paint.
+    """
+    with session_scope() as s:
+        any_user = s.scalar(select(User.id).limit(1)) is not None
+    return jsonify({"completed": any_user})
+
+
+@bp.post("")
+@limiter.limit("5 per minute")
+def setup():
+    try:
+        payload = SetupPayload.model_validate(request.get_json(silent=True) or {})
+    except ValidationError as e:
+        return jsonify({"error": "invalid_request", "details": e.errors()}), 400
+
+    try:
+        result = bootstrap_admin(
+            install_token=payload.install_token,
+            email=payload.email,
+            password=payload.password,
+            display_name=payload.display_name,
+        )
+    except BootstrapError as e:
+        return jsonify({"error": "bootstrap_failed", "message": str(e)}), 409
+    except ValueError as e:
+        return jsonify({"error": "invalid_request", "message": str(e)}), 400
+
+    log.warning(
+        "metamorph.bootstrap.completed",
+        extra={"user_id": str(result.user_id), "admin_group_id": str(result.admin_group_id)},
+    )
+    # Make sure the redteam/blueteam groups exist too (idempotent).
+    ensure_system_groups()
+
+    return make_response(
+        jsonify(
+            {
+                "ok": True,
+                "user_id": str(result.user_id),
+            }
+        ),
+        201,
+    )