By default, TOTP MFA is opt-in per user (User.mfaEnabled) or per school (School.mfaEnabled) — a compromised admin password alone grants full access unless MFA was actively set up.

Setting REQUIRE_MFA=true closes this gap: on login, an admin with no MFA configured (neither their own nor their school's) receives a restricted session token instead of full access. requireSchoolAuth (backend/src/middleware/auth.js) rejects every request from a restricted token except the MFA enrollment endpoints (POST /api/auth/mfa/user/setup, POST /api/auth/mfa/user/verify) with 403 MFA_SETUP_REQUIRED, so the frontend must complete enrollment before any protected endpoint becomes reachable. Once POST /api/auth/mfa/user/verify succeeds, the restriction is lifted for the current session immediately.

The login response includes mfaSetupRequired: true when this restricted session is issued, which the frontend uses to redirect to the MFA setup flow instead of the dashboard.

REQUIRE_MFA does not apply to the environment-configured super-admin break-glass account, which is not backed by the User/School MFA fields.

JWT secrets, the Stellar signing-key encryption key (SIGNER_MASTER_KEY), and the webhook secret encryption key (WEBHOOK_SECRET_ENCRYPTION_KEY) have scripted rotation — see scripts/rotate-jwt-secret.js, scripts/rotate-signer-master-key.js, and scripts/rotate-webhook-encryption-key.js, and the "Key Rotation" section of docs/operator-runbooks.md for when and how to run them.

backend/src/services/webhookSecretEncryption.js encrypts every school's webhookSecret at rest (AES-256-GCM) using a key derived from WEBHOOK_SECRET_ENCRYPTION_KEY. Rotating that key without re-encrypting the stored secrets would make every existing secret undecryptable with the new key, breaking outbound webhook signing for every school (#1380). Rotation is scripted and supports a dual-key grace period so there is no cutover window where deliveries fail.

Procedure:

1. Generate a new key: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))".
2. Set WEBHOOK_SECRET_ENCRYPTION_KEY_PREVIOUS to the current key (the one already protecting stored secrets) and WEBHOOK_SECRET_ENCRYPTION_KEY to the new key, both in the deployment's secret store.
3. Run the migration script against the target database, first as a dry run:

   WEBHOOK_SECRET_ENCRYPTION_KEY_PREVIOUS=<current key> WEBHOOK_SECRET_ENCRYPTION_KEY=<new key> \
     node scripts/rotate-webhook-encryption-key.js

   Review the per-school report, then re-run with --apply to persist the re-encrypted values:

   WEBHOOK_SECRET_ENCRYPTION_KEY_PREVIOUS=<current key> WEBHOOK_SECRET_ENCRYPTION_KEY=<new key> \
     node scripts/rotate-webhook-encryption-key.js --apply

4. Redeploy the API and worker instances with both env vars set. While WEBHOOK_SECRET_ENCRYPTION_KEY_PREVIOUS is present, decryptWebhookSecret() transparently falls back to it whenever the new key fails an auth-tag check — this covers any secret the migration script hasn't reached yet and any instance still finishing a rolling deploy, so webhook deliveries are never interrupted mid-rotation.
5. Once the rollout is complete and step 3's --apply run reports zero failures, drop WEBHOOK_SECRET_ENCRYPTION_KEY_PREVIOUS from the deployment and redeploy again to close the grace period.
6. Verify a live webhook delivery signs correctly, then record the rotation time and operator in the incident log per the general rotation order in docs/operator-runbooks.md.

Skipping step 2 (or dropping the previous key before step 3 completes) reproduces the original failure mode: any secret the script hasn't re-encrypted yet becomes unreadable, and signing outbound webhooks for that school silently breaks.

backend/src/utils/signerKeyManager.js encrypts every school's Stellar signing secret key at rest under a single master key. By default that master key is read from the SIGNER_MASTER_KEY environment variable, which is the simplest option but has real exposure in production: env vars are visible in docker inspect output and /proc/<pid>/environ on any node running the container, in Kubernetes Secret manifests that may end up committed to version control or stored unencrypted in etcd, and in CI logs that print the environment on failure.

To avoid holding the plaintext key in an env var, set SIGNER_KEY_SOURCE and call initializeMasterKey() once at startup (already wired into backend/src/app.js's boot sequence) to resolve it from a real secrets manager instead:

Either provider may return the key as a bare 64-character hex string or as JSON ({"SIGNER_MASTER_KEY": "<hex>"} or {"key": "<hex>"}). The resolved key is cached in memory only for the life of the process — it is never written back to process.env or to disk — and getMasterKey() prefers it over SIGNER_MASTER_KEY whenever initializeMasterKey() has populated it, so a misconfigured or unreachable provider fails loudly at boot (the process exits non-zero, per backend/src/app.js) instead of silently falling back to an unset env var.

This does not change key rotation mechanics — reEncryptSecretKey() and scripts/rotate-signer-master-key.js still apply; point SIGNER_MASTER_KEY_OLD / SIGNER_MASTER_KEY (or the provider-backed equivalents) at the old and new key material as described above.

A dedicated CI job (scripts/scan-repo-secrets.js, the secret-scan-repo job in .github/workflows/ci.yml) scans every tracked file in the repository for real Stellar StrKey secret keys (S + 55 base32 chars) so one can never be committed regardless of which SIGNER_KEY_SOURCE a deployment uses.

StellarEduPay enforces a Content Security Policy on all HTTP responses to mitigate XSS attacks. The policy is applied at two layers: the Next.js frontend and the Express backend.

Without CSP, a successful XSS injection (e.g. a malicious student name rendered in the dashboard) can execute arbitrary JavaScript in the admin's browser, steal the JWT from localStorage, and exfiltrate school data. CSP prevents this by restricting which scripts, styles, and network destinations the browser will allow.

Applied to every HTML response via the Next.js headers() API:

Content-Security-Policy:
  default-src 'self';
  script-src  'self';
  style-src   'self';
  img-src     'self' data:;
  font-src    'self';
  connect-src 'self' https://horizon-testnet.stellar.org https://horizon.stellar.org;
  object-src  'none';
  frame-ancestors 'none';
  base-uri    'self';
  form-action 'self'

Additional security headers set alongside CSP:

The Express backend serves only JSON API responses — directives for scripts, styles, and images are irrelevant. Helmet is configured with a minimal policy appropriate for an API:

helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'none'"],
      frameAncestors: ["'none'"],
    },
  },
})

default-src 'none' means the browser should load nothing from this origin as a document resource. frame-ancestors 'none' prevents the API responses from being embedded in frames.

The CSP configuration is covered by tests/csp.test.js, which verifies:

• The frontend next.config.js exports a headers() function returning a catch-all entry with a Content-Security-Policy header.
• The frontend CSP includes default-src 'self', script-src 'self', frame-ancestors 'none', object-src 'none', and the Stellar Horizon connect-src allowlist.
• The frontend CSP does not contain 'unsafe-inline' or 'unsafe-eval'.
• The backend app.js sets defaultSrc: ["'none'"] and frameAncestors: ["'none'"] and does not include scriptSrc, styleSrc, imgSrc, 'unsafe-inline', or 'unsafe-eval'.

Run the tests with:

npm test -- tests/csp.test.js

The CSP allow-list is defined in a single source of truth:

frontend/src/config/cspSources.js

Both frontend/next.config.js (runtime policy) and tests/csp.test.js (assertions) import from this module. Adding or removing an origin requires editing exactly one file — the change is automatically reflected in the deployed CSP header and in the test suite.

To add a new external origin:

1. Open frontend/src/config/cspSources.js.
2. Add the full origin (scheme + host, no trailing slash) to the appropriate array:
   • CONNECT_SRC_ORIGINS — fetch/XHR targets (APIs, WebSockets)
   • STYLE_SRC_ORIGINS — external stylesheets
   • FONT_SRC_ORIGINS — external font files
3. That's it. Run npm test -- tests/csp.test.js to confirm.

Do not add 'unsafe-inline' or 'unsafe-eval' to script-src. If a third-party library requires inline scripts, use a nonce-based approach instead.

All outbound webhook URLs pass through a multi-layer SSRF defence on every delivery attempt.

validateWebhookUrl(url) is called when an endpoint is created or updated:

• Only https:// scheme is accepted.
• Well-known internal hostnames (localhost, *.local, *.internal, *.localhost, *.test, *.invalid) are rejected without a DNS lookup.
• Bare IP literals are checked directly against the deny list.
• DNS is resolved and all returned addresses (A + AAAA) must be public.

Immediately before every HTTP delivery the hostname is re-resolved and every IP is re-checked. If the hostname now resolves to a private address (DNS rebinding attack), the delivery is aborted with error SSRF_BLOCKED.

Both IPv4 and IPv6 are covered:

The Axios instance used for delivery is configured with maxRedirects: 0. Any 3xx response is treated as a delivery failure with error code SSRF_REDIRECT_BLOCKED and is not followed.

Response bodies are capped at 64 KB (maxContentLength: 65536). Requests that exceed this are aborted.

