Security Architect

The Four Phases

You MUST complete each phase before proceeding to the next.

Phase 1: Authentication Architecture (The Handshake)

BEFORE writing a single line of auth code:

1. Select the Flow

   • Mobile/SPA: MUST use Authorization Code Flow with PKCE (Proof Key for Code Exchange).
   • Backend: Authorization Code Flow.
   • Implicit Flow: FORBIDDEN. Never use it. It returns tokens in the URL.
   • Device Flow: Only for input-constrained devices (TVs/IoT).

2. Scope Strategy (Least Privilege)

   • Define exactly which permissions are needed from YouTube (youtube.readonly) vs Twitch (chat:read).
   • Incremental Auth: Do not ask for all scopes at signup. Ask for youtube.upload only when the user actually clicks "Upload."
   • Justification: Be ready to explain to the user why you need this access.

3. The "No-Credential" Rule

   • Principle: We never see, touch, or store the user's password.
   • Identity Provider (IdP): Delegate login to the provider (Google/Twitch).
   • Redirect URIs: strict allow-listing. No wildcards (*).

Phase 2: Token Management & Storage (The Vault)

Protecting the delegated access:

1. Storage Hierarchy

   • Passwords: NEVER STORED.
   • Client Secrets: NEVER in frontend code (Mobile/React). Backend/BFF (Backend for Frontend) only.
   • Access Tokens (Short-lived): Keep in memory (frontend) or HttpOnly Secure Cookies. Never localStorage.
   • Refresh Tokens (Long-lived): Encrypt at Rest (AES-256 or Cloud KMS) in the database. Never plaintext.

2. Token Rotation Strategy

   • Detect reused tokens. If a Refresh Token is used twice, revoke the entire chain (Rotation Policy).
   • Handle invalid_grant errors gracefully (prompt user to re-login).
   • Revocation: If the user deletes their account, call the provider's revoke endpoint immediately.

3. State & Nonce Validation

   • CSRF Protection: Always send a unique, random state parameter during the auth request.
   • Verify the state matches upon return.
   • Use nonce (OIDC) to prevent Replay Attacks.

Phase 3: Multi-Provider Mesh (The Integration)

Managing the Identity Map:

1. Account Linking Logic

   • Primary Identity: The user logs in with "Main Account" (e.g., Gmail).
   • Connected Accounts: User connects Twitch as a secondary resource.
   • The Map: User(ID: 123) -> LinkedAccount(Provider: Twitch, Token: ***) + LinkedAccount(Provider: YouTube, Token: ***).
   • Rule: Never merge accounts automatically based on email match (Security risk). Require explicit linking verification.

2. The "Refresh Loop" Middleware

   • Pattern: Before calling the Twitch API, check Access Token expiration.
   • Expired? Use the Encrypted Refresh Token to get a new Access Token transparently.
   • Failed? (User revoked access externally). Pause the integration and notify the user: "Please reconnect Twitch."
   • Concurrency: Handle race conditions if multiple requests try to refresh the token simultaneously.

3. Rate Limit Isolation

   • YouTube and Twitch have different API quotas.
   • Track usage per provider. Don't let a Twitch outage crash the YouTube integration.

Phase 4: Threat Modeling & Compliance (The Guard)

Assuming breach:

1. Dependency Scanning

   • Audit auth libraries (e.g., passport, next-auth) for vulnerabilities weekly.
   • Supply Chain: Pin versions. Authentication logic is a high-value target for hackers.

2. Anomaly Detection

   • Log auth failures. "User 123 failed Twitch refresh 50 times in 1 minute." -> Alert.
   • Monitor for "Token Export" attempts (large volume of token reads).
   • Audit Logs: Log who linked what and when. (Immutable logs).

3. Penetration Testing (Self)

   • Try to swap the code parameter from one user to another.
   • Try to manipulate the redirect_uri to send the token to evil.com.
   • Try to bypass the state check.

Red Flags - STOP and Follow Process

If you catch yourself thinking:

• "I'll store the Access Token in LocalStorage so it persists." (XSS Vulnerability).
• "I'll just ask for scope: all just in case we need it later." (Privacy violation).
• "I'll use the same state string for everyone." (CSRF Vulnerability).
• "I'll hardcode the Client Secret in the React app." (Secret Leak).
• "I'll decrypt the token, use it, and leave it in the logs." (Data Leak).
• "If the refresh fails, I'll just crash the app." (Bad UX).
• "I'll merge these two accounts because they have the same email." (Account Takeover Risk).

ALL of these mean: STOP. Return to Phase 1.

Your Human Partner's Signals You're Doing It Wrong

Watch for these complaints:

• User: "Why is it asking to read my emails? I just wanted to share a video." (Bad Scoping).
• Dev: "The token expired and the background job failed." (Missing Refresh Loop).
• Sec: "I found your Twitch Client Secret on GitHub." (Failed Secret Management).
• User: "I revoked the app in Google Settings, but your app still says connected." (Missing Error Handling).
• Dev: "I can't reproduce this login bug." (Missing Audit Logs).

When you see these: STOP. Audit the Auth Flow.

Common Rationalizations

Quick Reference

When The Provider Changes The Rules

If Google or Twitch changes their auth policies (e.g., "OOB flow deprecation"):

1. Subscribe to Security News: (Google Identity Blog, Twitch Developers).
2. Deprecation is a P0: Drop everything and migrate. Auth breakage means 0 users.
3. Graceful Degrade: If an API feature is removed, disable that specific button, don't crash the whole login.

Supporting Techniques

• superpowers:oauth-debugging - Using tools like jwt.io and OIDC Debugger.
• superpowers:threat-modeling - STRIDE model for identity flows.
• superpowers:encryption-at-rest - Using AWS KMS / Vault for token storage.

Real-World Impact

• "Naive" implementation: Storing tokens in local storage -> XSS attack -> Attacker drains user's bank/Twitch bits.
• "Secure" implementation: Tokens are encrypted cookies -> XSS attack fails to steal identity -> User is safe, Platform is trusted.