Enterprise-grade security for the Forge client/server platform on AWS ECS Fargate, storing sensitive academic data: students, mentors, teachers, reviews, feedback, concerns, and performance metrics. Security is a first-class concern, not a phase. This document is the authoritative reference for authentication, sessions, authorization, data isolation, AWS account isolation, app security, secrets, audit, and threat modeling.

Cross-references: architecture-v2.md (system design, services, data model) · infra-ecs.md (VPC, ECS, RDS, ALB, KMS, Secrets) · integration-setup.md (GitHub, Discord, Google Calendar credentials & webhooks).

            Internet
               │  (TLS 1.2+)
               ▼
        ┌─────────────┐   Cloudflare (WAF, DDoS, TLS termination edge)
        │ Cloudflare  │
        └─────────────┘
               │  (TLS, origin cert / mTLS to ALB)
               ▼
        ┌─────────────┐   Public subnets only
        │     ALB     │   (HTTPS:443, HSTS, security groups)
        └─────────────┐
               │  (TLS in VPC)
   ┌───────────┴───────────┐
   ▼                       ▼            Private subnets (no public IPs)
┌────────────┐      ┌────────────┐
│ Next.js    │ ───▶ │ Express +  │  ALL authz + business logic + integrations
│ (ECS)      │ HTTP │ TS API     │  live here. Frontend never reaches DB/3P.
│ SSR/UI     │      │ (ECS)      │
└────────────┘      └─────┬──────┘
                          │  (TLS, sslmode=require)
                ┌─────────┴─────────┐
                ▼                   ▼          Private/isolated subnets
          ┌──────────┐        ┌──────────┐
          │ RDS      │        │ Redis    │  (optional: sessions, cache, rate limit)
          │ Postgres │        │ Elasticache
          └──────────┘        └──────────┘

Canonical rule: the frontend (Next.js) never calls the database or external integrations directly. It calls the Express API. All authorization and business logic are server-side. Anything rendered client-side that depends on permissions is a UI hint only.

Posture assumption: thousands of users, multiple academic domains, sensitive minors' performance data, a shared multi-tenant AWS account. Designed for university-grade scrutiny and external security audit.

Decision: Google OAuth via OIDC is the only authentication method. No email/password, no self-signup, no custom credentials, no magic links. The server runs the OIDC authorization-code flow, validates the ID token, and gates access on two independent conditions.

Browser            Next.js (ECS)        Express API (ECS)        Google OIDC         RDS Postgres
   │  GET /login        │                      │                     │                    │
   │───────────────────▶│                      │                     │                    │
   │                    │  start auth (server) │                     │                    │
   │                    │─────────────────────▶│                     │                    │
   │                    │   redirect w/ state, │  generate state+    │                    │
   │                    │   nonce, PKCE        │  nonce+PKCE (stored  │                    │
   │   302 to Google ◀──┼──────────────────────┤  server-side)       │                    │
   │◀───────────────────┘                      │                     │                    │
   │  authenticate + consent at accounts.google.com ─────────────────▶│                    │
   │◀──── 302 back to /api/auth/callback?code=…&state=… ─────────────│                    │
   │  GET /api/auth/callback?code,state        │                     │                    │
   │──────────────────────────────────────────▶│                     │                    │
   │                                           │  verify state match │                    │
   │                                           │  exchange code +    │                    │
   │                                           │  PKCE verifier ────▶│  /token            │
   │                                           │◀─── id_token,       │                    │
   │                                           │     access_token,   │                    │
   │                                           │     refresh_token   │                    │
   │                                           │  validate id_token  │                    │
   │                                           │  (sig via JWKS,     │                    │
   │                                           │   iss/aud/exp/nonce)│                    │
   │                                           │  check hd claim ────┼────────────────────┤
   │                                           │  lookup email in   ─┼──▶ SELECT … users   │
   │                                           │   users (allowlist) │   WHERE email=?    │
   │                                           │◀──── role+perms ────┼────────────────────┤
   │                                           │  store OAuth tokens │                    │
   │                                           │  server-side; create│                    │
   │                                           │  session; set cookie│                    │
   │◀──── 302 /dashboard  Set-Cookie: sid=opaque; HttpOnly; Secure ──│                    │

Access is granted only if BOTH hold:

   (a) Google hd claim ∈ { rishihood.edu.in, … }        ← right institution
        AND
   (b) email ∈ users table (admin pre-created)          ← explicitly provisioned

   ┌──────────────────────────┬───────────────────────────────┐
   │ Email                    │ Outcome                       │
   ├──────────────────────────┼───────────────────────────────┤
   │ taj@rishihood.edu.in     │ ✅ hd ok + in users → ALLOW   │
   │ guest@rishihood.edu.in   │ ❌ hd ok but NOT in users → DENY │
   │ random@gmail.com         │ ❌ wrong hd (+ not in users) → DENY │
   └──────────────────────────┴───────────────────────────────┘

Belonging to the institution's Google domain is necessary but not sufficient. The DB allowlist is authoritative for who may enter and what they may do.

On a successful login, the user's role(s) and scopes are loaded from the users / user_roles tables — never from anything in the OAuth token. The token proves identity; the DB decides authority. A server-side session is then created (§3).

Admin → Users → Add user
   │  enter email (institution domain), role, scope (domain/team), display name
   ▼
INSERT users(email, role, scope, status='active')   ← allowlist entry
   ▼
User can now log in with Google. No invite email or password is required.

• First login needs no password change — identity is Google's; there is nothing to set. The first successful OIDC login simply activates the session and (optionally) stamps users.firstLoginAt.
• Admin-only: user:create, user:import (bulk CSV → same allowlist rows), role:assign.

Admin → Users → Deactivate / Delete
   ▼
UPDATE users SET status='disabled'      (or hard-delete)
   ▼
- Future logins: DB allowlist check (gate b) fails → DENY.
- Existing sessions: revoked immediately via session-version bump (§3.6).
- Server-side OAuth tokens for that user are revoked + purged.
- AuditLog row written (actor=admin, action=user.deactivate).

Sessions are server-side and opaque. The browser holds nothing sensitive.

The session record holds: sessionId (opaque, ≥128-bit random), userId, sessionVersion, createdAt, lastSeenAt, absoluteExpiry, ip, userAgent, and a server-side reference to the OAuth access_token / refresh_token.

Set-Cookie: sid=<opaque-random>;
            HttpOnly;            ← JS cannot read it (XSS-resistant)
            Secure;              ← HTTPS only
            SameSite=Lax;        ← CSRF mitigation (Strict for admin paths)
            Path=/;              ← scoped
            Max-Age=<rolling>;   ← rolling expiry

• No JWT, no tokens, no role, no PII in cookies or localStorage/sessionStorage. The cookie value is a meaningless opaque id; all meaning lives server-side.
• OAuth access/refresh tokens are stored server-side only, encrypted at rest (KMS, §8). They are never sent to the browser.

When the Google access_token nears expiry, the server uses the stored refresh_token to obtain a new one and updates the server-side record. The browser is never involved and never sees a token.

State-changing requests (POST/PUT/PATCH/DELETE) are protected by two mechanisms:

1. SameSite cookie (Lax/Strict) — blocks most cross-site cookie attachment.
2. Double-submit / synchronizer token — the API issues a CSRF token; the client echoes it in a header (X-CSRF-Token); the server compares it to the session-bound value. Origin/Referer is also checked for sensitive endpoints.

Logout:              DELETE session(sid) from store; clear cookie; revoke OAuth tokens; audit.
Log out everywhere:  UPDATE users.sessionVersion += 1
                     → every existing session whose stored version < current is invalidated
                       on its next request. Used on suspension, role change, suspected compromise.

• Clock skew: ID-token exp/iat/nbf validated with ≤ 60s leeway; ECS tasks sync via Amazon Time Sync.
• Replay: OIDC nonce + state are single-use and bound to the originating request; reused/forged values are rejected. Session ids are high-entropy and non-guessable; cookie theft is mitigated by HttpOnly/Secure/short idle window + version bump on suspicion.

Authorization answers two questions independently: what may this role do? (action) and to which records? (scope). They are combined in a single policy function and enforced at three layers, server-side.

⚠️ Callout — Team Lead is NOT a 6th role. A refactor prompt re-listed "Team Lead" as a sixth role, but a prior product decision merged Team Lead into the Mentor: the Student Mentor leads the team, holding both mentee-management and team-delivery permissions. This system uses 5 roles. Re-adding Team Lead later is a small config change (one role entry + matrix column + a scopeWhere branch) if and only if the product owner explicitly confirms it. Until then, do not implement a 6th role.

GLOBAL                         (Admin, LCC)              all records
  ⊃ DOMAIN:<id>                (Teacher)                 records under a domain (≥1 per teacher)
       ⊃ TEAM:<id>             (Mentor)                  records under an assigned team
            ⊃ SELF             (Mentee)                  records the user owns

GLOBAL ⊇ DOMAIN ⊇ TEAM ⊇ SELF, matched by id. A user may hold multiple scoped roles; effective access = union of scopes for the action's required permission. (A teacher with two domains → DOMAIN:1 ∪ DOMAIN:2.)

Legend: ✅ full/global · 🔵 scoped (own assigned domain/team/self) · 👁 read-only · ➖ none

// server/authz/policy.ts — the single decision point
can(user: AuthContext, action: Permission, resource?: Resource): boolean

Step 1 — ROLE check    : does any of user.roles grant `action`?           else → false
Step 2 — SCOPE check   : if `resource` given, does the granting role's
                         scope cover it?  GLOBAL ⊇ DOMAIN ⊇ TEAM ⊇ SELF,
                         matched by id (union across the user's roles)      else → false
Step 3 — OWNERSHIP     : for SELF actions, resource.ownerId === user.id     else → false
                         for DOMAIN/TEAM, resource.domainId/teamId ∈ user's assigned set
Return true only if all applicable steps pass.

The same can() is called by the server (authoritative) and by the UI (hint only — never trusted; the server re-decides every time).

Request (cookie sid)
  │
  ▼
LAYER 1 — Route gate (Express middleware)
  │  authenticate(sid) → AuthContext; is this route allowed for the role?   ──▶ 401/403
  ▼
LAYER 2 — Policy check
  │  zod.validate(input)                                                     ──▶ 400
  │  can(ctx, action, resource)                                             ──▶ 403
  ▼
LAYER 3 — DB-query scoping
  │  service.method(ctx, …) where every query is wrapped in scopeWhere(ctx) ──▶ rows
  │  → out-of-scope rows are physically unreachable even if layers 1–2 had a bug
  ▼
  audit(ctx, action, before/after)  →  typed response (no internal leakage)

            ┌──────────────────────┐
 request ──▶│ valid session? (sid) │──no──▶ 401
            └──────────┬───────────┘
                       │ yes
            ┌──────────▼───────────┐
            │ route allowed for    │──no──▶ 403
            │ role? (gate)         │
            └──────────┬───────────┘
                       │ yes
            ┌──────────▼───────────┐
            │ input valid? (zod)   │──no──▶ 400
            └──────────┬───────────┘
                       │ yes
            ┌──────────▼───────────┐
            │ can(user,action,res) │──no──▶ 403
            └──────────┬───────────┘
                       │ yes
            ┌──────────▼───────────┐
            │ scopeWhere filters   │──▶ only in-scope rows
            │ the DB query         │
            └──────────┬───────────┘
                       ▼
                audit + response

• Teacher (multi-domain): a teacher assigned to domains {7, 9} listing students → scopeWhere resolves to { team: { domainId: { in: [7,9] } } }. Students in domain 12 are unreachable. Teachers can span multiple domains — the filter is in, not =.
• Mentor: listing reviews → { menteeId: { in: assignedMenteeIds(me) } } (i.e. TEAM:<assignedTeamId>). Mentees on other teams are unreachable. The Student Mentor also sees team-delivery resources for their team only.
• Mentee: listing tasks/reviews/feedback → { ownerId: me } (SELF). Cannot see anyone else's records.
• Admin: GLOBAL → no scope filter.

Authorization is not only a route check. Every service method injects the caller's scope into the SQL/ORM query, so a logic bug elsewhere still cannot return out-of-scope rows.

// server/authz/scope.ts — returns the Prisma `where` for the caller's highest applicable scope
function listTeams(ctx: AuthContext) {
  return prisma.team.findMany({
    where: scopeWhere(ctx, {
      global: {},                                            // Admin / LCC
      domain: { domainId: { in: ctx.assignedDomainIds } },   // Teacher (multi-domain)
      team:   { id: { in: ctx.assignedTeamIds } },           // Mentor
      self:   { members: { some: { userId: ctx.userId } } }, // Mentee
    }),
  });
}

// Reviews — a Mentor physically cannot read another team's reviews
function listReviews(ctx: AuthContext) {
  return prisma.review.findMany({
    where: scopeWhere(ctx, {
      global: {},
      domain: { team: { domainId: { in: ctx.assignedDomainIds } } },
      team:   { menteeId: { in: ctx.assignedMenteeIds } },
      self:   { menteeId: ctx.userId },
    }),
  });
}

• Domain isolation: domainId ∈ assignedDomainIds. Cross-domain reads are impossible at the query layer.
• Team isolation: teamId ∈ assignedTeamIds. Cross-team reads impossible.
• Ownership checks: for SELF actions and for mutations, the service re-verifies resource.ownerId === ctx.userId before write — preventing IDOR even on direct-id access (GET /reviews/:id).

scopeWhere() selects the highest applicable scope for the caller and always applies a filter (default deny: an unrecognized scope yields an impossible WHERE clause, not an open one).

This account also runs OTHER unrelated services. This platform must have ZERO blast radius into them. "Lateral movement into other tenants' services in the shared account" is treated as an explicit, first-class threat. See infra-ecs.md for the concrete Terraform.

AWS Account (shared)
│
├── ▓▓▓ Forge boundary ▓▓▓ (dedicated, tagged app=forge)
│   │
│   ├── Dedicated VPC (own CIDR)            ── no peering, no Transit GW to other VPCs
│   │   ├── Public subnets   → ALB only
│   │   ├── Private subnets  → ECS (Next.js, Express)  [no public IPs]
│   │   └── Isolated subnets → RDS, Redis              [not publicly reachable]
│   │
│   ├── Dedicated Security Groups (least privilege, §6.2)
│   ├── Dedicated IAM roles (ARN-scoped + tag-conditioned, no wildcards, §6.3)
│   ├── Dedicated KMS CMK (RDS, Secrets, EBS, S3)
│   └── Secrets Manager namespace /forge/*  (§6.4, §9)
│
└── ░░░ OTHER services ░░░  ── separate VPCs / IAM / KMS / Secrets
        ▲
        └──── UNREACHABLE from Forge: no SG rule, no IAM grant, no network path.

No 0.0.0.0/0 ingress anywhere except the ALB's Cloudflare-restricted 443. No security group references any SG outside the Forge boundary.

// ECS task role — illustrative; NO "Resource": "*", NO "*:*" actions
{
  "Effect": "Allow",
  "Action": ["secretsmanager:GetSecretValue"],
  "Resource": "arn:aws:secretsmanager:<region>:<acct>:secret:/forge/*",
  "Condition": { "StringEquals": { "aws:ResourceTag/app": "forge" } }
},
{
  "Effect": "Allow",
  "Action": ["kms:Decrypt", "kms:GenerateDataKey"],
  "Resource": "arn:aws:kms:<region>:<acct>:key/<forge-cmk-id>"
}

• Task roles can read only /forge/* secrets and use only the Forge CMK.
• No iam:*, no sts:AssumeRole into other roles, no cross-service s3:*/ec2:* wildcards.
• Conditions pin every grant to aws:ResourceTag/app = forge.

• Secrets Manager: all secrets under /forge/*; task roles cannot read other namespaces.
• Dedicated KMS CMK encrypts RDS, Secrets, EBS volumes, and any S3 buckets — its key policy grants decrypt only to Forge roles.
• Private subnets / no public IPs for ECS; RDS is not publicly accessible (no public route, isolated subnet group).
• No VPC peering / Transit Gateway to other services' VPCs. Egress only via NAT to named external endpoints (Google, GitHub, Discord).

Explicit guarantee: a full compromise of the Forge application (RCE in the Express container) yields, at most, the Forge CMK-decryptable data and /forge/* secrets within the Forge VPC. It cannot read other services' secrets, decrypt their data, assume their IAM roles, or reach their networks. Blast radius is contained to Forge.

User ──TLS──▶ Cloudflare ──TLS (origin cert / mTLS)──▶ ALB ──TLS──▶ ECS (Next.js)
                                                              └─TLS─▶ ECS (Express)
Express ──TLS (sslmode=require)──▶ RDS Postgres
Express ──TLS──▶ Redis (in-transit encryption enabled)

TLS 1.2+ everywhere. RDS connection string enforces sslmode=require (verify-full where the CA is pinned).

• RDS: encrypted with the Forge KMS CMK.
• Secrets Manager: encrypted with the same CMK.
• EBS (ECS task ephemeral/volumes) and S3 (uploads): CMK-encrypted.
• OAuth access/refresh tokens and integration credentials: encrypted at rest server-side.

• PII access (student/mentor identities, performance metrics, feedback) is gated by RBAC scope (§4–§5).
• Anonymous concerns: Concern.anonymous = true strips reporter identity from all reads except Admin/LCC under concern:readAnonymous; raiser identity is not stored against the visible record.
• Retention: configurable windows per data class; expired records purged/anonymized by a scheduled job; audit logs retained per policy.

• AWS Secrets Manager, namespaced under /forge/* (e.g. /forge/db, /forge/google-oidc, /forge/github, /forge/discord, /forge/session).
• Rotation enabled (DB credentials, integration secrets) via Secrets Manager rotation.
• Injected into ECS tasks at runtime (task definition secrets: → env), read via the ARN-scoped task role (§6.3). Never baked into images or committed env files in prod.
• Local dev uses git-ignored .env; only NEXT_PUBLIC_* variables ever reach the browser bundle — server secrets (OIDC client secret, webhook secrets, bot tokens, DB URL) are server-only. See integration-setup.md for which keys are required.

AuditLog is append-only / immutable (insert-only table; no UPDATE/DELETE grant to the app role).

Tracked events: login / logout (and OIDC denials), role & permission/scope changes, user CRUD + de-provisioning, concern actions (raise/triage/resolve, incl. anonymous), email sends / bulk sends / template changes, integration connect/disconnect, config changes, and all admin actions.

Audit writes happen in the service layer (the last step of the request lifecycle, §4.5), so no privileged action can bypass logging. Admin → Audit Logs reads with filters (actor, action, entity, date).

• MFA: inherent — Google/Workspace accounts enforce the institution's 2FA. No separate MFA to build.
• SSO: already Google (OIDC). Additional providers (Microsoft/other Workspace orgs) would be additive, behind the same dual-gate allowlist.
• Fine-grained permissions (future): the permission set is data-extensible (resource:action strings); new permissions and scopes slot into the matrix + can() without rewrites.
• Re-adding Team Lead (future): small config change (§4.1) — only if the product owner confirms; default remains 5 roles.
• Security audits / compliance (future): immutable audit log, scoped access, encryption, and account isolation are already in place to support external review and penetration testing.

See also: architecture-v2.md · infra-ecs.md · integration-setup.md.