StellarEduPay implements automatic anonymization of student personally identifiable information (PII) to reduce breach exposure and align with data minimization principles from GDPR and similar privacy frameworks.

Once the retention window expires for a soft-deleted student record, the following PII fields are cleared:

Non-PII fields retained for audit and reconciliation purposes:

• studentId, schoolId, class, academicYear — for payment tracking
• feeAmount, totalPaid, remainingBalance, fees — for billing history
• Payment and transaction records — for regulatory compliance

Environment variable: STUDENT_PII_RETENTION_DAYS (default: 90)

• Specifies the number of days to retain PII after soft-delete before anonymization
• Default of 90 days (~3 months) balances operational need against breach exposure
• Set to 0 to disable anonymization (not recommended for production)

Example:

# Retain PII for 180 days (6 months) before anonymization
STUDENT_PII_RETENTION_DAYS=180

The piiAnonymizationScheduler runs once daily on the leader node and:

1. Queries for soft-deleted students whose deletion date exceeds STUDENT_PII_RETENTION_DAYS
2. Skips records already anonymized (name="Anonymized" and all other PII fields null)
3. Bulk-updates matching records to clear sensitive fields
4. Logs the count of anonymized records for audit purposes

The scheduler is integrated into the leader-election system, ensuring it runs on exactly one instance in a clustered deployment.

This implementation supports:

• GDPR Article 5 (data minimization) — data kept no longer than necessary
• GDPR Article 17 (right to be forgotten) — PII erasure after the retention window
• Local privacy regulations — configurable retention period per deployment

Schools should configure STUDENT_PII_RETENTION_DAYS to match their legal obligations and operational needs.

To comply with data minimization requirements (GDPR Article 5, storage limitation), the platform automatically redacts personal data from all application logs.

All log entries at info level and above have the following fields masked:

• Raw IP addresses are never logged
• Instead, IPs are hashed using HMAC-SHA256 with a per-boot secret
• Same IP produces the same hash within a server session (for correlation/debugging)
• Hashes are not reversible and do not persist across server restarts

• Query strings are stripped from all logged URLs to prevent token/secret leakage
• Example: /api/payments?token=abc123 → /api/payments

All environment variables matching the pattern /(SECRET|PASSWORD|TOKEN|KEY|URI|HASH)$/i are redacted in config dumps, with explicit exceptions for known non-secret keys like SIGNER_KEY_SOURCE, EMAIL_PROVIDER, etc.

Credentials embedded in URIs are also redacted:

• mongodb://user:pass@host → mongodb://user:[REDACTED]@host
• redis://:pass@host → redis://:[REDACTED]@host

Redaction is applied in three layers:

1. Logger format (backend/src/utils/logger.js): The formatMessage() function applies redactPii() to all log arguments at info level and above
2. Request logger (backend/src/middleware/requestLogger.js): IP addresses are hashed via hashIp(), URLs are stripped via stripQueryString()
3. Auth middleware (backend/src/middleware/auth.js): Failed auth attempts log hashed IPs instead of raw IPs

Run the test suite to verify redaction:

npm test -- backend/tests/piiRedaction.test.js

The test verifies:

• Email addresses are masked in logs
• Phone numbers are masked in logs
• Names are masked in logs
• IP addresses are hashed (not logged in plaintext)
• Query strings are stripped from URLs
• Config dumps redact all secret-pattern environment variables

Audit logs (audit_log collection in MongoDB) are not redacted because they are the authoritative record for compliance and forensic investigation. However:

• Audit logs are access-controlled (admin-only via authenticated API)
• Audit logs respect the retention period configured in AUDIT_LOG_RETENTION_DAYS
• Audit logs are never written to file logs or stdout

File logs are automatically rotated and deleted by winston-daily-rotate-file.

1. Configure log aggregators to respect the platform's retention policy
2. Restrict access to log files and aggregation tools — logs still contain operational context that could be sensitive
3. Do not disable redaction — all PII redaction is mandatory for production use
4. Monitor alerts — admin alerts may contain masked PII; ensure alert channels are access-controlled

• Data Privacy and Retention Policy — full data retention and data subject rights
• Audit Service — audit log implementation
• PII Redaction Utilities — redaction functions

Every authenticated, state-changing request passes through auditContext middleware and calls logAudit in the handler. All entries land in the tamper-evident audit_log MongoDB collection.

An automated regression test (tests/issue-1554-audit-context-coverage.test.js) walks the Express router stack and fails if a non-GET authenticated route is missing auditContext.

These endpoints either have no authenticated actor at call time or use their own documented verification mechanism: