feat: add project membership RBAC and administration

.env.example

@@ -121,15 +121,19 @@ FEEDBACK_MAX_CRITERIA=1
 FEEDBACK_DESCENDANT_GUARD=true
 
 # ---------------------------------------------------------------------------
-# API Authentication (Microsoft Entra ID) — identity-only, non-breaking
+# Authentication and project-membership RBAC (Microsoft Entra ID)
 # ---------------------------------------------------------------------------
-# Leave AUTH_PROVIDER unset to keep auth disabled: the API boots and treats
-# every caller as anonymous when all IdP settings are absent. Configured clients
-# enroll through GET /api/v1/users/me?login=true, then use IdP bearer tokens on
-# ordinary requests. Active Scope users/roles are cached in Redis.
+# Enabled by default; missing IdP configuration fails API startup.
+# Explicit false disables BOTH API auth/RBAC and Portal sign-in, exposing normal
+# application APIs to network callers. Use only in isolated trusted test/local envs.
+# Recreate API and Portal together; users/memberships/audit history are preserved.
+# SCOPE_AUTH_ENABLED=true
+# Clients explicitly enroll through POST /api/v1/users/me, then use the unchanged
+# IdP bearer on ordinary requests. GET /users/me is read-only and never enrolls.
+# Identity snapshots are cached; canonical membership checks remain authoritative.
 # See ENV_VARIABLES.md → "API Authentication" for details.
 
-# Identity provider. Set to `entra` to enable token verification.
+# Required identity provider when SCOPE_AUTH_ENABLED is enabled (the default).
 # AUTH_PROVIDER=entra
 
 # OIDC authority for JWKS discovery + issuer validation (multi-tenant example).
@@ -158,11 +162,9 @@ FEEDBACK_DESCENDANT_GUARD=true
 # Scopes the CLI/Portal request for the API access token.
 # AUTH_SCOPES=api://00000000-0000-0000-0000-000000000000/access
 
-# Promote-only admin bootstrap: comma-separated `${idp}:${tenant}/${subject}`.
-# AUTH_BOOTSTRAP_ADMINS=
-
-# Required tenant allowlist when AUTH_BOOTSTRAP_ADMINS is configured.
-# AUTH_BOOTSTRAP_TENANTS=
+# First sign in to enroll, then use the operator bootstrap-admin command.
+# Login never promotes an admin. AUTH_BOOTSTRAP_ADMINS/TENANTS are retired;
+# nonempty values prevent authenticated API startup. See docs/architecture/auth-rbac.md.
 
 # Fixed active-user cache lifetime, in seconds (positive integer, default 300).
 # Cache hits do not extend expiry; Redis outages fall back to MongoDB.

.env.local.example

@@ -57,10 +57,10 @@ LLM_MODEL=
 #   docker pull ghcr.io/cmaneu/entra-local
 #   docker run -p 8443:8443 -v entra-local-data:/app/data ghcr.io/cmaneu/entra-local
 #
-# The emulator serves a self-signed certificate. `jose` fetches the JWKS over
-# HTTPS, so for local dev either trust the emulator CA or, as a quick shortcut,
-# set NODE_TLS_REJECT_UNAUTHORIZED=0 for the api service (dev-only — never in
-# production). The emulator advertises issuer + JWKS under
+# Trust the emulator's local CA; never disable TLS or signature verification.
+# The Compose wrapper generates/trusts the development CA and mounts it for the
+# API. Native host clients can use NODE_EXTRA_CA_CERTS=$PWD/.certs/rootCA.pem.
+# The emulator advertises issuer + JWKS under
 # https://localhost:8443/<tenant>/v2.0.
 #
 # Seeded identities (see the entra-local docs):
@@ -70,6 +70,10 @@ LLM_MODEL=
 #   user    alice@entralocal.dev -> oid aaaaaaaa-0000-0000-0000-000000000001 (bootstrap candidate below)
 #   user    bob@entralocal.dev   -> oid aaaaaaaa-0000-0000-0000-000000000002
 # ---------------------------------------------------------------------------
+# Auth and RBAC default on. Explicit false permits anonymous application access
+# without the emulator; use only in network-isolated trusted local/test envs.
+# Set the same mode for API and Portal and recreate both; do not use for recovery.
+# SCOPE_AUTH_ENABLED=true
 # AUTH_PROVIDER=entra
 
 # OIDC authority — the emulator issuer base for the seeded tenant. In a worktree
@@ -102,13 +106,10 @@ LLM_MODEL=
 # entra-local image that includes this JWKS extension.
 # AUTH_JWKS_URI=https://localhost:8501/11111111-1111-1111-1111-111111111111/discovery/v2.0/keys
 
-# Promote-only admin bootstrap: comma-separated `${idp}:${tenant}/${subject}`.
-# GET /api/v1/users/me?login=true promotes alice only if her API access token
-# asserts email_verified=true; otherwise the default role remains `user`.
-# AUTH_BOOTSTRAP_ADMINS=entra:11111111-1111-1111-1111-111111111111/aaaaaaaa-0000-0000-0000-000000000001
-
-# Required tenant allowlist when AUTH_BOOTSTRAP_ADMINS is configured.
-# AUTH_BOOTSTRAP_TENANTS=11111111-1111-1111-1111-111111111111
+# Alice and Bob initially enroll as ordinary users, using genuine emulator tokens.
+# Promote an existing exact identity with the operator bootstrap-admin command;
+# see docs/architecture/auth-rbac.md#durable-changes-and-operator-runbooks.
+# Login never grants or restores admin. Remove retired AUTH_BOOTSTRAP_* settings.
 
 # Fixed active-user Redis cache lifetime; normal requests never update lastLoginAt.
 # Redis keys are namespaced by MONGO_DATABASE and verified provider/tid/oid.