@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/codex/security-audit-log-design/SKILL.md

@@ -0,0 +1,227 @@
+# Audit Log Design
+
+> Log the who, what, when, where, and outcome of every security-relevant event in a
+> structured, tamper-evident format that enables both real-time detection and forensic
+> reconstruction
+
+## When to Use
+
+- Designing the logging infrastructure for a new application or service
+- Adding security event logging to an existing system that lacks audit trails
+- Preparing for SOC2, ISO 27001, HIPAA, or PCI-DSS compliance audits
+- Investigating a security incident and discovering logging gaps
+- Choosing between application-level and infrastructure-level audit logging
+- Designing tamper-evident log storage for high-assurance environments
+
+## Threat Context
+
+Attackers who gain access to a system routinely attempt to cover their tracks by deleting or
+modifying logs. Log tampering is not theoretical -- it is standard attacker tradecraft:
+
+- **SolarWinds (2020)**: The attackers specifically targeted logging and monitoring
+  infrastructure to evade detection, disabling security tools and modifying logs to remove
+  evidence of their presence. They remained undetected for 9+ months.
+- **Detection time without logging**: The IBM/Ponemon Cost of a Data Breach Report
+  consistently finds that organizations without adequate security logging take 200+ days to
+  detect a breach. Organizations with security AI and automation (which depends on structured
+  log data) detect breaches 108 days faster.
+- **Compliance requirements**: SOC2 Trust Services Criteria CC7.2 requires monitoring of
+  system components for anomalies. PCI-DSS Requirement 10 mandates audit trails for all
+  access to cardholder data. HIPAA requires audit controls for electronic protected health
+  information. ISO 27001 A.12.4 requires event logging, protection of log information, and
+  administrator/operator logs. Failure to maintain adequate logs results in audit findings,
+  regulatory penalties, and inability to investigate incidents.
+- **Legal and forensic value**: Audit logs are legal evidence. In breach litigation,
+  regulators and courts expect timestamped, tamper-evident records of what happened. Without
+  them, the organization cannot demonstrate due diligence or reconstruct the incident
+  timeline.
+
+Logging is not optional overhead -- it is the immune system of the application. A system
+without audit logging is a system where breaches are invisible.
+
+## Instructions
+
+1. **Define the security-relevant events that must be logged.** At minimum, capture these
+   event categories:
+   - **Authentication events**: Login success, login failure (with username attempted),
+     logout, MFA challenge issued, MFA challenge success/failure, password change, password
+     reset request, account lockout
+   - **Authorization events**: Access granted, access denied, permission change, role
+     assignment, role revocation, privilege escalation attempt
+   - **Data access events**: Read of sensitive data (PII, financial, health), bulk data
+     export, bulk query execution, data download
+   - **Administrative actions**: User creation, user deletion, user modification, role
+     creation, configuration change, feature flag change, deployment, certificate rotation
+   - **System events**: Application startup, application shutdown, dependency failure,
+     database migration, backup execution
+   - **Anomalous events**: Rate limit triggered, input validation rejection, WAF block,
+     unexpected error, authentication from new device/location
+
+2. **Use a structured event format for every audit entry.** Every audit event must include
+   these fields:
+   - `timestamp`: ISO 8601 with timezone, always UTC (e.g., `2024-01-15T14:30:00.123Z`)
+   - `event_type`: Enumerated, dot-separated category (e.g., `auth.login.success`,
+     `authz.permission.denied`, `data.export.initiated`)
+   - `actor`: Who performed the action -- user ID, service account name, or `system` for
+     automated processes
+   - `action`: The verb -- `create`, `read`, `update`, `delete`, `login`, `logout`,
+     `export`, `deny`
+   - `resource`: What was acted upon -- resource type and identifier (e.g., `user:u-12345`,
+     `order:o-67890`, `config:feature-flags`)
+   - `outcome`: `success` or `failure`, with `reason` for failures (e.g.,
+     `insufficient_permissions`, `invalid_credentials`, `rate_limited`)
+   - `source_ip`: The IP address of the request origin
+   - `session_id`: Session or request correlation ID for linking related events
+   - `metadata`: Additional context -- user agent, request path, changed fields for update
+     operations, previous and new values for configuration changes
+
+3. **Log at the application layer, not just infrastructure.** Infrastructure logs (web
+   server access logs, firewall logs, load balancer logs) capture network-level events but
+   miss application-level semantics. The infrastructure sees
+   `GET /api/customers?limit=99999 200 OK`. The application knows "User 123 exported all
+   50,000 customer records to CSV." Both are needed; the application event is far more
+   actionable for security investigation. Implement audit logging as a first-class
+   application concern, not an afterthought bolted onto HTTP middleware.
+
+4. **Make logs tamper-evident.** An attacker who compromises the application server will
+   attempt to delete or modify logs to cover their tracks. Tamper evidence ensures
+   modifications are detectable:
+   - **Write-once storage**: S3 Object Lock (Governance or Compliance mode), Azure Immutable
+     Blob Storage, GCP Bucket Lock, WORM (Write Once Read Many) storage. Once written, log
+     entries cannot be modified or deleted for the retention period.
+   - **Hash chaining**: Each log entry includes
+     `entry_hash = SHA-256(entry_data + previous_entry_hash)`. The first entry uses a known
+     sentinel value. Any modification, deletion, or insertion of entries breaks the hash
+     chain from that point forward.
+   - **Real-time forwarding**: Forward logs to an independent, append-only log aggregator
+     (Splunk, Elasticsearch/OpenSearch, CloudWatch Logs, Datadog) in real time via syslog,
+     Fluentd, or direct API integration. The application server's local logs are not the
+     sole copy.
+   - **Digital signatures**: Sign log batches with a key held in an HSM or KMS. Provides
+     non-repudiation -- the logs can be verified as authentic even if the logging
+     infrastructure is later compromised.
+
+5. **Never log secrets or PII unnecessarily.** Audit logs must not contain passwords, API
+   keys, session tokens, credit card numbers, social security numbers, or other sensitive
+   data. Log the fact that an action occurred, not the sensitive content. Correct: "User
+   u-12345 updated their password at 2024-01-15T14:30:00Z." Incorrect: "User u-12345
+   changed password from 'oldpass123' to 'newpass456'." For PII, log only the minimum needed
+   for investigation -- user ID rather than full name and email, unless specific compliance
+   requirements mandate otherwise. Implement log scrubbing as a safety net: regex-based
+   filters that detect and redact patterns matching known secret formats before log entries
+   are written.
+
+6. **Define retention and archival policies aligned with compliance requirements.** Common
+   minimums: SOC2 requires 1 year of audit log retention. PCI-DSS requires 1 year with 3
+   months immediately accessible for analysis. HIPAA requires 6 years. GDPR does not specify
+   a retention period but requires that retention be justified and proportionate. Archive
+   older logs to cold storage (S3 Glacier, Azure Cool/Archive Blob) to manage costs, but
+   ensure archived logs remain searchable and verifiable. Test restoration from cold storage
+   regularly -- logs that cannot be retrieved when needed are equivalent to no logs.
+
+7. **Alert on high-severity events in real time.** Logs that are only read during
+   post-incident investigation provide forensic value but no detection value. Configure
+   real-time alerts for: multiple failed login attempts from a single IP or against a single
+   account (brute force, credential stuffing), privilege escalation events, access to
+   sensitive data outside normal patterns (time of day, volume, geographic location),
+   administrative actions from unusual source IPs, any `outcome: failure` on critical
+   operations (payment processing, data export), and new device/location for privileged
+   accounts. Route alerts to the security team's incident response channel (PagerDuty,
+   Slack, email) with enough context to triage without reading raw logs.
+
+## Details
+
+- **The OWASP Logging Cheat Sheet event categories**: Authentication (success, failure,
+  lockout), Authorization (access granted, denied, permission changes), Session management
+  (creation, destruction, timeout, concurrent session detection), Input validation failures
+  (rejected input, WAF blocks, malformed requests), Application errors (unhandled
+  exceptions, dependency failures, timeout events), High-value transactions (financial
+  operations, data exports, bulk operations, configuration changes). Use this as a starting
+  checklist and add domain-specific events for your application.
+
+- **Structured logging format example**: A complete JSON audit event:
+
+  ```json
+  {
+    "timestamp": "2024-01-15T14:30:00.123Z",
+    "event_type": "authz.permission.denied",
+    "actor": { "user_id": "u-123", "session_id": "s-456", "service": "order-api" },
+    "action": "delete",
+    "resource": { "type": "order", "id": "o-789" },
+    "outcome": "failure",
+    "reason": "insufficient_permissions",
+    "source_ip": "198.51.100.42",
+    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
+    "request_id": "req-abc-def",
+    "metadata": {
+      "required_permission": "order:delete",
+      "actual_permissions": ["order:read", "order:update"]
+    }
+  }
+  ```
+
+  Use an enumerated `event_type` taxonomy defined in code so events can be queried
+  consistently across services. Avoid free-text event descriptions that vary between
+  developers.
+
+- **Tamper evidence with hash chaining in detail**: Each log entry includes:
+  `entry_hash = SHA-256(canonical_json(entry_data) + previous_entry_hash)`. The first entry
+  uses a well-known sentinel (e.g., `SHA-256("GENESIS")`) as the "previous hash."
+  Verification: recompute the chain from any starting point. If any entry has been modified,
+  deleted, or inserted, all subsequent hashes fail verification. Store periodic "anchor
+  hashes" in an independent system (a separate database, a blockchain, a signed timestamping
+  service) so that the integrity of the chain can be verified even if the primary log store
+  is compromised. This technique is used by AWS CloudTrail log file integrity validation.
+
+- **Log levels vs audit events -- they are different concerns**: Application log levels
+  (DEBUG, INFO, WARN, ERROR) serve operational troubleshooting. Audit events record
+  security-relevant business events regardless of severity. A successful login is not an
+  "error" or a "warning" -- it is a security event that must be recorded. Implement audit
+  logging as a separate subsystem with its own transport, storage, and retention. Do not
+  rely on application log level configuration to control audit event emission -- changing the
+  log level to WARN to reduce noise must never suppress security audit events.
+
+## Anti-Patterns
+
+1. **No logging of failed authentication attempts.** Failed logins are the single most
+   important signal for detecting brute force attacks, credential stuffing campaigns, and
+   account takeover attempts. An application that only logs successful logins is blind to the
+   10,000 failed attempts that preceded the one successful compromise.
+
+2. **Logging everything at DEBUG level in production.** Produces such volume that security
+   events are buried in noise. Debug logging also risks exposing sensitive data -- request
+   bodies containing passwords, internal state containing encryption keys, SQL queries
+   containing user data. Use structured audit events for security concerns, not verbose debug
+   output. Keep DEBUG logging disabled in production or restricted to specific components
+   during active troubleshooting.
+
+3. **Logs stored only on the application server.** If the server is compromised, the
+   attacker deletes the local logs and the evidence is gone. Always forward logs to an
+   independent aggregator in real time. The local log file on the application server should
+   be treated as a buffer, not as the permanent record.
+
+4. **No correlation IDs across services.** In a distributed system, a single user action may
+   span multiple services. Without a request or correlation ID propagated through all service
+   calls and included in every audit event, reconstructing an attack timeline requires manual
+   timestamp correlation across dozens of log sources -- slow, error-prone, and often
+   impossible when clocks are skewed. Propagate a correlation ID (via HTTP header, message
+   metadata, or distributed tracing context) and include it in every audit event.
+
+5. **Audit logging as an afterthought, added post-launch.** The most vulnerable period for
+   an application is immediately after launch -- configuration is fresh, security hardening
+   is incomplete, and the team is still learning the system's behavior. Adding audit logging
+   weeks or months after launch means this critical period has no audit trail. Design and
+   implement audit logging alongside the feature it monitors, shipping them together.
+
+6. **Logging PII in violation of privacy regulations.** Audit logs that contain full names,
+   email addresses, phone numbers, IP addresses (considered PII under GDPR), or health
+   information create a secondary data protection liability. The audit log itself becomes a
+   sensitive data store requiring access controls, encryption, and data subject access
+   request handling. Log the minimum identifiers needed (user IDs, resource IDs) and join
+   with the primary data store only when investigation requires it.
+
+7. **Alert fatigue from poorly tuned thresholds.** Alerting on every failed login produces
+   thousands of alerts per day, all ignored. Tune alert thresholds to reduce false positives:
+   alert on 10+ failed logins from a single IP in 5 minutes, not on individual failures. Use
+   progressive escalation: first alert goes to a Slack channel, repeated alerts page the
+   on-call engineer. Review and adjust thresholds monthly based on alert-to-incident ratio.

package/dist/agents/skills/codex/security-audit-log-design/skill.yaml

@@ -0,0 +1,39 @@
+name: security-audit-log-design
+version: "1.0.0"
+description: Security audit log design -- what to log, structured event format, tamper evidence, retention, and the balance between observability and privacy
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - security-log-correlation
+  - security-compliance-logging
+  - security-incident-containment
+  - security-forensics-fundamentals
+  - owasp-logging-monitoring
+stack_signals: []
+keywords:
+  - audit log
+  - security logging
+  - tamper evidence
+  - structured logging
+  - event log
+  - audit trail
+  - log retention
+  - security monitoring
+  - SIEM
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/security-authentication-flows/SKILL.md

@@ -0,0 +1,168 @@
+# Authentication Flows
+
+> Login, registration, password reset, magic links, and SSO -- each flow has distinct attack surfaces and each must be hardened independently
+
+## When to Use
+
+- Designing authentication for a new application from scratch
+- Adding password reset, magic link, or SSO to an existing system
+- Auditing existing authentication flows for enumeration, fixation, or brute-force vulnerabilities
+- Integrating OAuth 2.0 / OIDC with an identity provider
+- Implementing passwordless authentication
+
+## Threat Context
+
+Authentication flows are the primary target for credential stuffing (automated login attempts using breached credentials), account enumeration (determining valid usernames via differing error messages or response times), and session fixation (forcing a known session ID before authentication). The 2021 Facebook data scrape extracted 533 million phone numbers by exploiting the "forgot password" flow's account enumeration behavior -- the flow revealed whether a phone number was registered.
+
+Password reset flows are frequently the weakest link: the 2012 Dropbox breach started with a reused password, but the 2016 disclosure of 68 million accounts was enabled by password reset token predictability. The 2020 SolarWinds SAML golden ticket attack demonstrated that SSO misconfiguration can compromise an entire organization from a single forged assertion. OAuth misconfiguration (open redirects, missing state validation) has been exploited in attacks against Microsoft, Facebook, and Google accounts.
+
+## Instructions
+
+1. **Login flow.** Return identical error messages for "user not found" and "wrong password" -- both should produce "Invalid credentials." Responses must be identical in content, HTTP status code, response size, and timing. Enforce rate limiting per username and per IP: 5 failed attempts trigger a 15-minute lockout per account, 20 failed attempts from one IP trigger a CAPTCHA. Issue a new session ID after successful login (prevents session fixation). Set session cookies with `Secure`, `HttpOnly`, and `SameSite=Lax` flags. Log every authentication attempt (success and failure) with timestamp, IP, user agent, and outcome for security monitoring.
+
+2. **Registration flow.** Validate email ownership before account activation by sending a verification link containing a CSPRNG token (128+ bits). Set token expiration to 24 hours. Prevent account enumeration: if the email already exists, still display "verification email sent" to the registering user, but send the existing account holder a notification ("someone tried to register with your email -- if this was not you, no action is needed"). Never reveal whether an email is already registered through the registration API response, response timing, or HTTP status code.
+
+3. **Password reset flow.** Generate a CSPRNG token (128+ bits), single-use, expiring in 1 hour. Send via email. On submission, invalidate the token immediately (single use prevents the link from being reused if intercepted). Do not reveal whether the email exists -- always display "If an account with this email exists, we sent a reset link." Rate-limit reset requests per email address (max 3 per hour) and per IP (max 10 per hour). When a user changes their password from an authenticated session, require the current password or a fresh MFA challenge to prevent session-hijack-to-password-change attacks.
+
+4. **Magic link flow.** A passwordless authentication flow: user enters email, receives a link containing a CSPRNG token, clicks to authenticate. The token must be single-use, short-lived (15 minutes maximum), and ideally bound to the requesting session or device fingerprint to prevent link forwarding. Email becomes the sole authentication factor -- this means email account compromise equals application account compromise. Evaluate whether this trade-off is acceptable for your threat model. Magic links are vulnerable to email interception, forwarding, and preview pane rendering (some email clients and security scanners fetch URLs automatically, potentially consuming the single-use token).
+
+5. **SSO / OAuth 2.0 / OIDC integration.** Use Authorization Code flow with PKCE (RFC 7636) for all clients, including server-side applications. PKCE prevents authorization code interception even if the redirect happens over an insecure channel. Validate the `state` parameter to prevent CSRF on the OAuth callback. Validate the `nonce` in the ID token to prevent replay attacks. Validate the token issuer (`iss`), audience (`aud`), and expiration (`exp`). Verify the token signature using the IdP's published JWKS. Never use the Implicit flow -- it exposes tokens in URL fragments, browser history, and referrer headers. OAuth 2.1 formally deprecates the Implicit flow.
+
+6. **Account lockout vs rate limiting.** Hard lockout (disable the account after N failed attempts) enables denial of service: an attacker can lock out any targeted account by intentionally submitting wrong passwords repeatedly. Prefer progressive delays: attempts 1-5 are instant, attempts 6-10 incur a 30-second delay, attempts 11+ incur a 5-minute delay and CAPTCHA. Combine per-account delays with per-IP rate limiting and global anomaly detection (alert on distributed credential stuffing patterns: many accounts failing from many IPs at elevated rates).
+
+## Details
+
+### Account Enumeration Taxonomy
+
+Applications leak account existence through multiple channels, and all must be addressed simultaneously:
+
+- **Error message differences:** "User not found" vs "Wrong password" directly reveals registration status. Return identical messages for all failure modes.
+
+- **Timing differences:** Password hash comparison takes measurable time (bcrypt at cost 12 takes ~250ms), but returning immediately for non-existent users is fast (~1ms). An attacker can distinguish registered from unregistered accounts by measuring response time. Defense: always hash a dummy password even when the user does not exist, ensuring constant processing time regardless of account existence.
+
+- **HTTP status codes:** Returning 404 for non-existent users and 401 for wrong passwords leaks the same information as different error messages. Use the same status code (401 or 200 with error body) for both cases.
+
+- **Response body size:** Different error messages may have different byte lengths, detectable even over TLS (traffic analysis). Pad responses to identical sizes or use a generic response structure.
+
+- **Registration and reset flows:** "This email is already registered" on the registration form and "No account with this email" on the reset form both reveal account existence. Both must be addressed with the same "always succeed" pattern described in the Instructions section.
+
+### OAuth 2.0 / OIDC Security Checklist
+
+A complete OAuth/OIDC integration must verify all of the following. Missing any single check creates an exploitable vulnerability:
+
+1. **`state` parameter:** Generate a CSPRNG value, store in the session, include in the authorization request, verify on callback. Prevents CSRF attacks that link the victim's account to the attacker's IdP identity.
+
+2. **PKCE (`code_verifier` / `code_challenge`):** Generate a random verifier, hash it as the challenge, send the challenge in the authorization request, send the verifier in the token exchange. Prevents authorization code interception.
+
+3. **`nonce` in ID token:** Include a random nonce in the authorization request, verify it appears in the returned ID token. Prevents token replay from a previous authentication session.
+
+4. **Issuer (`iss`) validation:** The ID token issuer must match the expected IdP. Prevents token substitution from a different IdP.
+
+5. **Audience (`aud`) validation:** The ID token audience must include your client ID. Prevents tokens intended for a different application from being accepted by yours.
+
+6. **Signature verification:** Verify the ID token signature using the IdP's JWKS endpoint keys. Cache keys but support rotation (refetch on `kid` mismatch).
+
+7. **Expiration (`exp`) and issued-at (`iat`):** Reject expired tokens. Reject tokens with `iat` too far in the past (clock skew tolerance of 30-60 seconds is typical).
+
+8. **`redirect_uri` validation:** The callback URL must exactly match the registered redirect URI. No wildcards, no path traversal, no open redirects.
+
+9. **Token storage:** Store access tokens and refresh tokens in httpOnly cookies or server-side sessions. Never in localStorage (XSS-extractable) or URL parameters (logged everywhere).
+
+10. **Token refresh with rotation:** When refreshing, the IdP should issue a new refresh token and invalidate the old one. This limits the window of exposure for a stolen refresh token.
+
+### Passwordless Authentication Comparison
+
+| Method                   | Phishing Resistant | Email Dependent      | Device Dependent             | Recovery Complexity   |
+| ------------------------ | ------------------ | -------------------- | ---------------------------- | --------------------- |
+| Magic links              | No                 | Yes                  | No                           | Low (email access)    |
+| WebAuthn/Passkeys        | Yes                | No                   | Yes (synced passkeys reduce) | Medium (backup key)   |
+| Email OTP (6-digit code) | No                 | Yes                  | No                           | Low (email access)    |
+| SMS OTP                  | No                 | No (phone dependent) | Yes                          | Medium (SIM recovery) |
+
+Magic links and email OTP are functionally equivalent in security -- both depend entirely on email account security. WebAuthn/passkeys are the only phishing-resistant passwordless option. Synced passkeys (iCloud, Google) reduce device dependency but introduce cloud account security as a dependency. For high-security applications, non-synced hardware keys (YubiKey) provide the strongest guarantees at the cost of recovery complexity.
+
+### Credential Stuffing Defense Architecture
+
+Credential stuffing is the automated injection of breached username/password pairs into login forms. At scale, attackers use botnets to distribute attempts across thousands of IP addresses, defeating simple per-IP rate limiting.
+
+A layered defense architecture:
+
+1. **Layer 1 -- Rate limiting:** Per-account limits (5 failures per 15 minutes), per-IP limits (20 failures per hour), and global limits (alert on >1000 failures per minute across all accounts).
+2. **Layer 2 -- CAPTCHA escalation:** After exceeding the per-account threshold, require CAPTCHA. Use invisible CAPTCHA initially (no friction for legitimate users) and escalate to interactive CAPTCHA after further failures.
+3. **Layer 3 -- Credential breach checking:** On successful login, check the password against known breach databases (Have I Been Pwned API with k-anonymity, or a local bloom filter of breached password hashes). If the password appears in a breach database, force a password change.
+4. **Layer 4 -- Anomaly detection:** Monitor login patterns for distributed attacks (many accounts failing from many IPs in a short window). This catches botnets that stay under per-IP limits.
+5. **Layer 5 -- MFA:** The strongest defense. Even if the credential is valid, the attacker cannot complete authentication without the second factor.
+
+### Session Fixation Prevention
+
+The session fixation attack proceeds in three steps:
+
+1. The attacker obtains a valid, unauthenticated session ID from the application (by visiting the login page).
+2. The attacker injects this session ID into the victim's browser via a URL parameter like `?JSESSIONID=abc123`, cookie injection through a subdomain the attacker controls, or a meta tag injection via XSS.
+3. The victim logs in using the attacker's session ID. The server authenticates the session but does not change the ID. The attacker now holds an authenticated session because they know the session ID.
+
+Defense: always regenerate the session ID upon successful authentication. In most frameworks this is an explicit call:
+
+- **Express (Node.js):** `request.session.regenerate(callback)`
+- **Java Servlet:** `session.invalidate()` followed by `request.getSession(true)`
+- **Rails:** `request.reset_session` or `request.session.options[:renew] = true`
+- **Django:** `request.session.cycle_key()`
+- **Flask:** `session.regenerate()` (with Flask-Session)
+- **Spring Security:** Handled automatically by `SessionFixationProtectionStrategy`
+
+Never accept session IDs from URL parameters -- session IDs must travel exclusively in cookies with `Secure`, `HttpOnly`, and `SameSite` attributes.
+
+### Authentication Event Logging
+
+Every authentication-related event should be logged for security monitoring, incident response, and compliance:
+
+- **Login success:** Timestamp, user ID, IP address, user agent, authentication method (password, SSO, magic link, passkey), MFA method used, session ID (hashed)
+- **Login failure:** Timestamp, attempted user ID, IP address, user agent, failure reason (invalid credentials, account locked, MFA failed, expired token)
+- **Password change:** Timestamp, user ID, IP address, method (authenticated change vs reset token)
+- **Password reset request:** Timestamp, email address, IP address (do not log whether the email exists)
+- **MFA enrollment/removal:** Timestamp, user ID, factor type added or removed, IP address
+- **Session termination:** Timestamp, user ID, reason (logout, timeout, forced invalidation)
+- **OAuth events:** Authorization grants, token issuance, token refresh, token revocation, IdP errors
+
+Store authentication logs separately from application logs with longer retention (1-2 years for compliance). Make them immutable (append-only) and tamper-evident. Alert on anomalous patterns: geographic impossibility, credential stuffing signatures, sudden spikes in failed MFA, and unusual OAuth grant patterns.
+
+Authentication logs are the primary data source for detecting account compromise after the fact and for forensic investigation during incident response. They must be detailed enough to reconstruct the full authentication timeline for any user account.
+
+### Choosing an Authentication Architecture
+
+When designing authentication for a new application, choose one of these standard architectures based on the application type:
+
+- **Server-rendered web application:** Session-based authentication with server-side session storage. Cookies carry the session ID. Password + MFA for authentication. CSRF protection via SameSite cookies and CSRF tokens.
+
+- **Single-page application (SPA):** Backend-for-Frontend (BFF) pattern with the BFF server handling OAuth/OIDC and storing tokens server-side. The SPA communicates with the BFF via httpOnly session cookies. Avoid storing tokens in localStorage or sessionStorage.
+
+- **Mobile application:** OAuth 2.0 Authorization Code with PKCE. Store tokens in the platform's secure storage (iOS Keychain, Android Keystore). Use refresh token rotation.
+
+- **API service (machine-to-machine):** OAuth 2.0 Client Credentials flow with short-lived access tokens. Rotate client secrets on a schedule. Consider mTLS for service identity.
+
+- **Microservices internal:** JWT tokens issued by a central auth service, verified by each microservice using the auth service's public key (JWKS). Short expiration (5-15 minutes) with no refresh -- services re-authenticate from the gateway token.
+
+## Anti-Patterns
+
+1. **Different error messages for login failures.** "User not found" vs "Incorrect password" reveals which emails are registered. This information fuels credential stuffing (confirms valid targets) and social engineering (confirms the victim uses your service). Always return "Invalid credentials" regardless of the specific failure mode.
+
+2. **Password reset tokens that are predictable.** Using sequential IDs, timestamps, MD5(email), or any deterministic derivation as reset tokens. Tokens must be 128+ bits of CSPRNG output. Predictable tokens enable unauthenticated account takeover -- the most critical vulnerability class in web applications.
+
+3. **OAuth Implicit flow.** Tokens in URL fragments are logged by web servers, proxy servers, browser extensions, and appear in referrer headers when navigating away from the page. The Implicit flow was formally deprecated by OAuth 2.1. Use Authorization Code with PKCE for all client types including SPAs.
+
+4. **Storing OAuth tokens in localStorage.** Any XSS vulnerability can extract tokens from localStorage via `window.localStorage.getItem()`. Store access tokens in httpOnly, Secure cookies or in server-side sessions. If tokens must be accessible to client-side JavaScript (SPA architecture), use a Backend-for-Frontend (BFF) pattern that keeps tokens server-side and proxies authenticated requests.
+
+5. **No rate limiting on login or password reset.** Without rate limiting, attackers can attempt millions of credential combinations per hour (credential stuffing) or flood the target with reset emails (email bombing, which may also trigger the email provider's rate limits and block legitimate emails to the victim). Rate limit by account, by IP, and apply global anomaly detection thresholds.
+
+6. **Account lockout without progressive delays.** Hard lockout after 5 failures enables denial of service against any targeted user. An attacker who knows the victim's email can lock them out indefinitely by submitting wrong passwords. Use progressive delays (increasing wait time per failed attempt) and CAPTCHA escalation instead of binary lockout. Combine with per-IP rate limiting to catch distributed attacks.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** security-credential-storage, security-session-management, security-mfa-design, security-cryptographic-randomness, owasp-auth-patterns, owasp-csrf-protection, api-authentication-patterns
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/security-authentication-flows/skill.yaml

@@ -0,0 +1,42 @@
+name: security-authentication-flows
+version: '1.0.0'
+description: Secure design of login, registration, password reset, magic link, and SSO authentication flows -- preventing account enumeration, credential theft, and session fixation
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - security-credential-storage
+  - security-session-management
+  - security-mfa-design
+  - security-cryptographic-randomness
+  - owasp-auth-patterns
+  - owasp-csrf-protection
+  - api-authentication-patterns
+stack_signals: []
+keywords:
+  - login
+  - registration
+  - password reset
+  - magic link
+  - SSO
+  - OAuth
+  - OIDC
+  - account enumeration
+  - brute force
+  - credential stuffing
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []