fix(security): trust forwarding IPs only from configured proxies

.github/workflows/dependency-review.yml

@@ -20,12 +20,24 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
+          repository: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+
+      - name: Verify exact checkout revision
+        env:
+          EXPECTED_HEAD_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          actual_head_sha="$(git rev-parse HEAD)"
+          printf 'expected_head_sha=%s\nactual_head_sha=%s\n' "$EXPECTED_HEAD_SHA" "$actual_head_sha"
+          test "$actual_head_sha" = "$EXPECTED_HEAD_SHA"
 
       - name: Check dependency review support
         id: dependency_review_support
         env:
           GH_TOKEN: ${{ github.token }}
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
           REPOSITORY: ${{ github.repository }}
         shell: bash
@@ -40,33 +52,72 @@ jobs:
 
           api_url="${GITHUB_API_URL:-https://api.github.com}"
           response_file="$(mktemp)"
-          status="$(
-            curl -fsS -o "$response_file" -w '%{http_code}' \
+          base_response_file="$(mktemp)"
+          compare_response_file="$(mktemp)"
+          trap 'rm -f "$response_file" "$base_response_file" "$compare_response_file"' EXIT
+
+          base_ref_encoded="$(python3 -c 'import os, urllib.parse; print(urllib.parse.quote(os.environ["BASE_REF"], safe="/"))')"
+          base_status="$(
+            curl -sS -o "$base_response_file" -w '%{http_code}' \
               -H "Accept: application/vnd.github+json" \
               -H "Authorization: Bearer ${GH_TOKEN}" \
               -H "X-GitHub-Api-Version: 2022-11-28" \
-              "${api_url}/repos/${REPOSITORY}/dependency-graph/compare/${BASE_SHA}...${HEAD_SHA}" \
+              "${api_url}/repos/${REPOSITORY}/branches/${base_ref_encoded}" \
               || true
           )"
 
-          if [ "$status" = "200" ]; then
-            echo "supported=true" >>"$GITHUB_OUTPUT"
-            exit 0
+          if [ "$base_status" != "200" ]; then
+            echo "::error::Unable to resolve live base branch ${BASE_REF}; GitHub API returned HTTP ${base_status}."
+            exit 1
           fi
 
-          if [ "$status" = "403" ] || [ "$status" = "404" ]; then
-            echo "::warning::Dependency review is unavailable for ${REPOSITORY}; skipping dependency-review hard gate."
-            echo "supported=false" >>"$GITHUB_OUTPUT"
-            exit 0
+          LIVE_BASE_SHA="$(jq -er '.commit.sha | select(test("^[0-9a-f]{40}$"))' "$base_response_file")" || {
+            echo "::error::Live base branch response did not contain a valid commit SHA."
+            exit 1
+          }
+          printf 'live_base_sha=%s\n' "$LIVE_BASE_SHA"
+
+          compare_status="$(
+            curl -sS -o "$compare_response_file" -w '%{http_code}' \
+              -H "Accept: application/vnd.github+json" \
+              -H "Authorization: Bearer ${GH_TOKEN}" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
+              "${api_url}/repos/${REPOSITORY}/compare/${LIVE_BASE_SHA}...${HEAD_SHA}" \
+              || true
+          )"
+
+          if [ "$compare_status" != "200" ]; then
+            echo "::error::Unable to resolve the pull-request merge base for ${LIVE_BASE_SHA}...${HEAD_SHA}; GitHub API returned HTTP ${compare_status}."
+            exit 1
+          fi
+
+          BASE_SHA="$(jq -er '.merge_base_commit.sha | select(test("^[0-9a-f]{40}$"))' "$compare_response_file")" || {
+            echo "::error::Compare response did not contain a valid merge-base SHA."
+            exit 1
+          }
+          echo "base_sha=$BASE_SHA" >>"$GITHUB_OUTPUT"
+
+          status="$(
+            curl -sS -o "$response_file" -w '%{http_code}' \
+              -H "Accept: application/vnd.github+json" \
+              -H "Authorization: Bearer ${GH_TOKEN}" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
+              "${api_url}/repos/${REPOSITORY}/dependency-graph/compare/${BASE_SHA}...${HEAD_SHA}" \
+              || true
+          )"
+
+          if [ "$status" != "200" ]; then
+            echo "::error::Dependency review support check failed with HTTP ${status}."
+            exit 1
           fi
 
-          echo "::error::Dependency review support check failed with HTTP ${status}."
-          cat "$response_file"
-          exit 1
+          echo "supported=true" >>"$GITHUB_OUTPUT"
 
       - name: Dependency review
         if: steps.dependency_review_support.outputs.supported == 'true'
         uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
         with:
+          base-ref: ${{ steps.dependency_review_support.outputs.base_sha }}
+          head-ref: ${{ github.event.pull_request.head.sha }}
           fail-on-severity: moderate
           comment-summary-in-pr: on-failure

.github/workflows/server-tests.yml

@@ -25,6 +25,15 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
+          repository: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+      - name: Verify exact checkout revision
+        env:
+          EXPECTED_HEAD_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+        run: |
+          actual_head_sha="$(git rev-parse HEAD)"
+          printf 'expected_head_sha=%s\nactual_head_sha=%s\n' "$EXPECTED_HEAD_SHA" "$actual_head_sha"
+          test "$actual_head_sha" = "$EXPECTED_HEAD_SHA"
       - name: Setup Node 22.13
         uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
         with:
@@ -33,8 +42,8 @@ jobs:
         run: npm ci
       - name: Unit tests (EVM · CPM · baseline · workload)
         run: npm run test:unit
-      - name: API tests (auth · tenancy · RBAC · billing · webhooks · rate limit)
-        run: npm run test:api
+      - name: Owned production coverage evidence (unit · API under c8)
+        run: npm run test:coverage
       - name: app.js stays eval-safe (no top-level import/export)
         run: node -e "new Function(require('fs').readFileSync('app.js','utf8')); console.log('eval-safe OK')"
 
@@ -45,6 +54,15 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
+          repository: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+      - name: Verify exact checkout revision
+        env:
+          EXPECTED_HEAD_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+        run: |
+          actual_head_sha="$(git rev-parse HEAD)"
+          printf 'expected_head_sha=%s\nactual_head_sha=%s\n' "$EXPECTED_HEAD_SHA" "$actual_head_sha"
+          test "$actual_head_sha" = "$EXPECTED_HEAD_SHA"
       - name: Setup Node 22.13
         uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
         with:

CHANGELOG.md

@@ -22,6 +22,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- Redacted invite and public-share bearer-token path segments in both ordinary
+  request logs and rate-limit rejection logs, including malformed trailing
+  paths, so access-log retention cannot become a credential disclosure channel.
+- Unified server mailbox canonicalization across password, invitation, OIDC,
+  and legacy-migration boundaries with trim, NFC normalization, lowercase
+  conversion, and canonical unique-index enforcement.
+- Made the public HTTPS transport serialize URLSearchParams as UTF-8 bytes so
+  production OIDC token exchanges reach the provider instead of failing at the
+  request boundary.
+- Replaced the unsigned `POST /api/stripe/webhook` plan-upgrade stub with a
+  fail-closed raw-body HMAC-SHA-256 signature boundary. Signed deliveries are
+  acknowledged only; webhook JSON is not entitlement authority until durable
+  event reconciliation. Unsigned, stale, or body-mutated signatures fail closed,
+  and the public app copies protected logging and rate-limit middleware so abuse
+  controls still wrap the endpoint (Krawczyk et al., 1997; National Institute of
+  Standards and Technology, 2008).
 - Made contextual-orchestrator briefing requests fail closed unless an authenticated endpoint is configured. Deterministic generated text is restricted to explicit `SCOPEWEAVE_DEV=1`, message/provider responses are bounded and validated, and non-loopback HTTP transport is rejected.
 - Made `SCOPEWEAVE_JWT_SECRET` mandatory at startup and rejected weak or
   unexpanded placeholder values so production deployments fail closed.

docs/deploy.md

@@ -34,17 +34,53 @@ persists the database in the `scopeweave-data` volume.
 | `SCOPEWEAVE_JWT_SECRET` | **yes** | Signs session JWTs. Startup fails unless it contains at least 32 non-whitespace characters. |
 | `PORT` | no (default 8787) | Listen port |
 | `SCOPEWEAVE_DB` | no (default `/data/scopeweave.db`) | SQLite file path (on the volume) |
-| `SCOPEWEAVE_DEV` | no | Must be `1` to enable the dev `activate-pro` endpoint. **Never set in production.** |
+| `SCOPEWEAVE_DEV` | no | Must be `1` to enable development-only behavior: the `activate-pro` endpoint, the built-in OIDC mock when `OIDC_ISSUER` is unset, and the deterministic orchestrator mock when `ORCHESTRATOR_URL` is unset. **Never set in production.** |
 | `STRIPE_SECRET_KEY`, `STRIPE_PRICE_ID`, `STRIPE_WEBHOOK_SECRET` | for live billing | Enables real Stripe Checkout (`npm i stripe` too). Without them, billing uses the mock path. |
-| `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_REDIRECT_URI` | for real SSO | Points the OIDC login at your IdP. Unset → a built-in mock IdP (dev/test only). |
-| `ORCHESTRATOR_URL` | for AI 브리핑 | contextual-orchestrator 주소. Unset → deterministic mock. |
-| `ORCHESTRATOR_TOKEN` | with URL | orchestrator Bearer 토큰 (`CONTEXTUAL_ORCHESTRATOR_TOKEN`). |
+| `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_REDIRECT_URI` | for real SSO | Points the OIDC login at your IdP. Outside explicit `SCOPEWEAVE_DEV=1`, a missing issuer fails closed with `404 sso not configured`; the built-in mock exists only when the issuer is unset **and** development mode is explicitly enabled. |
+| `ORCHESTRATOR_URL` | for AI briefing | contextual-orchestrator origin. A missing URL fails closed outside explicit `SCOPEWEAVE_DEV=1`; the deterministic mock exists only in development mode. |
+| `ORCHESTRATOR_TOKEN` | with URL | Required Bearer token for configured orchestrator requests. Set it to the same value as the orchestrator's `CONTEXTUAL_ORCHESTRATOR_TOKEN` setting. |
 | `CLEARFOLIO_URL` | for 산출물 viewer | Clearfolio 문서 뷰어 백엔드 주소. Unset → built-in mock (dev/test). |
 | `CLEARFOLIO_HMAC_SECRET` | optional | Signs tenant-claim headers (`clearfolio.tenant-claims.hmac-secret`와 동일 값). |
 | `SCOPEWEAVE_ATTACHMENT_STATUS_CONCURRENCY` | no (default 8, maximum 32) | Maximum concurrent Clearfolio status lookups during one attachment-list request. Invalid values fall back to 8; values above 32 are clamped. |
 | `SCOPEWEAVE_ATTACHMENT_STATUS_TIMEOUT_MS` | no (default 3000, maximum 30000) | Hard caller-side timeout for each Clearfolio status lookup. The AbortSignal is also forwarded downstream. |
 | `SCOPEWEAVE_ATTACHMENT_STATUS_BUDGET_MS` | no (default 5000, maximum 60000) | Wall-clock budget for the entire best-effort refresh pass. Work not started before the deadline is deferred to a later list request. |
