@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/codex/security-code-signing/SKILL.md

@@ -0,0 +1,155 @@
+# Code and Artifact Signing
+
+> Sign every artifact you produce and verify every artifact you consume -- because an unsigned
+> binary could have been built by anyone, including an attacker
+
+## When to Use
+
+- Publishing container images, packages, or binaries that users need to verify as authentic
+- Implementing a deployment pipeline that rejects unsigned or untrusted artifacts
+- Signing git commits and tags for non-repudiation of source changes
+- Evaluating Sigstore (cosign, Fulcio, Rekor) for keyless signing workflows
+- Meeting compliance requirements for software integrity and chain of custody
+- Establishing a trusted publisher policy for your organization's artifact registries
+
+## Threat Context
+
+The 2020 SolarWinds attack injected the SUNBURST backdoor into a legitimate build artifact by
+compromising the build pipeline. The artifact was signed with SolarWinds' code signing
+certificate, making it appear trustworthy. Code signing alone did not prevent this attack because
+the signing happened after the malicious code was injected. This demonstrates that code signing
+proves who built the artifact but not whether the build process was compromised -- build
+provenance (SLSA) addresses that complementary concern.
+
+Without artifact signing, any entity with write access to a container registry, package
+repository, or download server can replace a legitimate artifact with a malicious one. A
+man-in-the-middle on the registry network path, a compromised CI/CD credential, or a rogue
+insider can publish a trojaned artifact that downstream consumers deploy without question.
+Container image tags are mutable -- `myapp:latest` can point to a completely different image
+tomorrow. Only cryptographic signing tied to a verified identity provides assurance that the
+artifact was produced by the expected party.
+
+The 2024 xz-utils backdoor (CVE-2024-3094) further demonstrated how compromised maintainers can
+inject malicious code into signed releases. Transparency logs and identity-bound signing (rather
+than long-lived keys) help detect such attacks by making every signing event publicly auditable.
+
+## Instructions
+
+1. **Sign container images with cosign.** Run `cosign sign <image-digest>` to sign the image and
+   store the signature in the same OCI registry. Use keyless signing via Sigstore Fulcio to avoid
+   long-lived key management: cosign obtains a short-lived certificate (valid for 10 minutes)
+   from Fulcio using the OIDC identity of the CI system (GitHub Actions, GitLab CI, Google
+   Workload Identity), signs the artifact, and records the signature in Rekor (the transparency
+   log). No long-lived signing keys to manage, rotate, or protect from theft.
+
+2. **Verify signatures before deployment.** In Kubernetes, enforce signature verification at
+   admission time using a policy engine: Kyverno (ClusterPolicy with `verifyImages` rule),
+   Sigstore policy-controller, or Connaisseur. The policy specifies the expected signer identity
+   (OIDC issuer and subject) and rejects any image that is unsigned, signed by an unexpected
+   identity, or whose signature does not verify. A deployment pipeline that signs but does not
+   verify is performing security theater.
+
+3. **Sign git commits and tags.** Configure git to sign commits using GPG (`git commit -S`), SSH
+   keys (supported since Git 2.34), or Sigstore Gitsign (keyless, OIDC-based). Sign release tags
+   with `git tag -s`. Configure GitHub or GitLab to require signed commits on protected branches
+   and to display verification status. Signed commits provide non-repudiation: the committer
+   cannot deny making the commit, and reviewers can verify the author's identity.
+
+4. **Use Sigstore for keyless signing workflows.** The Sigstore ecosystem eliminates long-lived
+   key management: Fulcio issues short-lived certificates (10-minute validity) based on OIDC
+   identity. Cosign signs the artifact with the ephemeral key. Rekor records the signing event
+   in an immutable, publicly auditable transparency log. Verification checks four properties:
+   (1) the signature is cryptographically valid, (2) the certificate was issued by Fulcio,
+   (3) the signing event exists in Rekor, (4) the OIDC identity matches the expected publisher.
+
+5. **Implement a trusted publisher policy.** Define which identities are authorized to sign which
+   artifacts. Example: only the GitHub Actions workflow in the `org/repo` repository, triggered
+   by a push to the `main` branch, is authorized to sign the `registry.io/org/app` image.
+   Encode this policy in the verification layer (Kyverno policy, cosign verify flags, or
+   Sigstore policy-controller CRD). This prevents a compromised workflow in a different
+   repository from signing artifacts for your production images.
+
+6. **Sign all release artifacts, not just containers.** Binaries, npm packages, Python wheels,
+   Helm charts, Terraform modules -- every artifact you distribute should be signed. Provide
+   verification instructions and your signing identity (public key or Sigstore OIDC identity) in
+   your release documentation. npm supports Sigstore provenance natively via `--provenance` on
+   publish. PyPI supports Trusted Publisher via GitHub Actions OIDC. Both enable consumers to
+   verify that the published package was built from the expected repository.
+
+## Details
+
+- **Sigstore ecosystem components**: Cosign (the signing and verification CLI), Fulcio
+  (certificate authority that issues short-lived certificates based on OIDC identity), Rekor
+  (transparency log that records all signing events as immutable entries), Gitsign (git commit
+  signing via Sigstore). The keyless signing flow: CI authenticates via OIDC -> Fulcio issues a
+  10-minute certificate binding the OIDC identity to a signing key -> cosign signs the artifact
+  -> cosign stores the signature and certificate in the OCI registry -> cosign records the event
+  in Rekor -> any verifier can check signature + certificate + Rekor entry without needing the
+  signer's cooperation.
+
+- **GPG vs SSH vs Sigstore for git signing**: GPG is the traditional approach -- complex key
+  management, long-lived keys, web of trust model. SSH signing (Git 2.34+) is simpler -- uses
+  existing SSH keys, supported by GitHub and GitLab. Sigstore Gitsign is the newest option --
+  keyless, uses OIDC, records in Rekor, no long-lived keys to manage. Recommendation: Sigstore
+  Gitsign for teams that want zero key management overhead. SSH signing for teams already using
+  SSH keys. GPG for organizations with established PGP key infrastructure.
+
+- **Container image verification in Kubernetes**: A Kyverno ClusterPolicy specifies the expected
+  cosign signer identity (OIDC issuer URL and subject claim) for each image pattern. When a pod
+  is created, the admission webhook calls cosign verify against the image digest, checks the
+  Rekor transparency log, and rejects the pod if verification fails. This happens at admission
+  time -- the image never runs if it fails verification.
+
+- **Transparency logs and key compromise detection**: Without a transparency log, a stolen
+  signing key allows an attacker to silently sign malicious artifacts. With Rekor, every signing
+  event is recorded publicly. Monitoring the transparency log for unexpected signing events
+  (signatures from your identity that you did not produce) enables detection of key compromise
+  or identity impersonation. This is the same principle behind Certificate Transparency for TLS.
+
+- **npm and PyPI provenance**: npm v9.5+ supports `npm publish --provenance`, which generates a
+  Sigstore-signed SLSA provenance attestation linking the published package to the GitHub Actions
+  workflow that built it. PyPI Trusted Publisher links a GitHub repository to a PyPI project via
+  OIDC, eliminating long-lived API tokens and enabling consumers to verify the build source.
+
+## Anti-Patterns
+
+1. **Signing without verifying.** Many organizations implement signing as a compliance checkbox
+   but never configure their deployment pipeline to verify signatures. Signing without
+   verification provides zero security benefit -- the signatures exist but are never checked.
+   Always implement admission-time verification alongside signing.
+
+2. **Long-lived signing keys stored in CI secrets.** A static signing key stored as a CI/CD
+   secret is a high-value target. If the CI system is compromised, the attacker can sign
+   arbitrary artifacts with your identity. Use Sigstore keyless signing to eliminate long-lived
+   keys entirely, or store signing keys in a hardware security module (HSM) or cloud KMS with
+   strict access controls and audit logging.
+
+3. **Signing after the artifact is modified.** If the build pipeline modifies the artifact after
+   signing (re-tagging a Docker image, repackaging a binary, adding metadata), the signature
+   becomes invalid or, worse, does not cover the final artifact. Sign the final artifact as the
+   absolute last step of the build process. Reference artifacts by digest, not by tag.
+
+4. **No transparency log.** Without a transparency log (Rekor or equivalent), a signing key
+   compromise is undetectable after the fact. The attacker signs malicious artifacts, distributes
+   them, and no public record exists to detect the unauthorized signatures. Transparency logs
+   provide the same security property as Certificate Transparency: public auditability of all
+   signing events.
+
+5. **Trusting image tags instead of digests.** Tags are mutable pointers: `myapp:v1.2.3` can
+   point to completely different image content at different times. Signing a tag is meaningless
+   because the tag can be reassigned. Always sign and verify by digest (`@sha256:abc123...`).
+   Tags are human-readable labels; digests are cryptographic identifiers. Your deployment
+   manifests should reference digests, not tags.
+
+6. **Signing only production artifacts.** If staging and development artifacts are unsigned, an
+   attacker who compromises the pre-production pipeline can inject malicious code that is
+   eventually promoted to production. Sign artifacts at every stage of the pipeline and verify
+   at every promotion boundary.
+
+7. **No key rotation or revocation plan.** Organizations using traditional (non-keyless) signing
+   keys often have no documented process for rotating keys or revoking compromised keys. If a
+   signing key is compromised, every artifact signed with that key is suspect, and consumers
+   need a way to distinguish pre-compromise signatures from post-compromise ones. Maintain a
+   key rotation schedule, document the revocation process, and test it before you need it. This
+   is another reason Sigstore keyless signing is preferred -- ephemeral keys cannot be stolen
+   because they exist for only 10 minutes.

package/dist/agents/skills/codex/security-code-signing/skill.yaml

@@ -0,0 +1,40 @@
+name: security-code-signing
+version: '1.0.0'
+description: Artifact signing, verification pipelines, Sigstore keyless signing, and ensuring that deployed software was built by trusted parties
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - security-sbom-provenance
+  - security-hmac-signatures
+  - security-asymmetric-encryption
+  - security-dependency-auditing
+  - owasp-dependency-security
+stack_signals: []
+keywords:
+  - code signing
+  - artifact signing
+  - Sigstore
+  - cosign
+  - Fulcio
+  - Rekor
+  - GPG signing
+  - container signing
+  - software verification
+  - trusted publisher
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/security-compliance-logging/SKILL.md

@@ -0,0 +1,183 @@
+# Compliance Logging
+
+> Regulatory frameworks mandate specific logging requirements -- SOC2, GDPR, HIPAA, and
+> PCI-DSS each define what must be logged, how long logs are retained, and what constitutes
+> auditable evidence, and failing to meet these requirements carries fines, legal liability,
+> and loss of certification
+
+## When to Use
+
+- Designing or auditing logging infrastructure for an organization subject to SOC2, GDPR,
+  HIPAA, or PCI-DSS compliance requirements
+- Preparing for a compliance audit and verifying that logging meets the framework's controls
+- Determining log retention policies across different regulatory jurisdictions
+- Deciding what to log and what must be excluded to avoid creating new compliance violations
+- Building centralized log aggregation and ensuring tamper evidence for audit trails
+- Resolving the tension between comprehensive logging and data minimization requirements
+
+## Threat Context
+
+Compliance logging failures create two categories of organizational risk: regulatory
+penalties and undetectable breaches.
+
+- **Equifax (2017)**: The breach exposed 147 million records. Post-breach investigation
+  revealed that Equifax's logging was insufficient to determine the full scope of the
+  compromise. Inadequate audit trails extended the investigation timeline by months and
+  contributed to a $700 million settlement.
+- **British Airways (2018)**: GDPR fine of 20 million GBP. The ICO found that BA's logging
+  and monitoring systems failed to detect the Magecart skimming attack for over two months.
+  Adequate logging of payment page modifications would have triggered alerts within hours.
+- **Anthem (2015)**: The largest healthcare breach at the time (78.8 million records). HIPAA
+  audit controls require logging of all access to electronic protected health information
+  (ePHI). Anthem's insufficient access logging made it impossible to determine exactly which
+  records the attacker accessed, complicating notification obligations.
+- **GDPR data minimization paradox**: Article 5(1)(c) requires data minimization -- collect
+  only what is necessary. But Article 30 requires records of processing activities, and
+  Article 33 requires breach notification within 72 hours (which requires sufficient logging
+  to detect breaches). Organizations must log enough to detect breaches and prove compliance
+  while not logging so much that the logs themselves become a liability.
+
+## Instructions
+
+1. **Map your regulatory obligations to specific logging controls.** Each framework has
+   explicit logging requirements:
+   - **SOC2 (Trust Services Criteria)**: CC6.1 requires logical access controls with logging
+     of access events. CC7.2 requires monitoring of system components for anomalies. CC7.3
+     requires evaluation of security events. Logging must demonstrate that controls are
+     operating effectively over the audit period (typically 12 months).
+   - **GDPR**: Article 30 requires records of processing activities including purposes,
+     categories of data subjects, and recipients. Article 5(1)(f) requires integrity and
+     confidentiality of personal data, which demands access logging. Article 33 requires
+     72-hour breach notification, which is impossible without detection logging.
+   - **HIPAA (45 CFR 164.312(b))**: Audit controls must record and examine activity in
+     information systems that contain or use ePHI. This includes login attempts, data access,
+     data modification, and data export. The Security Rule requires both hardware and software
+     audit mechanisms.
+   - **PCI-DSS Requirement 10**: Track and monitor all access to network resources and
+     cardholder data. Requirement 10.2 specifies exact events: all individual user access to
+     cardholder data, all actions by anyone with root/admin privileges, access to audit trails,
+     invalid access attempts, identification and authentication events, initialization of audit
+     logs, creation/deletion of system-level objects.
+
+2. **Implement correct retention periods.** Retention is not optional -- both too short and
+   too long create violations:
+   - **SOC2**: Minimum 1 year retention. The audit period is typically 12 months, and auditors
+     require logs covering the entire period.
+   - **PCI-DSS**: Minimum 1 year retention with at least 3 months immediately available for
+     analysis. Older logs may be in archive storage but must be retrievable.
+   - **HIPAA**: 6 years for security documentation and audit logs. This is the longest common
+     retention requirement and often becomes the de facto minimum for healthcare organizations.
+   - **GDPR**: No fixed retention period -- logs must be retained only as long as necessary
+     for the stated purpose. A retention policy must document the purpose and the deletion
+     schedule. Retaining logs indefinitely without justification violates data minimization.
+
+3. **Define what to log and what to exclude.** The core auditable events are:
+   - **Always log**: Authentication events (login success, login failure, logout, MFA
+     challenge), authorization decisions (access granted, access denied, privilege escalation),
+     data access (who accessed what record, when, from where), data modification (create,
+     update, delete with before/after values where feasible), configuration changes (security
+     settings, user provisioning, role assignments), administrative actions (system startup,
+     shutdown, backup, restore).
+   - **Never log**: Passwords or password hashes, full credit card numbers (log last 4 digits
+     only per PCI-DSS), Social Security numbers, health records content (log access to the
+     record, not the record itself), session tokens or API keys, biometric data.
+   - **Mask in logs**: Email addresses (log `j***@example.com`), IP addresses in GDPR
+     jurisdictions (IP is personal data -- log truncated or hashed IPs for analytics, full IPs
+     only for security investigation with documented legal basis), names (log user IDs, not
+     full names, unless the audit requires name resolution).
+
+4. **Ensure tamper evidence for audit trails.** Auditors must trust that logs have not been
+   modified after the fact:
+   - Use append-only storage (WORM -- Write Once Read Many) for compliance-critical logs.
+     AWS S3 Object Lock, Azure Immutable Blob Storage, and GCP Bucket Lock provide cloud-
+     native WORM storage.
+   - Implement log integrity verification using hash chains or Merkle trees. Each log entry
+     includes a hash of the previous entry, creating a tamper-evident chain.
+   - Centralize log collection immediately. Logs that remain on application servers can be
+     modified by an attacker who compromises the server. Ship logs to a centralized system
+     (SIEM, log aggregator) within seconds of generation.
+   - Restrict access to the logging infrastructure. The application should be able to write
+     logs but not read, modify, or delete them. Separate the logging system's access controls
+     from the application's access controls.
+
+5. **Maintain audit readiness at all times.** Compliance is not a point-in-time activity:
+   - Run monthly log completeness checks: are all required event types being captured? Are
+     there gaps in the timeline? Are all services and systems sending logs?
+   - Conduct quarterly mock audits: pull a sample of logs and verify they contain the
+     required fields, are properly retained, and can be searched and correlated.
+   - Package evidence proactively: maintain a running evidence collection that maps each
+     compliance control to the specific log queries, dashboards, or reports that demonstrate
+     the control is operating. When the auditor arrives, the evidence is ready.
+   - Document the logging architecture: auditors need to understand how logs flow from source
+     to storage, what transformations occur, what the retention policy is, and who has access.
+
+## Details
+
+- **SOC2 Type II vs Type I and the logging implications**: Type I audits assess control
+  design at a point in time -- the auditor verifies that logging controls exist. Type II
+  audits assess control effectiveness over a period (typically 12 months) -- the auditor
+  verifies that logging controls operated continuously and correctly throughout the period.
+  A single month with missing logs or disabled monitoring can result in a qualified opinion
+  or exception in the SOC2 Type II report. This means logging infrastructure must be treated
+  with the same availability requirements as production systems.
+
+- **GDPR's legitimate interest basis for security logging**: Under GDPR, processing personal
+  data requires a legal basis. For security logging, the most common basis is Article 6(1)(f)
+  -- legitimate interest. The organization has a legitimate interest in detecting and
+  preventing security incidents. A Legitimate Interest Assessment (LIA) documents that the
+  logging is necessary, proportionate, and that the individual's rights do not override the
+  interest. This assessment should be documented and reviewed annually. Without it, logging
+  personal data (even IP addresses) lacks a legal basis.
+
+- **PCI-DSS Requirement 10 in depth**: Requirement 10.2 mandates logging specific events.
+  Requirement 10.3 mandates specific fields in each log entry: user identification, type of
+  event, date and time, success or failure, origination of event, identity or name of affected
+  data/system/resource. Requirement 10.4 mandates time synchronization using NTP -- all
+  systems must agree on the time so that log correlation across systems is accurate.
+  Requirement 10.5 mandates securing audit trails so they cannot be altered. Requirement 10.7
+  mandates retaining audit trail history for at least 12 months.
+
+- **Log format standardization across services**: Use a consistent structured format (JSON
+  with a defined schema) across all services. Every log entry should include: timestamp
+  (ISO 8601, UTC), event type (from a controlled vocabulary), actor (user ID, service
+  account, or system), action (verb from a controlled vocabulary), resource (what was acted
+  upon), outcome (success/failure), source IP, request ID (for correlation), and session ID.
+  Inconsistent formats across services make audit evidence unreliable because the auditor
+  cannot compare events across systems.
+
+## Anti-Patterns
+
+1. **Logging PII or PHI without masking.** An organization implements comprehensive logging
+   to demonstrate HIPAA compliance but includes patient names and diagnosis codes in access
+   logs. The logs themselves now contain ePHI, requiring the same protections as the clinical
+   database. The logging system has created a second copy of sensitive data, expanding the
+   attack surface and the compliance scope. Log the access event (who, when, which record ID)
+   but not the record content.
+
+2. **Retaining logs indefinitely without a documented policy.** An organization stores all
+   logs forever because "storage is cheap" and "we might need them." Under GDPR, this violates
+   Article 5(1)(e) storage limitation -- personal data must not be kept longer than necessary.
+   The organization now has years of IP addresses, user activity patterns, and behavioral data
+   with no legal basis for retention. Define retention periods per regulatory requirement,
+   implement automated deletion, and document the policy.
+
+3. **No centralized log collection.** Logs remain on individual application servers, database
+   servers, and network devices. When an auditor requests evidence, the team must manually
+   collect logs from dozens of systems, hoping nothing was lost to log rotation or disk
+   failures. When an attacker compromises a server, they delete the local logs to cover their
+   tracks. Ship all logs to a centralized, access-restricted system within seconds.
+
+4. **Different logging standards across services.** One service logs authentication events
+   with user ID and timestamp. Another logs with username and local time. A third does not
+   log authentication events at all. The auditor cannot construct a consistent picture of
+   access patterns across the organization. Define a logging standard with required fields
+   and event types, enforce it through shared libraries or middleware, and validate compliance
+   in CI.
+
+5. **Treating compliance logging as a separate system from security logging.** Building a
+   dedicated "compliance log" pipeline that captures a subset of events for auditors, while
+   the security team uses a different logging pipeline for detection and response. The
+   compliance logs miss events the security team catches, and the security logs miss events
+   the auditors need. Use a single logging infrastructure that serves both purposes. Apply
+   different retention policies and access controls to the same data rather than maintaining
+   parallel systems.

package/dist/agents/skills/codex/security-compliance-logging/skill.yaml

@@ -0,0 +1,38 @@
+name: security-compliance-logging
+version: '1.0.0'
+description: SOC2, GDPR, HIPAA, and PCI-DSS logging requirements -- what to log, how long to retain it, and how to prove compliance through audit trails
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - security-audit-log-design
+  - security-log-correlation
+  - owasp-logging-monitoring
+stack_signals: []
+keywords:
+  - compliance logging
+  - SOC2
+  - GDPR
+  - HIPAA
+  - PCI-DSS
+  - audit trail
+  - data retention
+  - log retention
+  - regulatory compliance
+  - audit evidence
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/security-credential-storage/SKILL.md

@@ -0,0 +1,222 @@
+# Credential Storage
+
+> Argon2id for new systems, bcrypt for broad compatibility -- always salt, consider peppering, tune cost parameters to hardware, and plan hash upgrade paths
+
+## When to Use
+
+- Designing a user registration and login system that stores passwords
+- Reviewing existing password storage for security adequacy
+- Migrating from an insecure hashing scheme (MD5, SHA-1, unsalted SHA-256) to a secure one
+- Choosing between Argon2id, bcrypt, and scrypt for a new project
+- Tuning password hashing cost parameters for production hardware
+- Implementing a "hash upgrade on login" strategy for legacy systems
+
+## Threat Context
+
+When a database is breached (and breaches are a matter of when, not if), the attacker obtains the stored password representations.
+If passwords are stored in plaintext, all accounts are immediately compromised.
+If stored as fast hashes (MD5, SHA-256), offline brute-force attacks using GPUs can crack the majority of passwords in hours.
+
+The 2012 LinkedIn breach exposed 6.5 million SHA-1 unsalted hashes that were cracked within days.
+The 2016 follow-up revealed the full dataset was 117 million credentials.
+The 2013 Adobe breach exposed 153 million passwords encrypted (not hashed) with 3DES in ECB mode -- the block cipher preserved password frequency patterns, allowing mass decryption without the key.
+
+Purpose-built password hashing functions defend by making each guess computationally expensive.
+They are deliberately slow, memory-intensive, and resistant to parallelization on GPUs and ASICs.
+A hash that takes 250ms on a server CPU transforms a hours-long brute-force attack into one requiring centuries.
+
+## Instructions
+
+1. **Default to Argon2id.**
+   Argon2id won the 2015 Password Hashing Competition and is the OWASP-recommended algorithm.
+   It is memory-hard and resistant to both GPU and ASIC attacks.
+   Argon2id has three tunable parameters:
+   - Memory cost: minimum 64 MB recommended by OWASP
+   - Time cost: iterations, minimum 3
+   - Parallelism: threads, typically 1-4
+
+   Argon2id combines Argon2i (data-independent memory access, resistant to side-channel attacks) and Argon2d (data-dependent memory access, maximally resistant to GPU/ASIC attacks) in a hybrid mode.
+   The first pass uses Argon2i for side-channel resistance; subsequent passes use Argon2d for GPU resistance.
+
+2. **Use bcrypt when Argon2id is unavailable.**
+   bcrypt has been battle-tested since 1999 and is available in virtually every language and framework.
+   It uses the Blowfish cipher in a key setup phase that is intentionally expensive.
+   The cost factor is exponential (cost 12 = 2^12 = 4096 iterations).
+   Set the work factor so that hashing takes 250-500ms on your production hardware.
+
+   bcrypt has a critical 72-byte input limit -- passwords longer than 72 bytes are silently truncated.
+   For systems supporting long passphrases or high-entropy Unicode passwords, pre-hash with SHA-256:
+   `bcrypt(base64(SHA-256(password)))`.
+   This is safe because SHA-256 is preimage resistant and the pre-hash does not weaken the password.
+
+3. **Always use a unique salt per credential.**
+   A salt is a cryptographically random value (minimum 16 bytes) stored alongside the hash.
+   Salting ensures that identical passwords produce different hashes, which defeats two attack classes:
+   - Precomputed rainbow tables (which map hash outputs to inputs)
+   - Multi-target attacks (where the attacker cracks all instances of a common password simultaneously)
+
+   Argon2id and bcrypt generate and embed salts automatically in their output format.
+   Do not manage salts manually unless the algorithm requires it.
+
+4. **Consider peppering for defense in depth.**
+   A pepper is a secret value (minimum 32 bytes) applied to the password before hashing: `hash(pepper + password, salt)`.
+   Unlike the salt (stored with the hash in the database), the pepper is stored separately -- in an HSM, a secrets manager, or an environment variable that is not in the database.
+   If the database is breached but the pepper is not, the hashes are uncrackable even with infinite compute.
+
+   The tradeoff: pepper rotation requires re-hashing all credentials, which can only happen on login (when the plaintext password is available).
+   Implement pepper versioning: store the pepper version with each hash and support multiple active peppers during rotation.
+
+5. **Tune cost parameters to target 250-500ms per hash.**
+   Benchmark on production hardware, not development laptops.
+   Too fast means vulnerable to brute force -- if your hash completes in 1ms, the attacker can try 1000 passwords per second per core.
+   Too slow means degraded login UX and potential for login-based denial of service (an attacker sending thousands of login requests to consume server CPU).
+
+   For Argon2id: start with 64 MB memory, 3 iterations, 1 parallelism, and increase memory until you hit the target latency.
+   For bcrypt: start at cost 10 and increment by 1 until you reach the target.
+   Document the benchmarking methodology and re-run annually.
+
+6. **Implement hash upgrade on login.**
+   When a user authenticates successfully (proving they know the plaintext password), inspect the stored hash format.
+   If it uses a legacy algorithm or outdated parameters (e.g., bcrypt cost 10 when the current standard is cost 12, or MD5 from a legacy system), re-hash the password with the current algorithm and parameters, then update the stored hash.
+
+   This enables transparent migration across algorithm generations -- MD5 to bcrypt to Argon2id -- without forcing password resets on the entire user base.
+   Store the algorithm identifier and parameter version in a parseable format alongside each hash.
+
+7. **Never implement password hashing yourself.**
+   Use the language's standard library or a well-maintained, audited security library.
+   Custom password hashing implementations invariably contain:
+   - Timing side channels (comparing hashes byte-by-byte allows attackers to determine correctness incrementally)
+   - Incorrect salt generation (using Math.random() instead of a CSPRNG)
+   - Parameter misconfiguration or encoding errors
+
+   Constant-time comparison functions are mandatory for hash verification.
+
+## Details
+
+### Why General-Purpose Hashes Fail
+
+SHA-256 computes at approximately 6 billion hashes per second on a modern GPU (NVIDIA RTX 4090).
+At that rate, the entire space of 6-character alphanumeric passwords (2.2 billion combinations) is exhausted in under 1 second.
+The 8-character alphanumeric space (218 trillion combinations) falls in approximately 10 hours.
+
+bcrypt at cost 12 computes at roughly 50 hashes per second on the same GPU -- the same 8-character space would require approximately 138,000 years.
+Argon2id with 64 MB memory cost is even slower on GPUs because each hash attempt must allocate 64 MB of GPU memory, severely limiting parallelism.
+
+### Argon2 Variants
+
+- **Argon2d**: Data-dependent memory access pattern.
+  Maximum resistance to GPU and ASIC attacks because the memory access pattern depends on the password, making it impossible to precompute memory layouts.
+  Vulnerable to side-channel attacks (timing analysis of memory access patterns can leak information about the password).
+  Suitable for cryptocurrency mining and backend-only applications.
+
+- **Argon2i**: Data-independent memory access pattern.
+  Resistant to side-channel attacks because the memory access pattern is determined solely by the parameters (salt, time cost, memory cost), not the password.
+  Less resistant to GPU attacks than Argon2d.
+  Suitable for environments where side-channel attacks are a concern (shared hosting, client-side hashing).
+
+- **Argon2id**: Hybrid mode.
+  The first pass uses Argon2i (side-channel resistance during the initial memory fill), subsequent passes use Argon2d (GPU resistance for the majority of computation).
+  This is the recommended variant for password hashing in all contexts.
+
+### The bcrypt 72-Byte Limit
+
+bcrypt internally truncates input to 72 bytes before processing.
+For ASCII passwords, this allows 72 characters -- more than sufficient for typical passwords but problematic for systems accepting long passphrases or Unicode passwords (where a single character may be 4 bytes in UTF-8).
+
+The standard mitigation is pre-hashing: `bcrypt(base64(SHA-256(password)))`.
+The base64 encoding of a SHA-256 output is 44 bytes, well within the 72-byte limit.
+This is safe because SHA-256 is a preimage-resistant one-way function -- the pre-hash concentrates entropy without losing it.
+
+### Credential Stuffing vs. Brute Force
+
+Password hashing defends against offline brute force (attacker has the hash and tries passwords locally).
+It does not defend against credential stuffing (attacker tries leaked username/password pairs from other breaches against your login endpoint).
+
+Defense against credential stuffing requires:
+
+- Rate limiting on login endpoints
+- Progressive account lockout with exponential backoff
+- CAPTCHA challenges after repeated failures
+- Monitoring for bulk login failures from distributed sources
+- Multi-factor authentication (the single most effective defense)
+
+Password hashing protects the stored credentials; MFA protects the authentication flow.
+
+### scrypt as a Third Option
+
+scrypt (Percival, 2009) is memory-hard like Argon2id but predates the Password Hashing Competition.
+It has two tunable parameters: N (CPU/memory cost factor, must be a power of 2) and r (block size, controls memory usage per iteration).
+scrypt is used in several cryptocurrency protocols (Litecoin, Dogecoin) and is available in most cryptographic libraries.
+
+Prefer Argon2id over scrypt for new systems because:
+
+- Argon2id provides independent tuning of memory, time, and parallelism (scrypt couples memory and CPU cost)
+- Argon2id was designed specifically for password hashing with formal security analysis
+- Argon2id has broader review from the Password Hashing Competition judging process
+
+scrypt remains acceptable when Argon2id is unavailable and bcrypt's lack of memory-hardness is a concern.
+
+### Hash Format and Storage
+
+Store the complete hash output including the algorithm identifier, parameters, salt, and hash value in a single self-describing string.
+Argon2id and bcrypt both produce such strings natively:
+
+- **Argon2id**: `$argon2id$v=19$m=65536,t=3,p=1$<salt>$<hash>`
+- **bcrypt**: `$2b$12$<salt+hash>`
+- **scrypt**: `$scrypt$ln=15,r=8,p=1$<salt>$<hash>`
+
+This format enables hash-upgrade-on-login by allowing the application to detect the algorithm and parameters of the stored hash without external metadata.
+
+### Language-Specific Libraries
+
+- **Node.js**: `argon2` package (wraps the reference C implementation); `bcrypt` or `bcryptjs` for bcrypt
+- **Python**: `argon2-cffi` (recommended by the Argon2 authors); `bcrypt` package from PyCA
+- **Java**: Spring Security's `Argon2PasswordEncoder`; `jBCrypt` for bcrypt
+- **Go**: `golang.org/x/crypto/argon2`; `golang.org/x/crypto/bcrypt`
+- **Ruby**: `argon2` gem; `bcrypt-ruby` gem (used by Devise)
+- **PHP**: `password_hash()` with `PASSWORD_ARGON2ID` (built-in since PHP 7.3); `PASSWORD_BCRYPT` for bcrypt
+
+## Anti-Patterns
+
+1. **Plaintext password storage.**
+   Any breach exposes all credentials instantly.
+   There is no legitimate use case.
+   No exceptions, no excuses.
+   This is negligence, not a design choice.
+
+2. **Unsalted hashing (MD5(password), SHA-256(password)).**
+   Rainbow tables provide instant lookup for common passwords.
+   Even uncommon passwords fall to GPU-accelerated brute force within hours.
+   Every leaked database with unsalted hashes is fully cracked within days of publication.
+
+3. **Global salt (same salt for all users).**
+   Defeats the purpose of salting entirely.
+   Attackers incorporate the single salt into their GPU kernel and attack all hashes simultaneously, achieving the same throughput as unsalted hashing.
+   Each credential must have a unique random salt of at least 16 bytes.
+
+4. **Static cost parameters that are never re-tuned.**
+   bcrypt cost 10 was appropriate in 2010.
+   GPU performance improves roughly 2x every 18 months.
+   A cost parameter that provided 250ms latency in 2010 provides under 10ms today.
+   Re-tune cost parameters annually against production hardware benchmarks.
+   Use hash-upgrade-on-login to apply increased costs transparently.
+
+5. **Encrypting passwords instead of hashing them.**
+   Encryption is a reversible operation -- whoever holds the key can recover all passwords in constant time.
+   If the encryption key is compromised alongside the database (common in breaches that achieve code or config access), all passwords are exposed instantly.
+   Passwords must be hashed (one-way function), never encrypted (two-way function).
+   The only exception is peppering, where the pepper acts as an additional secret input to the hash function, not as an encryption key.
+
+6. **Rolling your own password hashing function.**
+   Combining SHA-256 iterations with custom salt handling, custom encoding, and manual timing protection.
+   Every component of this stack has subtle requirements that security libraries handle correctly and custom implementations do not.
+   Use Argon2id from a vetted library.
+
+7. **Comparing hashes with standard string equality.**
+   Standard `==` comparison short-circuits on the first differing byte, creating a timing side channel that allows attackers to determine hash correctness incrementally.
+   Always use constant-time comparison functions:
+
+- Node.js: `crypto.timingSafeEqual`
+- Python: `hmac.compare_digest`
+- Java: `MessageDigest.isEqual`
+- Go: `crypto/subtle.ConstantTimeCompare`