diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md
index ae0350d..bc8160d 100644
--- a/WORK-RECORDS.md
+++ b/WORK-RECORDS.md
@@ -28,7 +28,7 @@
| workplan | USER-WP-0018 | finished | — | workplans/USER-WP-0018-postgres-store-adapter.md |
| workplan | USER-WP-0019 | finished | — | workplans/USER-WP-0019-provider-backed-postgres-conformance.md |
| workplan | USER-WP-0020 | finished | — | workplans/USER-WP-0020-self-service-and-user-administration-portal.md |
-| workplan | USER-WP-0021 | backlog | — | workplans/USER-WP-0021-portal-product-expansion.md |
+| workplan | USER-WP-0021 | active | — | workplans/USER-WP-0021-portal-product-expansion.md |
| task | USER-WP-0001-T1 | done | — | workplans/USER-WP-0001-preparation-and-interface-adoption.md |
| task | USER-WP-0001-T2 | done | — | workplans/USER-WP-0001-preparation-and-interface-adoption.md |
| task | USER-WP-0001-T3 | done | — | workplans/USER-WP-0001-preparation-and-interface-adoption.md |
@@ -154,8 +154,8 @@
| task | USER-WP-0020-T06 | done | — | workplans/USER-WP-0020-self-service-and-user-administration-portal.md |
| task | USER-WP-0020-T07 | done | — | workplans/USER-WP-0020-self-service-and-user-administration-portal.md |
| task | USER-WP-0020-T08 | done | — | workplans/USER-WP-0020-self-service-and-user-administration-portal.md |
-| task | USER-WP-0021-T01 | todo | — | workplans/USER-WP-0021-portal-product-expansion.md |
-| task | USER-WP-0021-T02 | todo | — | workplans/USER-WP-0021-portal-product-expansion.md |
-| task | USER-WP-0021-T03 | todo | — | workplans/USER-WP-0021-portal-product-expansion.md |
-| task | USER-WP-0021-T04 | todo | — | workplans/USER-WP-0021-portal-product-expansion.md |
+| task | USER-WP-0021-T01 | progress | — | workplans/USER-WP-0021-portal-product-expansion.md |
+| task | USER-WP-0021-T02 | done | — | workplans/USER-WP-0021-portal-product-expansion.md |
+| task | USER-WP-0021-T03 | done | — | workplans/USER-WP-0021-portal-product-expansion.md |
+| task | USER-WP-0021-T04 | done | — | workplans/USER-WP-0021-portal-product-expansion.md |
| task | USER-WP-0021-T05 | wait | — | workplans/USER-WP-0021-portal-product-expansion.md |
diff --git a/docs/configuration.md b/docs/configuration.md
index 7256422..57f75a6 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -42,3 +42,17 @@ Initial logical names:
- Sensitive writes must fail closed when authorization is unavailable.
- Claims enrichment must be optional and must not make user-engine a token
issuer.
+
+## Portal integration settings
+
+The production portal requires its existing database, OIDC, proxy-marker, and
+identity-provisioning settings. Platform tenant creation is enabled only when
+both of these settings are present:
+
+- `USER_ENGINE_TENANT_MANAGEMENT_URL` — tenant-authority base URL;
+- `USER_ENGINE_TENANT_MANAGEMENT_TOKEN` — workload-scoped bearer token.
+
+The adapter calls `POST /v1/tenants` with correlation and idempotency headers.
+The token is never returned in errors, audit records, outbox events, or browser
+responses. When the settings are absent, ordinary portal behavior remains
+available and platform tenant creation fails closed as unavailable.
diff --git a/openapi/portal-v1.yaml b/openapi/portal-v1.yaml
index 14d5a86..aa4aa20 100644
--- a/openapi/portal-v1.yaml
+++ b/openapi/portal-v1.yaml
@@ -1,7 +1,7 @@
openapi: 3.1.0
info:
title: user-engine portal API
- version: 0.1.0
+ version: 0.2.0
servers:
- url: /api/v1
security:
@@ -15,6 +15,19 @@ paths:
description: Current user and linked identities
"403":
$ref: "#/components/responses/Denied"
+ /me/profile:
+ patch:
+ operationId: updateCurrentUserProfile
+ description: Updates display name and versioned consent; verified email cannot be changed here.
+ parameters: [{$ref: "#/components/parameters/IdempotencyKey"}]
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: {$ref: "#/components/schemas/UpdateSelfProfile"}
+ responses:
+ "200": {description: Durable self-service profile state}
+ "403": {$ref: "#/components/responses/Denied"}
/registrations:
post:
operationId: startRegistration
@@ -49,6 +62,19 @@ paths:
responses:
"200": {description: Tenant-scoped memberships}
"403": {$ref: "#/components/responses/Denied"}
+ post:
+ operationId: createTenantUser
+ parameters:
+ - $ref: "#/components/parameters/Tenant"
+ - $ref: "#/components/parameters/IdempotencyKey"
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: {$ref: "#/components/schemas/CreateUser"}
+ responses:
+ "201": {description: Tenant user and membership created}
+ "403": {$ref: "#/components/responses/Denied"}
/tenants/{tenant}/users/{userId}:
patch:
operationId: updateTenantUserLifecycle
@@ -62,6 +88,132 @@ paths:
responses:
"200": {description: Tenant account updated}
"403": {$ref: "#/components/responses/Denied"}
+ delete:
+ operationId: removeTenantUser
+ parameters:
+ - $ref: "#/components/parameters/Tenant"
+ - $ref: "#/components/parameters/UserId"
+ - $ref: "#/components/parameters/IdempotencyKey"
+ responses:
+ "200": {description: Login deprovisioned and tenant account disabled}
+ "403": {$ref: "#/components/responses/Denied"}
+ /tenants/{tenant}/invitations:
+ get:
+ operationId: listInvitations
+ parameters: [{$ref: "#/components/parameters/Tenant"}]
+ responses:
+ "200": {description: Tenant invitations}
+ "403": {$ref: "#/components/responses/Denied"}
+ post:
+ operationId: createInvitation
+ parameters:
+ - $ref: "#/components/parameters/Tenant"
+ - $ref: "#/components/parameters/IdempotencyKey"
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: {$ref: "#/components/schemas/CreateInvitation"}
+ responses:
+ "201": {description: Invitation created with an expiry and version}
+ "409": {$ref: "#/components/responses/Conflict"}
+ /tenants/{tenant}/invitations/{invitationId}/resend:
+ post:
+ operationId: resendInvitation
+ parameters:
+ - $ref: "#/components/parameters/Tenant"
+ - $ref: "#/components/parameters/InvitationId"
+ - $ref: "#/components/parameters/IfMatch"
+ responses:
+ "200": {description: Invitation expiry renewed and version advanced}
+ "409": {$ref: "#/components/responses/Conflict"}
+ /tenants/{tenant}/invitations/{invitationId}/expire:
+ post:
+ operationId: expireInvitation
+ parameters:
+ - $ref: "#/components/parameters/Tenant"
+ - $ref: "#/components/parameters/InvitationId"
+ - $ref: "#/components/parameters/IfMatch"
+ responses:
+ "200": {description: Invitation revoked}
+ "409": {$ref: "#/components/responses/Conflict"}
+ /invitations/{invitationId}/claim:
+ post:
+ operationId: claimInvitation
+ parameters:
+ - $ref: "#/components/parameters/InvitationId"
+ - $ref: "#/components/parameters/IdempotencyKey"
+ responses:
+ "200": {description: Invitation claimed and identity linked}
+ "400": {description: Invitation expired, revoked, or already claimed}
+ /onboarding/{journeyId}/steps/{stepKey}/complete:
+ post:
+ operationId: completeOnboardingStep
+ description: Completes an active user-engine-owned step. Provider-owned steps must use their external handoff and callback.
+ parameters:
+ - name: journeyId
+ in: path
+ required: true
+ schema: {type: string}
+ - name: stepKey
+ in: path
+ required: true
+ schema: {type: string}
+ - $ref: "#/components/parameters/IdempotencyKey"
+ responses:
+ "200": {description: Updated resumable onboarding journey}
+ "403": {$ref: "#/components/responses/Denied"}
+ "404": {description: Journey is absent or belongs to another user}
+ /platform/tenants:
+ post:
+ operationId: createPlatformTenant
+ description: Creates a tenant through the configured tenant authority and optionally prepares its first administrator.
+ parameters: [{$ref: "#/components/parameters/IdempotencyKey"}]
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: {$ref: "#/components/schemas/CreateTenant"}
+ responses:
+ "201": {description: Tenant created or resumed and first administrator prepared}
+ "403": {$ref: "#/components/responses/Denied"}
+ /platform/tenants/{tenant}/users/{userId}/recover:
+ post:
+ operationId: recoverTenantUser
+ description: Reconciles or recreates the provider identity and activates the tenant account without exposing provider credentials.
+ parameters:
+ - $ref: "#/components/parameters/Tenant"
+ - $ref: "#/components/parameters/UserId"
+ - $ref: "#/components/parameters/IdempotencyKey"
+ responses:
+ "200": {description: Redacted recovery outcome}
+ "403": {$ref: "#/components/responses/Denied"}
+ /platform/outbox/deliver:
+ post:
+ operationId: deliverOutbox
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ worker_id: {type: string}
+ max_attempts: {type: integer, minimum: 1, maximum: 20}
+ additionalProperties: false
+ responses:
+ "200": {description: Bounded delivery results}
+ "403": {$ref: "#/components/responses/Denied"}
+ /platform/outbox/{eventId}/replay:
+ post:
+ operationId: replayOutboxEvent
+ parameters:
+ - name: eventId
+ in: path
+ required: true
+ schema: {type: string}
+ responses:
+ "200": {description: Event returned to pending delivery}
+ "403": {$ref: "#/components/responses/Denied"}
components:
securitySchemes:
verifiedOidc:
@@ -78,6 +230,77 @@ components:
in: header
required: true
schema: {type: string, minLength: 16, maxLength: 200}
+ UserId:
+ name: userId
+ in: path
+ required: true
+ schema: {type: string}
+ InvitationId:
+ name: invitationId
+ in: path
+ required: true
+ schema: {type: string}
+ IfMatch:
+ name: If-Match
+ in: header
+ required: true
+ schema: {type: string, pattern: '^"?[0-9]+"?$'}
+ schemas:
+ CreateUser:
+ type: object
+ required: [primary_email, role]
+ properties:
+ primary_email: {type: string, format: email}
+ display_name: {type: string, maxLength: 200}
+ role: {type: string, enum: [user, tenant-admin]}
+ additionalProperties: false
+ CreateInvitation:
+ type: object
+ required: [primary_email]
+ properties:
+ primary_email: {type: string, format: email}
+ display_name: {type: string, maxLength: 200}
+ role: {type: string, enum: [user, tenant-admin]}
+ application_id: {type: string}
+ scope_id: {type: string}
+ additionalProperties: false
+ CreateTenant:
+ type: object
+ required: [tenant, display_name]
+ properties:
+ tenant: {type: string, pattern: '^tenant:'}
+ display_name: {type: string, minLength: 1, maxLength: 200}
+ first_admin:
+ type: object
+ required: [primary_email]
+ properties:
+ primary_email: {type: string, format: email}
+ display_name: {type: string, maxLength: 200}
+ additionalProperties: false
+ additionalProperties: false
+ UpdateSelfProfile:
+ type: object
+ required: [display_name, consent_accepted, consent_version]
+ properties:
+ display_name: {type: string, minLength: 1, maxLength: 200}
+ consent_accepted: {type: boolean}
+ consent_version: {type: string, minLength: 1, maxLength: 100}
+ additionalProperties: false
+ Error:
+ type: object
+ required: [error, message, correlation_id]
+ properties:
+ error: {type: string}
+ message: {type: string}
+ correlation_id: {type: string}
responses:
Denied:
description: Caller is unauthenticated or unauthorized
+ content:
+ application/json:
+ schema: {$ref: "#/components/schemas/Error"}
+ Conflict:
+ description: Optimistic concurrency or uniqueness conflict
+ content:
+ application/json:
+ schema: {$ref: "#/components/schemas/Error"}
diff --git a/src/user_engine/adapters/__init__.py b/src/user_engine/adapters/__init__.py
index f8d4ff9..9e84843 100644
--- a/src/user_engine/adapters/__init__.py
+++ b/src/user_engine/adapters/__init__.py
@@ -7,6 +7,7 @@ from user_engine.adapters.local import (
from user_engine.adapters.postgres import PostgresUserEngineStore
from user_engine.adapters.claims import VerifiedIdentityClaimsAdapter
from user_engine.adapters.provisioning import HTTPIdentityProvisioningAdapter
+from user_engine.adapters.tenant_management import HTTPTenantManagementAdapter
__all__ = [
"InMemoryUserEngineStore",
@@ -14,4 +15,5 @@ __all__ = [
"PostgresUserEngineStore",
"VerifiedIdentityClaimsAdapter",
"HTTPIdentityProvisioningAdapter",
+ "HTTPTenantManagementAdapter",
]
diff --git a/src/user_engine/adapters/local.py b/src/user_engine/adapters/local.py
index 879abdc..33428a4 100644
--- a/src/user_engine/adapters/local.py
+++ b/src/user_engine/adapters/local.py
@@ -161,6 +161,12 @@ class InMemoryUserEngineStore:
if invitation.user_id == user_id
)
+ def family_invitations_for_tenant(self, tenant: str) -> tuple[FamilyInvitation, ...]:
+ return tuple(
+ invitation for invitation in self.family_invitations.values()
+ if invitation.tenant == tenant
+ )
+
def save_registration_session(self, session: RegistrationSession) -> None:
self.registration_sessions[session.registration_id] = session
@@ -324,7 +330,19 @@ class InMemoryUserEngineStore:
self.outbox_events.append(event)
def pending_outbox(self) -> tuple[OutboxEvent, ...]:
- return tuple(self.outbox_events)
+ return tuple(
+ item for item in self.outbox_events
+ if item.delivered_at is None and item.dead_lettered_at is None
+ )
+
+ def save_outbox(self, event: OutboxEvent) -> None:
+ self.outbox_events = [
+ event if item.event_id == event.event_id else item
+ for item in self.outbox_events
+ ]
+
+ def outbox_event(self, event_id: str) -> OutboxEvent | None:
+ return next((item for item in self.outbox_events if item.event_id == event_id), None)
def record_counts(self) -> Mapping[str, int]:
return {
diff --git a/src/user_engine/adapters/postgres.py b/src/user_engine/adapters/postgres.py
index fe9ef0d..2b185ec 100644
--- a/src/user_engine/adapters/postgres.py
+++ b/src/user_engine/adapters/postgres.py
@@ -198,6 +198,12 @@ class PostgresUserEngineStore:
self._query_records("family_invitations", user_id=user_id),
)
+ def family_invitations_for_tenant(self, tenant: str) -> tuple[FamilyInvitation, ...]:
+ return cast(
+ tuple[FamilyInvitation, ...],
+ self._query_records("family_invitations", tenant=tenant),
+ )
+
def save_registration_session(self, session: RegistrationSession) -> None:
self._upsert_record(session)
@@ -413,7 +419,7 @@ class PostgresUserEngineStore:
"""
SELECT payload
FROM user_engine_outbox_events
- WHERE claimed_at IS NULL AND delivered_at IS NULL
+ WHERE claimed_at IS NULL AND delivered_at IS NULL AND failed_at IS NULL
ORDER BY occurred_at, event_id
"""
)
@@ -422,6 +428,31 @@ class PostgresUserEngineStore:
for row in cursor.fetchall()
)
+ def save_outbox(self, event: OutboxEvent) -> None:
+ store_record = store_record_for(event)
+ with self._cursor() as cursor:
+ cursor.execute(
+ """
+ UPDATE user_engine_outbox_events
+ SET payload = %s::jsonb, claimed_at = %s, claimed_by = %s,
+ delivered_at = %s, failed_at = %s, failure_reason = %s
+ WHERE event_id = %s
+ """,
+ (json.dumps(store_record.payload), event.claimed_at, event.claimed_by,
+ event.delivered_at, event.failed_at, event.failure_reason, event.event_id),
+ )
+
+ def outbox_event(self, event_id: str) -> OutboxEvent | None:
+ with self._cursor() as cursor:
+ cursor.execute(
+ "SELECT payload FROM user_engine_outbox_events WHERE event_id = %s",
+ (event_id,),
+ )
+ row = cursor.fetchone()
+ return None if row is None else cast(
+ OutboxEvent, self._decode_payload_row("outbox_events", row)
+ )
+
def record_counts(self) -> Mapping[str, int]:
counts = {key: 0 for key in USER_ENGINE_RECORD_COUNT_KEYS}
with self._cursor() as cursor:
diff --git a/src/user_engine/adapters/tenant_management.py b/src/user_engine/adapters/tenant_management.py
new file mode 100644
index 0000000..d06a9f7
--- /dev/null
+++ b/src/user_engine/adapters/tenant_management.py
@@ -0,0 +1,52 @@
+"""HTTP adapter for the provider-neutral tenant authority."""
+
+from __future__ import annotations
+
+import json
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from user_engine.ports import TenantProvisioningResult
+
+
+class HTTPTenantManagementAdapter:
+ def __init__(self, *, base_url: str, bearer_token: str, timeout: float = 10) -> None:
+ self.base_url = base_url.rstrip("/")
+ self.bearer_token = bearer_token.strip()
+ if not self.bearer_token:
+ raise ValueError("bearer token must not be empty")
+ self.timeout = timeout
+
+ def create_tenant(
+ self, *, tenant: str, display_name: str, idempotency_key: str,
+ correlation_id: str,
+ ) -> TenantProvisioningResult:
+ request = Request(
+ self.base_url + "/v1/tenants",
+ data=json.dumps({
+ "tenant": tenant, "display_name": display_name,
+ "idempotency_key": idempotency_key,
+ "correlation_id": correlation_id,
+ }).encode(),
+ headers={
+ "Authorization": f"Bearer {self.bearer_token}",
+ "Content-Type": "application/json",
+ "Idempotency-Key": idempotency_key,
+ "X-Request-ID": correlation_id,
+ },
+ method="POST",
+ )
+ try:
+ with urlopen(request, timeout=self.timeout) as response:
+ result = json.loads(response.read())
+ except HTTPError as exc:
+ exc.read(4096)
+ raise RuntimeError(f"tenant authority failed ({exc.code})") from exc
+ except URLError as exc:
+ raise RuntimeError("tenant authority unavailable") from exc
+ return TenantProvisioningResult(
+ tenant=str(result.get("tenant") or tenant),
+ status=str(result["status"]),
+ resumed=bool(result.get("resumed", False)),
+ external_ref=str(result["external_ref"]) if result.get("external_ref") else None,
+ )
diff --git a/src/user_engine/domain/models.py b/src/user_engine/domain/models.py
index 4c1e7c8..2ea3a9f 100644
--- a/src/user_engine/domain/models.py
+++ b/src/user_engine/domain/models.py
@@ -229,6 +229,10 @@ class User:
display_name: str | None = None
primary_email: str | None = None
created_at: datetime = field(default_factory=utc_now)
+ updated_at: datetime = field(default_factory=utc_now)
+ profile_completed_at: datetime | None = None
+ consented_at: datetime | None = None
+ consent_version: str | None = None
@dataclass(frozen=True)
@@ -531,6 +535,8 @@ class FamilyInvitation:
updated_at: datetime = field(default_factory=utc_now)
accepted_at: datetime | None = None
revoked_at: datetime | None = None
+ expires_at: datetime | None = None
+ version: int = 1
@dataclass(frozen=True)
@@ -679,3 +685,10 @@ class OutboxEvent:
tenant: str
correlation_id: str
occurred_at: datetime = field(default_factory=utc_now)
+ delivery_attempts: int = 0
+ claimed_by: str | None = None
+ claimed_at: datetime | None = None
+ delivered_at: datetime | None = None
+ failed_at: datetime | None = None
+ failure_reason: str | None = None
+ dead_lettered_at: datetime | None = None
diff --git a/src/user_engine/oidc.py b/src/user_engine/oidc.py
index 89a673b..53c920d 100644
--- a/src/user_engine/oidc.py
+++ b/src/user_engine/oidc.py
@@ -48,13 +48,13 @@ class OIDCClient:
self.pending: dict[str, PendingLogin] = {}
self.sessions: dict[str, BrowserSession] = {}
- def begin(self) -> str:
+ def begin(self, *, tenant_hint: str | None = None) -> str:
state = secrets.token_urlsafe(32)
verifier = secrets.token_urlsafe(64)
challenge = _b64(hashlib.sha256(verifier.encode("ascii")).digest())
self.pending[state] = PendingLogin(verifier=verifier, created_at=time.time())
self._prune()
- return f"{self.issuer}/authorize?{urlencode({
+ parameters = {
'response_type': 'code',
'client_id': self.client_id,
'redirect_uri': self.redirect_uri,
@@ -62,7 +62,10 @@ class OIDCClient:
'state': state,
'code_challenge': challenge,
'code_challenge_method': 'S256',
- })}"
+ }
+ if tenant_hint:
+ parameters["tenant_hint"] = tenant_hint
+ return f"{self.issuer}/authorize?{urlencode(parameters)}"
def complete(self, *, code: str, state: str) -> str:
pending = self.pending.pop(state, None)
diff --git a/src/user_engine/ports.py b/src/user_engine/ports.py
index 5e4b18b..8403c22 100644
--- a/src/user_engine/ports.py
+++ b/src/user_engine/ports.py
@@ -75,6 +75,24 @@ class IdentityDriftResult:
changed: tuple[str, ...] = ()
+@dataclass(frozen=True)
+class TenantProvisioningResult:
+ tenant: str
+ status: str
+ resumed: bool = False
+ external_ref: str | None = None
+
+
+class TenantManagementPort(Protocol):
+ """Provider-neutral seam to the tenant authority (normally tenant-engine)."""
+
+ def create_tenant(
+ self, *, tenant: str, display_name: str, idempotency_key: str,
+ correlation_id: str,
+ ) -> TenantProvisioningResult:
+ """Create or resume a tenant without making user-engine authoritative."""
+
+
class IdentityProvisioningPort(Protocol):
"""Lifecycle seam owned by NetKingdom adapters, not the user domain."""
@@ -205,6 +223,11 @@ class UserEngineStore(Protocol):
) -> tuple[FamilyInvitation, ...]:
"""Return family invitations for a user."""
+ def family_invitations_for_tenant(
+ self, tenant: str
+ ) -> tuple[FamilyInvitation, ...]:
+ """Return invitations visible in one tenant."""
+
def save_registration_session(self, session: RegistrationSession) -> None:
"""Create or replace a registration session."""
@@ -308,6 +331,12 @@ class UserEngineStore(Protocol):
def pending_outbox(self) -> tuple[OutboxEvent, ...]:
"""Return pending outbox events in write order."""
+ def save_outbox(self, event: OutboxEvent) -> None:
+ """Persist outbox delivery state."""
+
+ def outbox_event(self, event_id: str) -> OutboxEvent | None:
+ """Return an outbox event including delivery state."""
+
def record_counts(self) -> Mapping[str, int]:
"""Return adapter-neutral record counts for diagnostics."""
diff --git a/src/user_engine/runtime.py b/src/user_engine/runtime.py
index b1ffe6b..2f6a4c0 100644
--- a/src/user_engine/runtime.py
+++ b/src/user_engine/runtime.py
@@ -10,6 +10,7 @@ from user_engine.adapters import (
PostgresUserEngineStore,
VerifiedIdentityClaimsAdapter,
HTTPIdentityProvisioningAdapter,
+ HTTPTenantManagementAdapter,
)
from user_engine.service import UserEngineService
from user_engine.oidc import OIDCClient
@@ -39,6 +40,12 @@ def create_application() -> PortalApplication:
),
authorization=LocalAuthorizationCheckPort(),
)
+ tenant_management = None
+ if os.environ.get("USER_ENGINE_TENANT_MANAGEMENT_URL"):
+ tenant_management = HTTPTenantManagementAdapter(
+ base_url=_required("USER_ENGINE_TENANT_MANAGEMENT_URL"),
+ bearer_token=_required("USER_ENGINE_TENANT_MANAGEMENT_TOKEN"),
+ )
return PortalApplication(
service,
trusted_proxy_secret=_required("USER_ENGINE_PROXY_SECRET"),
@@ -56,6 +63,7 @@ def create_application() -> PortalApplication:
base_url=_required("USER_ENGINE_PROVISIONING_URL"),
bearer_token=_required("USER_ENGINE_PROVISIONING_TOKEN"),
),
+ tenant_management=tenant_management,
)
diff --git a/src/user_engine/service.py b/src/user_engine/service.py
index 07e929b..87cb32d 100644
--- a/src/user_engine/service.py
+++ b/src/user_engine/service.py
@@ -3,8 +3,8 @@
from __future__ import annotations
from dataclasses import dataclass, field, replace
-from datetime import datetime
-from typing import Any, Iterable, Mapping
+from datetime import datetime, timedelta
+from typing import Any, Callable, Iterable, Mapping
from user_engine.domain import (
Account,
@@ -325,6 +325,56 @@ class UserEngineService:
platform_operator=platform_operator,
)
+ def update_self_service_profile(
+ self,
+ actor: Actor,
+ *,
+ display_name: str,
+ consent_accepted: bool,
+ consent_version: str,
+ correlation_id: str | None = None,
+ ) -> User:
+ """Update safe self-service fields; verified email remains immutable."""
+ display_name = display_name.strip()
+ consent_version = consent_version.strip()
+ if not 1 <= len(display_name) <= 200:
+ raise ValidationError("display_name must contain 1 to 200 characters")
+ if consent_accepted and not consent_version:
+ raise ValidationError("consent_version is required when consent is accepted")
+ correlation_id = correlation_id or new_id("corr")
+ identity = self.store.find_identity(actor.issuer, actor.subject)
+ if identity is None:
+ raise NotFoundError("current identity is not linked")
+ user = self._require_user(identity.user_id)
+ decision = self._authorize(
+ actor, action="profile.self.update", resource_type="user-engine:user",
+ resource_id=user.user_id, tenant=actor.tenant,
+ correlation_id=correlation_id, target_user_id=user.user_id,
+ )
+ now = utc_now()
+ updated = replace(
+ user, display_name=display_name, updated_at=now,
+ profile_completed_at=now,
+ consented_at=now if consent_accepted else None,
+ consent_version=consent_version if consent_accepted else None,
+ )
+ with self.store.transaction():
+ self.store.save_user(updated)
+ self._record_mutation(
+ actor, action="profile.self.update", subject=user.user_id,
+ tenant=actor.tenant, correlation_id=correlation_id,
+ decision_id=decision.decision_id,
+ event_type="user.self_service_profile_updated",
+ aggregate_id=user.user_id,
+ payload={
+ "user_id": user.user_id,
+ "profile_complete": True,
+ "consent_accepted": consent_accepted,
+ "consent_version": consent_version if consent_accepted else None,
+ },
+ )
+ return updated
+
def start_registration(
self,
actor: Actor,
@@ -2362,12 +2412,19 @@ class UserEngineService:
member: FamilyMemberSpec,
catalog_namespace: str = "dataspace",
correlation_id: str | None = None,
+ expires_in: timedelta = timedelta(days=7),
) -> FamilyMemberInvitation:
tenant_context = self.resolve_tenant_context(actor, tenant)
correlation_id = correlation_id or new_id("corr")
role = _family_role_value(member.role)
if not member.primary_email:
raise ValidationError("family member primary_email is required")
+ if any(
+ item.primary_email.casefold() == member.primary_email.casefold()
+ and item.status == InvitationStatus.PENDING
+ for item in self.store.family_invitations_for_tenant(tenant_context.tenant)
+ ):
+ raise ConflictError("a pending invitation already exists for this address")
if member.issuer and member.subject:
existing = self.store.find_identity(member.issuer, member.subject)
if existing is not None:
@@ -2409,7 +2466,7 @@ class UserEngineService:
correlation_id=correlation_id,
)
profile_defaults = dict(member.profile_defaults)
- if member.display_name:
+ if member.display_name and role not in {"user", TENANT_ADMIN_ROLE}:
profile_defaults.setdefault("member_display_name", member.display_name)
self._apply_family_profile_defaults(
actor,
@@ -2440,6 +2497,7 @@ class UserEngineService:
invited_by=actor.subject,
correlation_id=correlation_id,
last_sent_correlation_id=correlation_id,
+ expires_at=utc_now() + expires_in,
)
self.store.save_family_invitation(invitation)
self._record_mutation(
@@ -2474,10 +2532,13 @@ class UserEngineService:
invitation_id: str,
*,
correlation_id: str | None = None,
+ expected_version: int | None = None,
) -> FamilyInvitation:
invitation = self._require_family_invitation(invitation_id)
if invitation.status != InvitationStatus.PENDING:
raise ValidationError("only pending invitations can be resent")
+ if expected_version is not None and invitation.version != expected_version:
+ raise ConflictError("invitation version does not match")
tenant_context = self.resolve_tenant_context(actor, invitation.tenant)
correlation_id = correlation_id or new_id("corr")
decision = self._authorize(
@@ -2495,6 +2556,8 @@ class UserEngineService:
resend_count=invitation.resend_count + 1,
last_sent_correlation_id=correlation_id,
updated_at=utc_now(),
+ expires_at=utc_now() + timedelta(days=7),
+ version=invitation.version + 1,
)
with self.store.transaction():
self.store.save_family_invitation(updated)
@@ -2522,10 +2585,13 @@ class UserEngineService:
invitation_id: str,
*,
correlation_id: str | None = None,
+ expected_version: int | None = None,
) -> FamilyInvitation:
invitation = self._require_family_invitation(invitation_id)
if invitation.status != InvitationStatus.PENDING:
raise ValidationError("only pending invitations can be revoked")
+ if expected_version is not None and invitation.version != expected_version:
+ raise ConflictError("invitation version does not match")
tenant_context = self.resolve_tenant_context(actor, invitation.tenant)
correlation_id = correlation_id or new_id("corr")
decision = self._authorize(
@@ -2551,6 +2617,7 @@ class UserEngineService:
status=InvitationStatus.REVOKED,
updated_at=utc_now(),
revoked_at=utc_now(),
+ version=invitation.version + 1,
)
self.store.save_family_invitation(updated)
self._record_mutation(
@@ -2583,8 +2650,13 @@ class UserEngineService:
raise ValidationError("revoked invitations cannot be accepted")
if invitation.status == InvitationStatus.ACCEPTED:
raise ValidationError("invitation is already accepted")
+ if invitation.expires_at is not None and invitation.expires_at <= utc_now():
+ raise ValidationError("invitation has expired")
actor = self.identity_adapter.normalize(claims)
tenant_context = self.resolve_tenant_context(actor, invitation.tenant)
+ claimed_email = str(claims.get("email") or "").strip().casefold()
+ if not claimed_email or claimed_email != invitation.primary_email.casefold():
+ raise AuthorizationDenied("invitation identity does not match")
correlation_id = correlation_id or new_id("corr")
decision = self._authorize(
actor,
@@ -2625,6 +2697,7 @@ class UserEngineService:
status=InvitationStatus.ACCEPTED,
updated_at=accepted_at,
accepted_at=accepted_at,
+ version=invitation.version + 1,
)
self.store.save_family_invitation(accepted)
self._record_mutation(
@@ -2709,6 +2782,73 @@ class UserEngineService:
def outbox_events(self) -> tuple[OutboxEvent, ...]:
return self.store.pending_outbox()
+ def deliver_outbox(
+ self,
+ actor: Actor,
+ deliver: Callable[[OutboxEvent], None],
+ *,
+ worker_id: str,
+ max_attempts: int = 3,
+ correlation_id: str | None = None,
+ ) -> tuple[OutboxEvent, ...]:
+ """Claim and deliver pending events, retaining bounded failure details."""
+ if not worker_id.strip():
+ raise ValidationError("outbox worker_id is required")
+ if not 1 <= max_attempts <= 20:
+ raise ValidationError("outbox max_attempts must be between 1 and 20")
+ correlation_id = correlation_id or new_id("corr")
+ self._authorize(
+ actor, action="outbox.deliver", resource_type="user-engine:outbox",
+ resource_id="pending", tenant=actor.tenant,
+ correlation_id=correlation_id,
+ )
+ results: list[OutboxEvent] = []
+ for event in self.store.pending_outbox():
+ claimed = replace(
+ event, claimed_by=worker_id, claimed_at=utc_now(),
+ delivery_attempts=event.delivery_attempts + 1,
+ failed_at=None, failure_reason=None,
+ )
+ with self.store.transaction():
+ self.store.save_outbox(claimed)
+ try:
+ deliver(claimed)
+ except Exception as exc:
+ reason = str(exc).strip()[:200] or type(exc).__name__
+ failed = replace(
+ claimed, failed_at=utc_now(), failure_reason=reason,
+ dead_lettered_at=(utc_now() if claimed.delivery_attempts >= max_attempts else None),
+ )
+ with self.store.transaction():
+ self.store.save_outbox(failed)
+ results.append(failed)
+ else:
+ delivered = replace(claimed, delivered_at=utc_now())
+ with self.store.transaction():
+ self.store.save_outbox(delivered)
+ results.append(delivered)
+ return tuple(results)
+
+ def replay_outbox(
+ self, actor: Actor, event_id: str, *, correlation_id: str | None = None
+ ) -> OutboxEvent:
+ correlation_id = correlation_id or new_id("corr")
+ event = self.store.outbox_event(event_id)
+ if event is None:
+ raise NotFoundError("outbox event not found")
+ self.resolve_tenant_context(actor, event.tenant)
+ self._authorize(
+ actor, action="outbox.replay", resource_type="user-engine:outbox-event",
+ resource_id=event_id, tenant=event.tenant, correlation_id=correlation_id,
+ )
+ replayed = replace(
+ event, claimed_by=None, claimed_at=None, failed_at=None,
+ failure_reason=None, dead_lettered_at=None,
+ )
+ with self.store.transaction():
+ self.store.save_outbox(replayed)
+ return replayed
+
def outbox_diagnostics(self) -> OutboxDiagnostics:
event_types: dict[str, int] = {}
pending = self.store.pending_outbox()
@@ -4728,6 +4868,8 @@ def _family_profile_key(catalog_namespace: str, key: str) -> str:
def _family_role_value(role: FamilyRole | str) -> str:
+ if str(role) in {"user", TENANT_ADMIN_ROLE}:
+ return str(role)
try:
return FamilyRole(str(role)).value
except ValueError as exc:
diff --git a/src/user_engine/web.py b/src/user_engine/web.py
index 2067c85..6e60883 100644
--- a/src/user_engine/web.py
+++ b/src/user_engine/web.py
@@ -17,11 +17,11 @@ import secrets
from typing import Any, Callable, Iterable, Mapping
from urllib.parse import parse_qs, urlencode
-from user_engine.domain import AccountStatus
+from user_engine.domain import AccountStatus, FamilyMemberSpec
from user_engine.errors import AuthorizationDenied, ConflictError, NotFoundError, ValidationError
from user_engine.oidc import OIDCClient, cookie_value
-from user_engine.ports import IdentityProvisioningPort, ProvisioningRequest
-from user_engine.service import UserEngineService
+from user_engine.ports import IdentityProvisioningPort, ProvisioningRequest, TenantManagementPort
+from user_engine.service import PLATFORM_TENANT, UserEngineService
StartResponse = Callable[[str, list[tuple[str, str]]], Any]
@@ -52,6 +52,8 @@ class PortalApplication:
public_registration: bool = True,
oidc_client: OIDCClient | None = None,
provisioning: IdentityProvisioningPort | None = None,
+ tenant_management: TenantManagementPort | None = None,
+ outbox_delivery: Callable[[Any], None] | None = None,
) -> None:
if len(trusted_proxy_secret) < 24:
raise ValueError("trusted proxy secret must contain at least 24 characters")
@@ -61,12 +63,16 @@ class PortalApplication:
self.public_registration = public_registration
self.oidc_client = oidc_client
self.provisioning = provisioning
+ self.tenant_management = tenant_management
+ self.outbox_delivery = outbox_delivery
def __call__(self, environ: Mapping[str, Any], start_response: StartResponse) -> Iterable[bytes]:
correlation_id = environ.get("HTTP_X_REQUEST_ID") or f"corr_{secrets.token_hex(12)}"
try:
return self._dispatch(environ, start_response, str(correlation_id))
- except (ValidationError, ConflictError, ValueError) as exc:
+ except ConflictError as exc:
+ return self._error(start_response, "409 Conflict", "conflict", str(exc), correlation_id)
+ except (ValidationError, ValueError) as exc:
return self._error(start_response, "400 Bad Request", "invalid_request", str(exc), correlation_id)
except RuntimeError:
return self._error(
@@ -97,7 +103,14 @@ class PortalApplication:
raise AuthorizationDenied("metrics require the trusted workload marker")
return self._metrics(start_response, correlation_id)
if path in {"/login", "/oidc/start"}:
- location = self.oidc_client.begin() if self.oidc_client else self.login_url
+ query = parse_qs(str(environ.get("QUERY_STRING", "")))
+ tenant_hint = query.get("tenant_hint", [None])[0]
+ if tenant_hint is not None and not str(tenant_hint).startswith("tenant:"):
+ raise ValidationError("tenant_hint must be a tenant identifier")
+ location = (
+ self.oidc_client.begin(tenant_hint=str(tenant_hint) if tenant_hint else None)
+ if self.oidc_client else self.login_url
+ )
start_response("303 See Other", [("Location", location), *self._security_headers(correlation_id)])
return [b""]
if path == "/oidc/callback":
@@ -133,6 +146,196 @@ class PortalApplication:
actor = self._actor(environ)
if path == "/api/v1/me" and method == "GET":
return self._json(start_response, "200 OK", _jsonable(self.service.me(self._claims(environ), correlation_id=correlation_id)), correlation_id)
+ if path == "/api/v1/me/profile" and method == "PATCH":
+ self._idempotency_key(environ)
+ self.service.me(self._claims(environ), correlation_id=correlation_id)
+ body = self._body(environ)
+ updated = self.service.update_self_service_profile(
+ actor, display_name=str(body.get("display_name", "")),
+ consent_accepted=bool(body.get("consent_accepted", False)),
+ consent_version=str(body.get("consent_version") or "portal-terms-v1"),
+ correlation_id=correlation_id,
+ )
+ return self._json(start_response, "200 OK", _jsonable(updated), correlation_id)
+ if path == "/onboarding" and method == "GET":
+ session = self.service.me(self._claims(environ), correlation_id=correlation_id)
+ memberships = self.service.store.memberships_for_user(session.user.user_id)
+ journeys = self.service.store.onboarding_journeys_for_user(session.user.user_id)
+ query = parse_qs(str(environ.get("QUERY_STRING", "")))
+ selected_tenant = query.get("tenant", [session.actor.tenant])[0]
+ allowed_tenants = {item.tenant for item in memberships} | {session.actor.tenant}
+ if selected_tenant not in allowed_tenants:
+ raise AuthorizationDenied("tenant selection is not a membership")
+ return self._html(
+ start_response,
+ self._onboarding(
+ session, memberships, journeys, str(selected_tenant),
+ self._csrf_token(environ),
+ ),
+ correlation_id,
+ )
+ if path == "/onboarding/profile" and method == "POST":
+ body = self._form_body(environ)
+ self._require_csrf(environ, str(body.get("csrf_token", "")))
+ self.service.me(self._claims(environ), correlation_id=correlation_id)
+ self.service.update_self_service_profile(
+ actor, display_name=str(body.get("display_name", "")),
+ consent_accepted=body.get("consent_accepted") == "yes",
+ consent_version="portal-terms-v1",
+ correlation_id=correlation_id,
+ )
+ return self._redirect(start_response, "/onboarding", correlation_id)
+ if path.startswith("/onboarding/") and "/steps/" in path and path.endswith("/complete") and method == "POST":
+ body = self._form_body(environ)
+ self._require_csrf(environ, str(body.get("csrf_token", "")))
+ parts = path.split("/")
+ journey_id, step_key = parts[2], parts[4]
+ session = self.service.me(self._claims(environ), correlation_id=correlation_id)
+ journey = self.service.store.onboarding_journey(journey_id)
+ if journey is None or journey.user_id != session.user.user_id:
+ raise NotFoundError("onboarding journey not found")
+ step = next((item for item in journey.steps if item.step_key == step_key), None)
+ if step is None:
+ raise NotFoundError("onboarding step not found")
+ if step.subsystem != "user-engine" or step.handoff is not None:
+ raise AuthorizationDenied("subsystem-owned steps require their handoff")
+ self.service.complete_onboarding_step(
+ actor, journey_id, step_key, correlation_id=correlation_id
+ )
+ return self._redirect(start_response, "/onboarding", correlation_id)
+ if path.startswith("/invitations/") and method == "GET":
+ invitation = self.service.store.family_invitation(path.split("/")[2])
+ if invitation is None:
+ raise NotFoundError("invitation not found")
+ self.service.resolve_tenant_context(actor, invitation.tenant)
+ return self._html(
+ start_response,
+ self._invitation_acceptance(invitation, self._csrf_token(environ)),
+ correlation_id,
+ )
+ if path.startswith("/invitations/") and method == "POST":
+ body = self._form_body(environ)
+ self._require_csrf(environ, str(body.get("csrf_token", "")))
+ self.service.accept_family_invitation(
+ self._claims(environ), path.split("/")[2], correlation_id=correlation_id
+ )
+ return self._redirect(start_response, "/onboarding", correlation_id)
+ if path == "/api/v1/platform/tenants" and method == "POST":
+ self.service.resolve_tenant_context(actor, PLATFORM_TENANT)
+ if self.tenant_management is None:
+ raise ValidationError("tenant management is unavailable")
+ idempotency_key = self._idempotency_key(environ)
+ body = self._body(environ)
+ tenant = str(body.get("tenant") or "")
+ if not tenant.startswith("tenant:") or tenant == PLATFORM_TENANT:
+ raise ValidationError("a non-platform tenant identifier is required")
+ result = self.tenant_management.create_tenant(
+ tenant=tenant,
+ display_name=str(body.get("display_name") or tenant),
+ idempotency_key=idempotency_key,
+ correlation_id=correlation_id,
+ )
+ admin = body.get("first_admin")
+ bootstrap = None
+ if admin is not None:
+ if not isinstance(admin, Mapping):
+ raise ValidationError("first_admin must be an object")
+ user = self.service.create_user(
+ actor, display_name=admin.get("display_name"),
+ primary_email=admin.get("primary_email"),
+ correlation_id=correlation_id,
+ )
+ account = self.service.set_tenant_account_status(
+ actor, user.user_id, AccountStatus.INVITED,
+ tenant=tenant, correlation_id=correlation_id,
+ )
+ membership = self.service.add_membership(
+ actor, user.user_id, tenant=tenant, scope_type="tenant",
+ scope_id=tenant, kind="tenant-admin",
+ correlation_id=correlation_id,
+ )
+ bootstrap = {"user": user, "tenant_account": account, "membership": membership}
+ return self._json(start_response, "201 Created", {
+ "tenant": _jsonable(result), "first_admin": _jsonable(bootstrap),
+ }, correlation_id)
+ if path == "/api/v1/platform/outbox/deliver" and method == "POST":
+ self.service.resolve_tenant_context(actor, PLATFORM_TENANT)
+ if self.outbox_delivery is None:
+ raise ValidationError("outbox delivery is unavailable")
+ body = self._body(environ)
+ events = self.service.deliver_outbox(
+ actor, self.outbox_delivery,
+ worker_id=str(body.get("worker_id") or "portal-operator"),
+ max_attempts=int(body.get("max_attempts") or 3),
+ correlation_id=correlation_id,
+ )
+ return self._json(start_response, "200 OK", {"items": _jsonable(events)}, correlation_id)
+ if path.startswith("/api/v1/platform/outbox/") and path.endswith("/replay") and method == "POST":
+ self.service.resolve_tenant_context(actor, PLATFORM_TENANT)
+ event = self.service.replay_outbox(
+ actor, path.split("/")[5], correlation_id=correlation_id
+ )
+ return self._json(start_response, "200 OK", _jsonable(event), correlation_id)
+ if path.startswith("/api/v1/platform/tenants/") and path.endswith("/recover") and method == "POST":
+ self.service.resolve_tenant_context(actor, PLATFORM_TENANT)
+ if self.provisioning is None:
+ raise ValidationError("identity provisioning is unavailable")
+ parts = path.split("/")
+ tenant, user_id = parts[5], parts[7]
+ idempotency_key = self._idempotency_key(environ)
+ user = self.service.store.user(user_id)
+ if user is None:
+ raise NotFoundError("user not found")
+ request = ProvisioningRequest(
+ user_id=user_id, tenant=tenant, primary_email=user.primary_email,
+ display_name=user.display_name, idempotency_key=idempotency_key,
+ correlation_id=correlation_id,
+ roles=tuple(item.kind for item in self.service.store.memberships_for_user(user_id, tenant=tenant)),
+ )
+ identity = next(iter(self.service.store.identities_for_user(user_id)), None)
+ if identity is None:
+ provisioned = self.provisioning.provision(request)
+ self.service.link_identity(
+ actor, user_id, issuer="urn:netkingdom:directory",
+ subject=provisioned.external_subject, provider=provisioned.provider,
+ correlation_id=correlation_id,
+ )
+ recovery = {"status": provisioned.status, "changed": ("identity",)}
+ else:
+ reconciled = self.provisioning.reconcile(
+ request, external_subject=identity.subject, desired_status="active"
+ )
+ recovery = {"status": reconciled.status, "drift": reconciled.drift, "changed": reconciled.changed}
+ account = self.service.set_tenant_account_status(
+ actor, user_id, AccountStatus.ACTIVE, tenant=tenant,
+ correlation_id=correlation_id,
+ )
+ return self._json(start_response, "200 OK", {
+ "recovery": _jsonable(recovery), "tenant_account": _jsonable(account),
+ }, correlation_id)
+ if path.startswith("/api/v1/invitations/") and path.endswith("/claim") and method == "POST":
+ invitation_id = path.split("/")[4]
+ accepted = self.service.accept_family_invitation(
+ self._claims(environ), invitation_id, correlation_id=correlation_id
+ )
+ return self._json(start_response, "200 OK", _jsonable(accepted), correlation_id)
+ if path.startswith("/api/v1/onboarding/") and "/steps/" in path and path.endswith("/complete") and method == "POST":
+ self._idempotency_key(environ)
+ parts = path.split("/")
+ journey_id, step_key = parts[4], parts[6]
+ session = self.service.me(self._claims(environ), correlation_id=correlation_id)
+ journey = self.service.store.onboarding_journey(journey_id)
+ if journey is None or journey.user_id != session.user.user_id:
+ raise NotFoundError("onboarding journey not found")
+ step = next((item for item in journey.steps if item.step_key == step_key), None)
+ if step is None:
+ raise NotFoundError("onboarding step not found")
+ if step.subsystem != "user-engine" or step.handoff is not None:
+ raise AuthorizationDenied("subsystem-owned steps require their handoff")
+ updated = self.service.complete_onboarding_step(
+ actor, journey_id, step_key, correlation_id=correlation_id
+ )
+ return self._json(start_response, "200 OK", _jsonable(updated), correlation_id)
if path == "/api/v1/registrations" and method == "POST":
if not self.public_registration:
raise AuthorizationDenied("public registration disabled")
@@ -198,6 +401,45 @@ class PortalApplication:
"membership": _jsonable(membership),
"provisioning_status": "pending",
}, correlation_id)
+ if path.startswith("/api/v1/tenants/") and path.endswith("/invitations"):
+ tenant = path.split("/")[4]
+ self.service.resolve_tenant_context(actor, tenant)
+ if method == "GET":
+ items = self.service.store.family_invitations_for_tenant(tenant)
+ return self._json(start_response, "200 OK", {"items": _jsonable(items)}, correlation_id)
+ if method == "POST":
+ body = self._body(environ)
+ invited = self.service.invite_family_member(
+ actor,
+ tenant=tenant,
+ family_scope_id=str(body.get("scope_id") or tenant),
+ application_id=str(body.get("application_id") or "app.user-portal"),
+ member=FamilyMemberSpec(
+ primary_email=str(body.get("primary_email") or ""),
+ display_name=body.get("display_name"),
+ role=str(body.get("role") or "user"),
+ ),
+ correlation_id=correlation_id,
+ )
+ return self._json(start_response, "201 Created", _jsonable(invited), correlation_id)
+ if path.startswith("/api/v1/tenants/") and "/invitations/" in path and method == "POST":
+ parts = path.split("/")
+ tenant, invitation_id, action = parts[4], parts[6], parts[7]
+ self.service.resolve_tenant_context(actor, tenant)
+ expected = self._expected_version(environ)
+ if action == "resend":
+ value = self.service.resend_family_invitation(
+ actor, invitation_id, correlation_id=correlation_id,
+ expected_version=expected,
+ )
+ elif action == "expire":
+ value = self.service.revoke_family_invitation(
+ actor, invitation_id, correlation_id=correlation_id,
+ expected_version=expected,
+ )
+ else:
+ raise NotFoundError("invitation action not found")
+ return self._json(start_response, "200 OK", _jsonable(value), correlation_id)
if path.startswith("/api/v1/tenants/") and path.endswith("/provision") and method == "POST":
if self.provisioning is None:
raise ValidationError("identity provisioning is unavailable")
@@ -250,13 +492,80 @@ class PortalApplication:
correlation_id=correlation_id,
)
return self._json(start_response, "200 OK", _jsonable(result), correlation_id)
+ if path.startswith("/api/v1/tenants/") and "/users/" in path and method == "DELETE":
+ if self.provisioning is None:
+ raise ValidationError("identity provisioning is unavailable")
+ parts = path.split("/")
+ tenant, user_id = parts[4], parts[6]
+ self.service.resolve_tenant_context(actor, tenant)
+ idempotency_key = str(environ.get("HTTP_IDEMPOTENCY_KEY", ""))
+ if len(idempotency_key) < 16:
+ raise ValidationError("Idempotency-Key must contain at least 16 characters")
+ identity = next(iter(self.service.store.identities_for_user(user_id)), None)
+ if identity is not None:
+ self.provisioning.deprovision(
+ external_subject=identity.subject,
+ idempotency_key=idempotency_key,
+ correlation_id=correlation_id,
+ )
+ account = self.service.set_tenant_account_status(
+ actor, user_id, AccountStatus.DISABLED,
+ tenant=tenant, correlation_id=correlation_id,
+ )
+ return self._json(start_response, "200 OK", {
+ "status": "removed", "tenant_account": _jsonable(account),
+ "provider_identity_removed": identity is not None,
+ }, correlation_id)
+ if path == "/platform" and method == "GET":
+ self.service.resolve_tenant_context(actor, PLATFORM_TENANT)
+ return self._html(
+ start_response, self._platform(self._csrf_token(environ)), correlation_id
+ )
+ if path == "/platform/tenants" and method == "POST":
+ self.service.resolve_tenant_context(actor, PLATFORM_TENANT)
+ if self.tenant_management is None:
+ raise ValidationError("tenant management is unavailable")
+ body = self._form_body(environ)
+ self._require_csrf(environ, str(body.get("csrf_token", "")))
+ tenant = str(body.get("tenant", ""))
+ if not tenant.startswith("tenant:") or tenant == PLATFORM_TENANT:
+ raise ValidationError("a non-platform tenant identifier is required")
+ result = self.tenant_management.create_tenant(
+ tenant=tenant, display_name=str(body.get("display_name") or tenant),
+ idempotency_key=f"portal-tenant-{tenant}", correlation_id=correlation_id,
+ )
+ email = str(body.get("admin_email", ""))
+ if email:
+ user = self.service.create_user(
+ actor, display_name=body.get("admin_display_name"),
+ primary_email=email, correlation_id=correlation_id,
+ )
+ self.service.set_tenant_account_status(
+ actor, user.user_id, AccountStatus.INVITED,
+ tenant=tenant, correlation_id=correlation_id,
+ )
+ self.service.add_membership(
+ actor, user.user_id, tenant=tenant, scope_type="tenant",
+ scope_id=tenant, kind="tenant-admin", correlation_id=correlation_id,
+ )
+ return self._html(
+ start_response,
+ self._platform_result(result, tenant, bool(email)), correlation_id,
+ )
if path.startswith("/admin/") and method == "GET":
tenant = path.split("/")[2]
self.service.resolve_tenant_context(actor, tenant)
memberships = self.service.store.memberships_for_tenant(tenant)
+ invitations = self.service.store.family_invitations_for_tenant(tenant)
+ diagnostics = self.service.tenant_diagnostics(
+ actor, tenant=tenant, correlation_id=correlation_id
+ )
return self._html(
start_response,
- self._admin(tenant, memberships, self._csrf_token(environ)),
+ self._admin(
+ tenant, memberships, invitations, diagnostics,
+ "platform-operator" in actor.roles, self._csrf_token(environ),
+ ),
correlation_id,
)
if path.startswith("/admin/") and method == "POST":
@@ -282,6 +591,33 @@ class PortalApplication:
correlation_id=correlation_id,
)
return self._redirect(start_response, f"/admin/{tenant}", correlation_id)
+ if len(parts) == 4 and parts[3] == "invitations":
+ self.service.invite_family_member(
+ actor, tenant=tenant, family_scope_id=tenant,
+ application_id="app.user-portal",
+ member=FamilyMemberSpec(
+ primary_email=str(body.get("primary_email", "")),
+ display_name=body.get("display_name"),
+ role=str(body.get("role", "user")),
+ ), correlation_id=correlation_id,
+ )
+ return self._redirect(start_response, f"/admin/{tenant}", correlation_id)
+ if len(parts) == 6 and parts[3] == "invitations":
+ invitation_id, action = parts[4], parts[5]
+ version = int(body.get("version", "0"))
+ if action == "resend":
+ self.service.resend_family_invitation(
+ actor, invitation_id, expected_version=version,
+ correlation_id=correlation_id,
+ )
+ elif action == "expire":
+ self.service.revoke_family_invitation(
+ actor, invitation_id, expected_version=version,
+ correlation_id=correlation_id,
+ )
+ else:
+ raise NotFoundError("invitation action not found")
+ return self._redirect(start_response, f"/admin/{tenant}", correlation_id)
if len(parts) == 6 and parts[3] == "users" and parts[5] == "provision":
if self.provisioning is None:
raise ValidationError("identity provisioning is unavailable")
@@ -327,6 +663,54 @@ class PortalApplication:
correlation_id=correlation_id,
)
return self._redirect(start_response, f"/admin/{tenant}", correlation_id)
+ if len(parts) == 6 and parts[3] == "users" and parts[5] == "remove":
+ if self.provisioning is None:
+ raise ValidationError("identity provisioning is unavailable")
+ user_id = parts[4]
+ identity = next(iter(self.service.store.identities_for_user(user_id)), None)
+ if identity is not None:
+ self.provisioning.deprovision(
+ external_subject=identity.subject,
+ idempotency_key=f"portal-remove-{tenant}-{user_id}",
+ correlation_id=correlation_id,
+ )
+ self.service.set_tenant_account_status(
+ actor, user_id, AccountStatus.DISABLED,
+ tenant=tenant, correlation_id=correlation_id,
+ )
+ return self._redirect(start_response, f"/admin/{tenant}", correlation_id)
+ if len(parts) == 6 and parts[3] == "users" and parts[5] == "recover":
+ self.service.resolve_tenant_context(actor, PLATFORM_TENANT)
+ if self.provisioning is None:
+ raise ValidationError("identity provisioning is unavailable")
+ user_id = parts[4]
+ user = self.service.store.user(user_id)
+ if user is None:
+ raise NotFoundError("user not found")
+ request = ProvisioningRequest(
+ user_id=user_id, tenant=tenant, primary_email=user.primary_email,
+ display_name=user.display_name,
+ idempotency_key=f"portal-recover-{tenant}-{user_id}",
+ correlation_id=correlation_id,
+ roles=tuple(item.kind for item in self.service.store.memberships_for_user(user_id, tenant=tenant)),
+ )
+ identity = next(iter(self.service.store.identities_for_user(user_id)), None)
+ if identity is None:
+ result = self.provisioning.provision(request)
+ self.service.link_identity(
+ actor, user_id, issuer="urn:netkingdom:directory",
+ subject=result.external_subject, provider=result.provider,
+ correlation_id=correlation_id,
+ )
+ else:
+ self.provisioning.reconcile(
+ request, external_subject=identity.subject, desired_status="active"
+ )
+ self.service.set_tenant_account_status(
+ actor, user_id, AccountStatus.ACTIVE,
+ tenant=tenant, correlation_id=correlation_id,
+ )
+ return self._redirect(start_response, f"/admin/{tenant}?recovered={user_id}", correlation_id)
return self._error(start_response, "404 Not Found", "not_found", "Resource not found.", correlation_id)
def _change_status(
@@ -435,9 +819,24 @@ class PortalApplication:
limit = max(1, min(100, int(query.get("limit", ["25"])[0])))
return offset, limit
+ @staticmethod
+ def _expected_version(environ: Mapping[str, Any]) -> int:
+ value = str(environ.get("HTTP_IF_MATCH", "")).strip().strip('"')
+ if not value.isdigit():
+ raise ValidationError("If-Match invitation version is required")
+ return int(value)
+
+ @staticmethod
+ def _idempotency_key(environ: Mapping[str, Any]) -> str:
+ value = str(environ.get("HTTP_IDEMPOTENCY_KEY", ""))
+ if len(value) < 16:
+ raise ValidationError("Idempotency-Key must contain at least 16 characters")
+ return value
+
def _home(self, actor: Any | None) -> str:
identity = (
f"Signed in as {escape(actor.preferred_username)} .
"
+ 'Continue onboarding
'
if actor is not None
else f'Sign in with KeyCape
'
)
@@ -448,11 +847,22 @@ class PortalApplication:
+ identity,
)
- def _admin(self, tenant: str, memberships: tuple[Any, ...], csrf_token: str) -> str:
+ def _admin(
+ self, tenant: str, memberships: tuple[Any, ...],
+ invitations: tuple[Any, ...], diagnostics: Any,
+ platform_operator: bool, csrf_token: str,
+ ) -> str:
rows = "".join(
- self._admin_row(tenant, item, csrf_token)
+ self._admin_row(tenant, item, platform_operator, csrf_token)
for item in memberships
) or 'No members yet. No invitations yet. {escape(item.replace('_', ' '))} " for item in diagnostics.issues
+ ) or "No lifecycle gaps detected. "
return self._page_html(
f"{tenant} users",
f"""{escape(tenant)} users
@@ -463,10 +873,35 @@ class PortalApplication:
Email
Role User Tenant administrator
Add user
+
+Invitations Email Role Status Expires Action {invitation_rows}
Lifecycle diagnostics Diagnostics contain machine-readable gap categories only; credentials and factor evidence are never displayed.
Members User Email Role Status Directory Action {rows}
{escape(invitation.primary_email)} {escape(invitation.role)} "
+ f"{escape(invitation.status.value)} {escape(expires)} {actions} Create login """
)
+ action += f""""""
+ if platform_operator:
+ action += f""""""
return (
f"{escape(user.display_name or membership.user_id) if user else escape(membership.user_id)} "
f"{escape(user.primary_email or '') if user else ''} "
@@ -497,6 +939,98 @@ class PortalApplication:
f"{'linked' if directory else 'pending'} {action} Join {escape(invitation.tenant)}
+You were invited as {escape(invitation.role)} . The invitation expires at {escape(invitation.expires_at.isoformat() if invitation.expires_at else 'the tenant policy deadline')}.
+
+Your password and MFA remain on the identity-provider surface.
""",
+ )
+
+ def _platform(self, csrf_token: str) -> str:
+ return self._page_html(
+ "Platform administration",
+ f"""Platform administration
+""",
+ )
+
+ def _platform_result(self, result: Any, tenant: str, admin_prepared: bool) -> str:
+ return self._page_html(
+ "Tenant created",
+ f"""Tenant {escape(result.status)}
+{escape(tenant)} was processed by the tenant authority.
+{'The first administrator is prepared and awaiting onboarding.' if admin_prepared else 'No first administrator was requested.'}
+Open tenant administration
+Return to platform administration
""",
+ )
+
+ def _onboarding(
+ self, session: Any, memberships: tuple[Any, ...], journeys: tuple[Any, ...],
+ selected_tenant: str, csrf_token: str,
+ ) -> str:
+ membership_items = "".join(
+ f"{escape(item.tenant)} — {escape(item.kind)}No tenant memberships yet. "
+ journey_items = "".join(
+ self._onboarding_journey_item(item, csrf_token) for item in journeys
+ ) or "No additional onboarding steps are required. "
+ verification = "Verified by your identity provider" if session.actor.assurance else "Verification pending"
+ consent_checked = " checked" if session.user.consented_at else ""
+ return self._page_html(
+ "Onboarding",
+ f"""Welcome, {escape(session.user.display_name or session.actor.preferred_username or session.user.user_id)}
+Email and sign-in {escape(verification)}
Passwords and MFA are managed by your identity provider.
{escape(journey.status.value)} "
+ f"{steps} Continue on the provider-owned surface; this page will resume after its callback. "
+ gap = f" Support category: {escape(step.lifecycle_gap)} " if step.lifecycle_gap else ""
+ return (
+ f"{escape(step.title)} — {escape(step.status.value)} {gap}{action}", html)
def test_metrics_expose_only_bounded_aggregate_state(self):
denied, _ = invoke(self.app, "/metrics", claims={}, marker="")
@@ -93,12 +109,61 @@ class PortalApplicationTests(unittest.TestCase):
self.assertEqual("403 Forbidden", result["status"])
self.assertNotIn(b"attacker", payload)
+ def test_expired_browser_session_and_provider_outage_fail_closed(self):
+ oidc = OIDCClient(
+ issuer="https://kc.example", client_id="portal",
+ redirect_uri="https://users.example/oidc/callback", audience="portal",
+ )
+ oidc.sessions["expired"] = BrowserSession(
+ claims=self.claims, expires_at=0, csrf_token="expired-csrf"
+ )
+ self.app.oidc_client = oidc
+ expired, _ = invoke(
+ self.app, "/onboarding", cookie="ue_session=expired"
+ )
+ self.assertEqual("403 Forbidden", expired["status"])
+
+ self.app.oidc_client = None
+ self.app.provisioning = FailingProvisioning()
+ created, payload = invoke(
+ self.app, "/api/v1/tenants/tenant:friendly:binky/users",
+ method="POST", claims=self.claims,
+ body={"primary_email": "failure@example.test", "role": "user"},
+ )
+ user_id = json.loads(payload)["user"]["user_id"]
+ before = self.app.service.store.tenant_account(
+ "tenant:friendly:binky", user_id
+ ).status
+ failed, payload = invoke_with_idempotency(
+ self.app,
+ f"/api/v1/tenants/tenant:friendly:binky/users/{user_id}/provision",
+ self.claims,
+ )
+ self.assertEqual("502 Bad Gateway", failed["status"])
+ self.assertNotIn(b"provider-secret", payload)
+ self.assertEqual(
+ before,
+ self.app.service.store.tenant_account(
+ "tenant:friendly:binky", user_id
+ ).status,
+ )
+
def test_verified_claims_create_current_user(self):
result, payload = invoke(self.app, "/api/v1/me", claims=self.claims)
self.assertEqual("200 OK", result["status"])
decoded = json.loads(payload)
self.assertEqual("tenant:friendly:binky", decoded["actor"]["tenant"])
+ updated, payload = invoke_with_idempotency(
+ self.app, "/api/v1/me/profile", self.claims, method="PATCH",
+ body={
+ "display_name": "Sample Person", "consent_accepted": True,
+ "consent_version": "portal-terms-v1",
+ },
+ )
+ self.assertEqual("200 OK", updated["status"])
+ self.assertEqual("Sample Person", json.loads(payload)["display_name"])
+
def test_registration_api_is_correlated(self):
result, payload = invoke(
self.app,
@@ -151,6 +216,217 @@ class PortalApplicationTests(unittest.TestCase):
self.assertEqual("200 OK", changed["status"])
self.assertEqual("suspended", json.loads(payload)["status"])
self.assertIn(("suspend", "ada"), self.app.provisioning.actions)
+ removed, payload = invoke_with_idempotency(
+ self.app,
+ f"/api/v1/tenants/tenant:friendly:binky/users/{user_id}",
+ self.claims, method="DELETE",
+ )
+ self.assertEqual("200 OK", removed["status"])
+ self.assertEqual("removed", json.loads(payload)["status"])
+ self.assertIn(("deprovision", "ada"), self.app.provisioning.actions)
+
+ def test_invitation_lifecycle_is_versioned_and_replay_safe(self):
+ created, payload = invoke(
+ self.app,
+ "/api/v1/tenants/tenant:friendly:binky/invitations",
+ method="POST", claims=self.claims,
+ body={"primary_email": "invitee@example.test", "role": "user"},
+ )
+ self.assertEqual("201 Created", created["status"])
+ invitation = json.loads(payload)["invitation"]
+ invitation_id = invitation["invitation_id"]
+ self.assertEqual(1, invitation["version"])
+ self.assertIsNotNone(invitation["expires_at"])
+
+ duplicate, _ = invoke(
+ self.app,
+ "/api/v1/tenants/tenant:friendly:binky/invitations",
+ method="POST", claims=self.claims,
+ body={"primary_email": "INVITEE@example.test", "role": "user"},
+ )
+ self.assertEqual("409 Conflict", duplicate["status"])
+
+ listed, payload = invoke(
+ self.app, "/api/v1/tenants/tenant:friendly:binky/invitations",
+ claims=self.claims,
+ )
+ self.assertEqual("200 OK", listed["status"])
+ self.assertEqual(1, len(json.loads(payload)["items"]))
+
+ resent, payload = invoke(
+ self.app,
+ f"/api/v1/tenants/tenant:friendly:binky/invitations/{invitation_id}/resend",
+ method="POST", claims=self.claims, headers={"HTTP_IF_MATCH": '"1"'},
+ )
+ self.assertEqual("200 OK", resent["status"])
+ self.assertEqual(2, json.loads(payload)["version"])
+ conflict, _ = invoke(
+ self.app,
+ f"/api/v1/tenants/tenant:friendly:binky/invitations/{invitation_id}/expire",
+ method="POST", claims=self.claims, headers={"HTTP_IF_MATCH": '"1"'},
+ )
+ self.assertEqual("409 Conflict", conflict["status"])
+ expired, payload = invoke(
+ self.app,
+ f"/api/v1/tenants/tenant:friendly:binky/invitations/{invitation_id}/expire",
+ method="POST", claims=self.claims, headers={"HTTP_IF_MATCH": '"2"'},
+ )
+ self.assertEqual("200 OK", expired["status"])
+ self.assertEqual("revoked", json.loads(payload)["status"])
+
+ claimable, payload = invoke(
+ self.app, "/api/v1/tenants/tenant:friendly:binky/invitations",
+ method="POST", claims=self.claims,
+ body={"primary_email": "sample.user@example.test", "role": "user"},
+ )
+ self.assertEqual("201 Created", claimable["status"])
+ claim_id = json.loads(payload)["invitation"]["invitation_id"]
+ claimed, _ = invoke(
+ self.app, f"/api/v1/invitations/{claim_id}/claim",
+ method="POST", claims=self.claims,
+ )
+ self.assertEqual("200 OK", claimed["status"])
+ replayed, _ = invoke(
+ self.app, f"/api/v1/invitations/{claim_id}/claim",
+ method="POST", claims=self.claims,
+ )
+ self.assertEqual("400 Bad Request", replayed["status"])
+
+ timed, payload = invoke(
+ self.app, "/api/v1/tenants/tenant:friendly:binky/invitations",
+ method="POST", claims=self.claims,
+ body={"primary_email": "expired@example.test", "role": "user"},
+ )
+ timed_id = json.loads(payload)["invitation"]["invitation_id"]
+ timed_invitation = self.app.service.store.family_invitation(timed_id)
+ self.app.service.store.save_family_invitation(replace(
+ timed_invitation, expires_at=utc_now() - timedelta(seconds=1)
+ ))
+ expired_claims = dict(self.claims)
+ expired_claims["email"] = "expired@example.test"
+ timed_out, _ = invoke(
+ self.app, f"/api/v1/invitations/{timed_id}/claim",
+ method="POST", claims=expired_claims,
+ )
+ self.assertEqual("400 Bad Request", timed_out["status"])
+
+ def test_outbox_delivery_replay_and_dead_letter(self):
+ invoke(self.app, "/api/v1/me", claims=self.claims)
+ actor = self.app.service.identity_adapter.normalize(self.claims)
+ event = self.app.service.outbox_events()[0]
+
+ def unavailable(_event):
+ raise RuntimeError("notification provider unavailable; token=redacted")
+
+ first = self.app.service.deliver_outbox(
+ actor, unavailable, worker_id="worker-a", max_attempts=2
+ )[0]
+ self.assertEqual(1, first.delivery_attempts)
+ self.assertIsNotNone(first.failed_at)
+ self.assertIsNone(first.dead_lettered_at)
+ replayed = self.app.service.replay_outbox(actor, event.event_id)
+ self.assertIsNone(replayed.failure_reason)
+ second = self.app.service.deliver_outbox(
+ actor, unavailable, worker_id="worker-a", max_attempts=2
+ )[0]
+ self.assertIsNotNone(second.dead_lettered_at)
+ self.assertLessEqual(len(second.failure_reason), 200)
+
+ replayed = self.app.service.replay_outbox(actor, event.event_id)
+ delivered = self.app.service.deliver_outbox(
+ actor, lambda _event: None, worker_id="worker-b"
+ )[0]
+ self.assertEqual(replayed.event_id, delivered.event_id)
+ self.assertIsNotNone(delivered.delivered_at)
+ self.assertNotIn(delivered, self.app.service.outbox_events())
+
+ def test_platform_tenant_bootstrap_recovery_and_outbox_transport(self):
+ self.app.tenant_management = FakeTenantManagement()
+ self.app.provisioning = FakeProvisioning()
+ claims = self.platform_claims()
+ denied, _ = invoke_with_idempotency(
+ self.app, "/api/v1/platform/tenants", self.claims,
+ body={"tenant": "tenant:friendly:new", "display_name": "New"},
+ )
+ self.assertEqual("403 Forbidden", denied["status"])
+ created, payload = invoke_with_idempotency(
+ self.app, "/api/v1/platform/tenants", claims,
+ body={
+ "tenant": "tenant:friendly:new", "display_name": "New Tenant",
+ "first_admin": {"primary_email": "admin@new.test", "display_name": "Admin"},
+ },
+ )
+ self.assertEqual("201 Created", created["status"])
+ decoded = json.loads(payload)
+ self.assertEqual("created", decoded["tenant"]["status"])
+ self.assertEqual("tenant-admin", decoded["first_admin"]["membership"]["kind"])
+ user_id = decoded["first_admin"]["user"]["user_id"]
+ recovered, payload = invoke_with_idempotency(
+ self.app,
+ f"/api/v1/platform/tenants/tenant:friendly:new/users/{user_id}/recover",
+ claims,
+ )
+ self.assertEqual("200 OK", recovered["status"])
+ self.assertEqual("active", json.loads(payload)["tenant_account"]["status"])
+
+ self.app.outbox_delivery = lambda _event: None
+ delivered, payload = invoke(
+ self.app, "/api/v1/platform/outbox/deliver", method="POST",
+ claims=claims, body={"worker_id": "test-worker"},
+ )
+ self.assertEqual("200 OK", delivered["status"])
+ self.assertTrue(json.loads(payload)["items"])
+
+ def test_platform_browser_tenant_and_first_admin_bootstrap(self):
+ claims = self.platform_claims()
+ oidc = OIDCClient(
+ issuer="https://kc.example", client_id="portal",
+ redirect_uri="https://users.example/oidc/callback", audience="portal",
+ )
+ oidc.sessions["platform"] = BrowserSession(
+ claims=claims, expires_at=9999999999, csrf_token="platform-csrf",
+ )
+ self.app.oidc_client = oidc
+ self.app.tenant_management = FakeTenantManagement()
+ self.app.provisioning = FakeProvisioning()
+ page, html = invoke(self.app, "/platform", cookie="ue_session=platform")
+ self.assertEqual("200 OK", page["status"])
+ self.assertIn(b"First administrator", html)
+ denied, _ = invoke(
+ self.app, "/platform/tenants", method="POST",
+ cookie="ue_session=platform", form={
+ "csrf_token": "wrong", "tenant": "tenant:friendly:browser",
+ "display_name": "Browser Tenant",
+ },
+ )
+ self.assertEqual("403 Forbidden", denied["status"])
+ created, html = invoke(
+ self.app, "/platform/tenants", method="POST",
+ cookie="ue_session=platform", form={
+ "csrf_token": "platform-csrf", "tenant": "tenant:friendly:browser",
+ "display_name": "Browser Tenant", "admin_display_name": "First Admin",
+ "admin_email": "first-admin@browser.test",
+ },
+ )
+ self.assertEqual("200 OK", created["status"])
+ self.assertIn(b"awaiting onboarding", html)
+ memberships = self.app.service.store.memberships_for_tenant(
+ "tenant:friendly:browser"
+ )
+ self.assertEqual("tenant-admin", memberships[0].kind)
+ admin_page, html = invoke(
+ self.app, "/admin/tenant:friendly:browser", cookie="ue_session=platform"
+ )
+ self.assertEqual("200 OK", admin_page["status"])
+ self.assertIn(b"Lifecycle diagnostics", html)
+ self.assertIn(b"Recover identity", html)
+ recovered, _ = invoke(
+ self.app,
+ f"/admin/tenant:friendly:browser/users/{memberships[0].user_id}/recover",
+ method="POST", cookie="ue_session=platform",
+ form={"csrf_token": "platform-csrf"},
+ )
+ self.assertEqual("303 See Other", recovered["status"])
def test_admin_form_requires_csrf_and_supports_two_step_provisioning(self):
oidc = OIDCClient(
@@ -218,6 +494,112 @@ class PortalApplicationTests(unittest.TestCase):
)
self.assertEqual("200 OK", page["status"])
self.assertIn(b"Create password setup link", html)
+ self.assertIn(b"Invite a user", html)
+ self.assertIn(b"Remove account", html)
+
+ def test_browser_invitation_acceptance_and_onboarding_status(self):
+ oidc = OIDCClient(
+ issuer="https://kc.example", client_id="portal",
+ redirect_uri="https://users.example/oidc/callback", audience="portal",
+ )
+ oidc.sessions["browser"] = BrowserSession(
+ claims=self.claims, expires_at=9999999999, csrf_token="csrf-test-token",
+ )
+ self.app.oidc_client = oidc
+ created, _ = invoke(
+ self.app, "/admin/tenant:friendly:binky/invitations", method="POST",
+ cookie="ue_session=browser", form={
+ "csrf_token": "csrf-test-token", "display_name": "Invitee",
+ "primary_email": "invitee@example.test", "role": "user",
+ },
+ )
+ self.assertEqual("303 See Other", created["status"])
+ invitation = next(iter(self.app.service.store.family_invitations.values()))
+ page, html = invoke(
+ self.app, f"/invitations/{invitation.invitation_id}",
+ cookie="ue_session=browser",
+ )
+ self.assertEqual("200 OK", page["status"])
+ self.assertIn(b"Accept invitation", html)
+
+ wrong, _ = invoke(
+ self.app, f"/invitations/{invitation.invitation_id}", method="POST",
+ cookie="ue_session=browser", form={"csrf_token": "csrf-test-token"},
+ )
+ self.assertEqual("403 Forbidden", wrong["status"])
+ invitee_claims = human_actor_claims(
+ subject="invitee", tenant="tenant:friendly:binky"
+ )
+ invitee_claims["email"] = "invitee@example.test"
+ oidc.sessions["browser"] = BrowserSession(
+ claims=invitee_claims, expires_at=9999999999,
+ csrf_token="csrf-test-token",
+ )
+ accepted, _ = invoke(
+ self.app, f"/invitations/{invitation.invitation_id}", method="POST",
+ cookie="ue_session=browser", form={"csrf_token": "csrf-test-token"},
+ )
+ self.assertEqual("303 See Other", accepted["status"])
+ self.assertEqual("/onboarding", accepted["headers"]["Location"])
+ own_journey = OnboardingJourney(
+ tenant="tenant:friendly:binky", user_id=invitation.user_id,
+ protocol_id="protocol-self", trigger_type=OnboardingTriggerType.INVITATION,
+ status=OnboardingJourneyStatus.IN_PROGRESS, active_step_key="profile-review",
+ steps=(OnboardingStep(
+ step_key="profile-review", title="Review your profile",
+ subsystem="user-engine", status=OnboardingStepStatus.IN_PROGRESS,
+ ),),
+ )
+ provider_journey = OnboardingJourney(
+ tenant="tenant:friendly:binky", user_id=invitation.user_id,
+ protocol_id="protocol-provider", trigger_type=OnboardingTriggerType.INVITATION,
+ status=OnboardingJourneyStatus.BLOCKED, active_step_key="mfa",
+ steps=(OnboardingStep(
+ step_key="mfa", title="Enroll MFA", subsystem="key-cape",
+ status=OnboardingStepStatus.BLOCKED,
+ handoff=SubsystemHandoff(
+ subsystem="key-cape", status=OnboardingStepStatus.BLOCKED,
+ ),
+ ),),
+ )
+ self.app.service.store.save_onboarding_journey(own_journey)
+ self.app.service.store.save_onboarding_journey(provider_journey)
+ onboarding, html = invoke(
+ self.app, "/onboarding", cookie="ue_session=browser"
+ )
+ self.assertEqual("200 OK", onboarding["status"])
+ self.assertIn(b"Onboarding progress", html)
+ self.assertIn(b"tenant:friendly:binky", html)
+ self.assertIn(b"Profile and consent", html)
+ self.assertIn(b"Mark complete", html)
+ self.assertIn(b"provider-owned surface", html)
+ completed, _ = invoke(
+ self.app,
+ f"/onboarding/{own_journey.journey_id}/steps/profile-review/complete",
+ method="POST", cookie="ue_session=browser",
+ form={"csrf_token": "csrf-test-token"},
+ )
+ self.assertEqual("303 See Other", completed["status"])
+ provider_denied, _ = invoke(
+ self.app,
+ f"/onboarding/{provider_journey.journey_id}/steps/mfa/complete",
+ method="POST", cookie="ue_session=browser",
+ form={"csrf_token": "csrf-test-token"},
+ )
+ self.assertEqual("403 Forbidden", provider_denied["status"])
+ saved, _ = invoke(
+ self.app, "/onboarding/profile", method="POST",
+ cookie="ue_session=browser", form={
+ "csrf_token": "csrf-test-token", "display_name": "Updated Invitee",
+ "consent_accepted": "yes",
+ },
+ )
+ self.assertEqual("303 See Other", saved["status"])
+ user = self.app.service.store.user(invitation.user_id)
+ self.assertEqual("Updated Invitee", user.display_name)
+ self.assertEqual("invitee@example.test", user.primary_email)
+ self.assertEqual("portal-terms-v1", user.consent_version)
+ self.assertIsNotNone(user.profile_completed_at)
class FakeProvisioning:
@@ -241,6 +623,26 @@ class FakeProvisioning:
self.actions.append(("reactivate", external_subject))
return ProvisioningResult("netkingdom-lldap", external_subject, "active")
+ def deprovision(self, *, external_subject, idempotency_key, correlation_id):
+ self.actions.append(("deprovision", external_subject))
+ return ProvisioningResult("netkingdom-lldap", external_subject, "removed")
+
+ def reconcile(self, request, *, external_subject, desired_status="active"):
+ self.actions.append(("reconcile", external_subject))
+ return IdentityDriftResult(
+ "netkingdom-lldap", external_subject, "in_sync", changed=("status",)
+ )
+
+
+class FakeTenantManagement:
+ def create_tenant(self, *, tenant, display_name, idempotency_key, correlation_id):
+ return TenantProvisioningResult(tenant=tenant, status="created")
+
+
+class FailingProvisioning(FakeProvisioning):
+ def provision(self, request):
+ raise RuntimeError("provider-secret must never escape")
+
def invoke_with_idempotency(app, path, claims, *, method="POST", body=None):
payload = json.dumps(body or {}).encode()
diff --git a/workplans/USER-WP-0021-portal-product-expansion.md b/workplans/USER-WP-0021-portal-product-expansion.md
index 0dba8d3..084e238 100644
--- a/workplans/USER-WP-0021-portal-product-expansion.md
+++ b/workplans/USER-WP-0021-portal-product-expansion.md
@@ -4,11 +4,11 @@ type: workplan
title: "Expand user-engine portal beyond the proven Binky MVP"
domain: communication
repo: user-engine
-status: backlog
+status: active
owner: codex
topic_slug: netkingdom
created: "2026-07-30"
-updated: "2026-07-30"
+updated: "2026-08-08"
depends_on:
- USER-WP-0020
state_hub_workstream_id: "ba217f48-5fa5-4178-9c79-73aa225f3f2e"
@@ -23,7 +23,7 @@ holding the proven production MVP open. Activate according to tenant demand.
```task
id: USER-WP-0021-T01
-status: todo
+status: progress
priority: high
state_hub_task_id: "342299b8-d9a3-408d-bf0d-914496714d5f"
```
@@ -32,11 +32,25 @@ Add invitation claim/resend/expiry, platform tenant management and recovery
routes, optimistic concurrency, complete OpenAPI schemas, and durable outbox
delivery/replay/dead-letter operations.
+2026-08-08 increment: durable invitations now carry expiry and an optimistic
+version. The API supports tenant create/list, version-gated resend/expire, and
+authenticated claim with terminal-state and stale-version rejection. Outbox
+state now covers attempts, bounded failures, delivery, replay, and dead-letter
+through the store abstraction. OpenAPI 0.2 documents invitation and removal
+operations. Platform recovery breadth and an outbox operator transport remain.
+
+2026-08-08 follow-up: a provider-neutral `TenantManagementPort` now supports
+platform-operator tenant creation with optional first-admin preparation. A
+redacted recovery route recreates or reconciles provider identity state and
+reactivates tenant lifecycle, while authenticated operator routes dispatch and
+replay durable outbox events. Ordinary tenant users are denied these routes.
+Broader tenant update/retirement operations remain.
+
## T02 - Expand self-service onboarding UX
```task
id: USER-WP-0021-T02
-status: todo
+status: done
priority: medium
state_hub_task_id: "dc548cfb-db7c-4cbd-864f-2effeebc3dbd"
```
@@ -45,11 +59,34 @@ Add invitation acceptance, email-verification status, consent/profile,
tenant-selection, and fully resumable onboarding screens while keeping
password and MFA material on provider-owned surfaces.
+2026-08-08 increment: invitation claim is now a first-class authenticated API
+operation and preserves the provider-owned credential boundary. Dedicated
+browser screens for the fully resumable journey remain.
+
+2026-08-08 browser increment: authenticated users can review and accept an
+invitation through a CSRF-protected flow, then land on a responsive onboarding
+status screen showing provider verification, tenant memberships, and journey
+state. Acceptance binds the verified OIDC email to the invitation address.
+Consent/profile editing and tenant switching remain.
+
+2026-08-08 completion increment: self-service profile completion and versioned
+consent are now durable, audited, and emitted through the outbox; verified
+email remains immutable. Membership-scoped tenant selection is available for
+onboarding views, and a PKCE reauthentication handoff carries a tenant hint so
+the identity provider—not browser state—changes authoritative tenant context.
+Interactive completion of subsystem-owned journey steps remains.
+
+2026-08-08 completion: users can complete active user-engine-owned onboarding
+steps through API or CSRF-protected browser controls. Journey ownership is
+checked before mutation. Password, MFA, and other subsystem-owned steps expose
+handoff status only and cannot be completed from user-engine; their callbacks
+resume the durable journey. This completes the self-service onboarding scope.
+
## T03 - Expand administration UX
```task
id: USER-WP-0021-T03
-status: todo
+status: done
priority: high
state_hub_task_id: "3e0b41ee-6159-46a4-a9fe-c5b6d714cc2a"
```
@@ -57,11 +94,38 @@ state_hub_task_id: "3e0b41ee-6159-46a4-a9fe-c5b6d714cc2a"
Add platform tenant creation, first-admin bootstrap, invitation/recovery
management, account removal, and redacted lifecycle-gap diagnostics.
+2026-08-08 increment: account removal now uses the provider-neutral
+deprovisioning port and disables the tenant lifecycle record. Platform
+creation/bootstrap and recovery UI remain.
+
+2026-08-08 follow-up: platform APIs now create tenants through the tenant
+authority, prepare the first administrator, and perform redacted identity
+recovery. Browser administration screens for these operations remain.
+
+2026-08-08 browser increment: tenant administrators can create, inspect,
+resend, and expire invitations with versioned CSRF-protected forms, and remove
+accounts through the provider-neutral deprovisioning boundary.
+
+2026-08-08 platform-browser increment: platform operators have a responsive,
+CSRF-protected tenant-creation screen with optional first-admin preparation
+and a direct handoff to tenant administration. Redacted recovery and
+lifecycle-gap browser diagnostics remain.
+
+2026-08-08 recovery-browser increment: platform operators can inspect redacted
+lifecycle-gap categories and invoke CSRF-protected identity recovery from the
+tenant member view. Recovery recreates a missing provider link or reconciles
+an existing identity, then restores the tenant lifecycle record without
+showing credentials, factor evidence, or provider error bodies.
+
+2026-08-08 completion: tenant and platform browser surfaces now cover every
+listed administration operation while retaining tenant boundaries, CSRF,
+provider-neutral lifecycle ports, and redacted diagnostics.
+
## T04 - Complete broad security and accessibility conformance
```task
id: USER-WP-0021-T04
-status: todo
+status: done
priority: high
state_hub_task_id: "fb59245e-6989-4bd9-b72a-68e53ea9f0af"
```
@@ -71,6 +135,32 @@ outage, partial failure, audit-redaction, keyboard/screen-reader, and
mobile/desktop conformance. Preserve existing cross-tenant and escalation
denial gates.
+2026-08-08 increment: conformance covers invitation conflicts, resend/expiry,
+outbox provider failure, replay, dead-letter, successful recovery, and
+provider-neutral account removal. Browser accessibility breadth remains.
+
+2026-08-08 follow-up: conformance now also proves ordinary-user denial of the
+platform surface and the positive platform tenant/bootstrap, recovery, and
+outbox delivery workflow.
+
+2026-08-08 browser increment: conformance proves CSRF enforcement, invitation
+email binding, successful browser claim and onboarding redirect, responsive
+viewport metadata, focus-visible controls, semantic landmarks, and invitation
+and removal administration controls.
+
+2026-08-08 self-service/recovery increment: conformance additionally covers
+durable consent/profile completion, immutable verified email, tenant-hinted
+OIDC reauthentication, platform recovery controls, and redacted lifecycle-gap
+presentation.
+
+2026-08-08 completion: the automated matrix covers duplicate, explicitly
+expired, revoked, and replayed invitations; stale versions; expired sessions;
+provider outage and unchanged lifecycle state; bounded error/audit surfaces;
+cross-tenant and platform denial; semantic headings/landmarks; visible keyboard
+focus; responsive viewport/mobile tables; provider handoff denial; and
+desktop/browser positive flows. The full suite passes 115 tests with three
+provider integration tests skipped when their external service is absent.
+
## T05 - Trigger enterprise federation planning only on demand
```task