-| `SCOPEWEAVE_RATE_LIMIT_MAX` (+ `SCOPEWEAVE_RATE_LIMIT_WINDOW_MS`) | recommended | Per-IP fixed-window rate limiting (429 + Retry-After). Off when unset. |
+| `SCOPEWEAVE_RATE_LIMIT_MAX` | recommended | Per-client fixed-window request allowance. Unset or explicit `0` disables the limiter. Any other configured value must be a non-negative safe integer or startup fails. |
+| `SCOPEWEAVE_RATE_LIMIT_WINDOW_MS` | no (default 60000) | Fixed-window duration in milliseconds. An explicit value must be a positive safe integer or startup fails. |
+| `SCOPEWEAVE_RATE_LIMIT_BUCKETS_MAX` | no (default 10000) | Maximum number of live per-client limiter buckets held by one ScopeWeave process. An explicit value must be a positive safe integer or startup fails. Once capacity is reached, previously unseen identities share a fail-closed overflow bucket until expired regular buckets are reclaimed. |
+| `SCOPEWEAVE_TRUSTED_PROXY_IPS` | only behind trusted reverse proxies | Comma-separated **immediate or chained proxy peer IPs** that ScopeWeave is allowed to trust when interpreting `X-Forwarded-For`. Configure the actual IP once; dotted IPv4-mapped Node spellings such as `::ffff:127.0.0.1` are normalized to their IPv4 address before trust comparison. Leave unset for direct deployments. |
+
+### Rate-limit capacity and tuning
+
+When the limiter is enabled, `429` responses include `Retry-After`. Client
+identity is anchored to the actual network peer unless that peer is explicitly
+trusted through `SCOPEWEAVE_TRUSTED_PROXY_IPS`. Valid dotted IPv4-mapped IPv6
+peer and forwarded-hop spellings are canonicalized to their underlying IPv4
+address before trust comparison and limiter-key selection. This prevents a
+Node dual-stack listener from collapsing all proxied clients into one limiter
+bucket merely because the socket exposed an IPv4 proxy as `::ffff:a.b.c.d`.
+Invalid address text is never admitted as a trusted identity.
+
+The regular in-memory bucket map is deliberately bounded by
+`SCOPEWEAVE_RATE_LIMIT_BUCKETS_MAX`; attacker-driven high-cardinality source
+identities therefore cannot create unbounded limiter state. At capacity, new
+identities use one shared overflow bucket rather than allocating new map entries.
+Expired regular buckets are reclaimed by a bounded sweep before admitting new
+identities.
+
+Size `SCOPEWEAVE_RATE_LIMIT_BUCKETS_MAX` for the maximum legitimate concurrent
+client-identity population expected **per process**, with headroom for normal
+bursts. Do not increase it merely to make overflow throttling disappear: first
+confirm that trusted-proxy identity extraction is correct and that the observed
+cardinality is legitimate. In horizontally scaled deployments, each replica has
+its own limiter state; this fixed-window implementation is a process-local abuse
+control, not a globally coordinated quota system. Use a shared rate-limit store
+or edge control plane when a cross-replica/global quota is required.
+
+Limiter numeric configuration is fail-closed. A malformed, infinite, negative,
+or otherwise unsafe explicit value causes startup failure instead of silently
+disabling protection or resetting windows on every request. Treat such a startup
+failure as a configuration incident; correct the setting rather than removing
+or bypassing the limiter gate.
 
 ## Attachment status refresh operations
 
@@ -133,6 +169,22 @@ Terminate TLS at a reverse proxy (nginx/Caddy/ALB) in front of the backend and
 forward to `:8787`. The client and API share the origin, so no CORS config is
 needed.
 
+`X-Forwarded-For` is **ignored for the security rate-limit identity by default**.
+If a reverse proxy is the only permitted ingress to ScopeWeave, list its actual
+network peer address in `SCOPEWEAVE_TRUSTED_PROXY_IPS`. For multiple trusted
+proxy hops, list every trusted hop. You do not need to duplicate an IPv4 proxy
+as both `a.b.c.d` and Node's dotted IPv4-mapped `::ffff:a.b.c.d` representation;
+ScopeWeave canonicalizes that mapped socket/hop spelling before the trust
+comparison. ScopeWeave then walks `X-Forwarded-For` from right to left, skips
+explicitly trusted proxy addresses, and chooses the first untrusted valid IP as
+the client identity. Missing, malformed, or all-trusted forwarding evidence
+falls back to the actual socket peer.
+
+Do not configure this trust list while untrusted clients can connect directly to
+the backend. The proxy must overwrite or append forwarding information according
+to a controlled ingress policy; accepting a caller-selected forwarding header
+without an authenticated/trusted peer would make rate limiting bypassable.
+
 ## Kubernetes
 
 The existing `infra/k8s/` manifests deploy the **static-only** nginx image. For