@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/cursor/security-hashing-fundamentals/SKILL.md

@@ -0,0 +1,212 @@
+# Hashing Fundamentals
+
+> One-way functions for integrity verification, content addressing, and commitment schemes
+> -- SHA-256 for interoperability, BLAKE3 for performance, and never MD5 or SHA-1 for
+> security
+
+## When to Use
+
+- Verifying file or data integrity (checksums, download verification, package signing)
+- Content addressing (deduplication, cache keys, Git object IDs, container image digests)
+- Generating deterministic identifiers from variable-length input
+- Choosing a hash function for a new system or migrating away from a deprecated one
+- Reviewing code that uses hashing and assessing whether the right function and use
+  pattern is applied
+- Understanding why MD5 or SHA-1 must be replaced in security-sensitive contexts
+
+## Threat Context
+
+Weak hash functions enable collision attacks (finding two different inputs that produce
+the same hash), preimage attacks (finding an input that produces a specific target hash),
+and second preimage attacks (finding a different input with the same hash as a known
+input). MD5 collisions can be generated in seconds on commodity hardware -- Wang et al.
+demonstrated the first practical MD5 collision in 2004, and by 2012, the Flame malware
+exploited an MD5 chosen-prefix collision to forge a Microsoft code-signing certificate,
+enabling nation-state malware to masquerade as a legitimate Windows update. SHA-1
+collisions were demonstrated practically by Google and CWI Amsterdam in 2017 (the
+SHAttered attack), producing two distinct PDF files with identical SHA-1 hashes at a cost
+of approximately $110,000 in cloud computing. These attacks enable forged digital
+certificates, tampered software distribution packages, Git repository poisoning, and
+bypassed integrity checks in any system relying on the compromised hash function.
+
+## Instructions
+
+1. **For general-purpose cryptographic hashing, use SHA-256.** SHA-256 (part of the SHA-2
+   family, designed by the NSA, standardized by NIST in 2001) produces a 256-bit digest
+   and provides 128-bit collision resistance and 256-bit preimage resistance. It is
+   universally supported across every programming language, operating system, and
+   cryptographic library. SHA-256 is the standard choice for integrity verification,
+   digital signature hashing, certificate fingerprints, blockchain proof-of-work, and any
+   context requiring a well-analyzed, interoperable cryptographic hash. SHA-512 offers the
+   same security margin with better performance on 64-bit platforms due to its use of
+   64-bit arithmetic operations.
+
+2. **For performance-sensitive hashing, use BLAKE3.** BLAKE3 is a cryptographic hash
+   function released in 2020, derived from the BLAKE2/ChaCha cipher family. It is 6-14x
+   faster than SHA-256 on modern CPUs by exploiting SIMD parallelism (AVX-512, NEON) and
+   internal tree hashing that parallelizes across multiple cores. BLAKE3 provides 128-bit
+   security against all known attacks. Use BLAKE3 for content addressing, file
+   deduplication, Merkle tree construction, and any use case where hash throughput is a
+   bottleneck. BLAKE3 is not yet NIST-standardized, so use SHA-256 when FIPS 140-2/140-3
+   compliance is required. BLAKE2b (BLAKE3's predecessor) is standardized in RFC 7693 and
+   is a suitable intermediate choice.
+
+3. **For defense-in-depth against structural attacks, consider SHA-3 (Keccak).** SHA-3
+   uses the sponge construction, which is fundamentally different from the Merkle-Damgard
+   construction used by SHA-2, MD5, and SHA-1. If a structural breakthrough ever
+   compromises the Merkle-Damgard design (affecting the entire SHA-2 family
+   simultaneously), SHA-3 would be unaffected. SHA-3-256 provides 128-bit collision
+   resistance, identical to SHA-256. In practice, SHA-256 is not under credible threat,
+   but defense-critical or long-lived systems (government archives, root certificate
+   authorities) may use SHA-3-256 as a hedge. SHA-3 also natively supports
+   variable-length output via SHAKE128 and SHAKE256 (extendable output functions), which
+   is useful for key derivation and domain separation.
+
+4. **Never use MD5 or SHA-1 for security purposes.** MD5 is completely broken for
+   collision resistance -- chosen-prefix collisions (where the attacker controls prefixes
+   of both inputs) can be computed in hours on a single machine. SHA-1 is similarly
+   broken: the SHAttered attack demonstrated a practical collision, and further research
+   (Leurent and Peyrin, 2020) reduced chosen-prefix collision cost to approximately
+   $45,000. Both MD5 and SHA-1 are acceptable only for non-security checksums where
+   adversarial tampering is not in the threat model (e.g., verifying data integrity over a
+   reliable channel, deduplication in trusted storage). When encountering MD5 or SHA-1 in
+   existing code, assess whether the context is security-sensitive; if so, migration to
+   SHA-256 is urgent.
+
+5. **Understand the three security properties of cryptographic hash functions:**
+   - **Preimage resistance (one-wayness):** Given a hash output H, it is computationally
+     infeasible to find any input m such that hash(m) = H. A hash function with n-bit
+     output provides up to n-bit preimage resistance. This property ensures that hashes
+     cannot be "reversed" to recover the original input.
+   - **Second preimage resistance:** Given a specific input m1, it is computationally
+     infeasible to find a different input m2 such that hash(m1) = hash(m2). This property
+     ensures that an attacker cannot find a substitute input that matches a known hash,
+     which would enable undetected document or data substitution.
+   - **Collision resistance:** It is computationally infeasible to find any two distinct
+     inputs m1 and m2 such that hash(m1) = hash(m2). Due to the birthday paradox,
+     collision resistance is at most n/2 bits for an n-bit hash (2^128 operations for
+     SHA-256). Collision resistance is the strongest property and implies second preimage
+     resistance.
+
+6. **Hashing is NOT encryption.** Hashing is a one-way function: given input m, you can
+   compute hash(m), but given hash(m), you cannot recover m. Encryption is a two-way
+   function: given plaintext and a key, you can encrypt; given ciphertext and the key, you
+   can decrypt. Never hash data you need to recover (use encryption). Never encrypt data
+   you only need to verify (use hashing). This distinction is fundamental: hashing
+   provides integrity and commitment; encryption provides confidentiality.
+
+7. **Hashing is NOT a MAC.** A bare hash -- SHA-256(message) -- does not authenticate
+   the sender. Anyone who knows the message can compute its hash. A Message
+   Authentication Code (MAC) combines the hash with a secret key, so only parties
+   possessing the key can compute or verify the MAC. Use HMAC (HMAC-SHA256, HMAC-SHA384)
+   when you need to verify both integrity and authenticity. Naive constructions like
+   hash(key || message) are vulnerable to length extension attacks on Merkle-Damgard
+   hashes. See the `security-hmac-signatures` skill.
+
+## Details
+
+### Length Extension Attacks
+
+SHA-256, SHA-512, and all Merkle-Damgard hash functions are vulnerable to length
+extension: given hash(m) and the length of m (but not m itself), an attacker can compute
+hash(m || padding || attacker_suffix) for any chosen suffix, without knowing m. This is
+possible because the final internal state of a Merkle-Damgard hash is the hash output,
+and that state can be used to initialize a new hash computation that "continues" from
+where the original left off.
+
+This breaks naive keyed-hash authentication schemes like hash(secret || message): an
+attacker who observes the hash and knows the message length can append arbitrary data and
+compute a valid hash. Real-world exploits include API signature bypasses where servers
+used hash(api_key || request_params) for authentication.
+
+Mitigations:
+
+- **HMAC** nests the hash in a specific construction -- hash(K XOR opad || hash(K XOR
+  ipad || message)) -- that is provably secure against length extension.
+- **SHA-3 (Keccak)** uses the sponge construction, which absorbs input and squeezes
+  output through a capacity parameter. The internal state is larger than the output,
+  making length extension infeasible.
+- **BLAKE3** uses a tree/chaining construction that is also immune to length extension.
+
+### Birthday Paradox and Collision Probability
+
+The birthday paradox states that in a set of n randomly chosen values from a space of
+size N, the probability of at least one collision exceeds 50% when n approaches sqrt(N).
+For hash functions:
+
+- **SHA-256** (256-bit output): collision expected after ~2^128 hashes --
+  computationally infeasible with current or foreseeable technology.
+- **SHA-1** (160-bit output): collision expected after ~2^80 hashes -- within reach of
+  well-funded attackers, as SHAttered demonstrated.
+- **MD5** (128-bit output): collision expected after ~2^64 hashes -- trivially achievable
+  on modern hardware.
+
+This is why hash output length matters for security: a 128-bit hash provides only 64-bit
+collision resistance, which is insufficient for any security application.
+
+### Content Addressing Pattern
+
+Content addressing uses the hash of data as its identifier/address, making integrity
+self-verifying:
+
+- **Git** uses SHA-1 for object IDs (commits, trees, blobs), migrating to SHA-256 to
+  address collision concerns.
+- **IPFS** uses multihash (a self-describing format: hash function identifier + digest
+  length + digest), allowing algorithm agility.
+- **Docker/OCI** uses SHA-256 for layer digests and image manifests.
+- **Content Delivery Networks** use content hashes for cache keys, enabling global
+  deduplication.
+
+The pattern: `store(hash(content), content)` and `retrieve(hash) -> content`. On
+retrieval, recompute the hash and verify it matches the address. If the content has been
+tampered with, the hash will not match and the tampering is detected. This provides
+integrity without requiring a separate signature or MAC, as long as the hash-to-content
+binding was established through a trusted channel.
+
+### Hash Function Selection Decision Tree
+
+- Need FIPS 140-2/140-3 compliance? Use **SHA-256** or **SHA-3-256**.
+- Need maximum throughput and no FIPS requirement? Use **BLAKE3**.
+- Need defense-in-depth against Merkle-Damgard structural attacks? Use **SHA-3-256**.
+- Non-security checksum (error detection, not adversarial)? Use **CRC32** or **xxHash**
+  (not cryptographic, but extremely fast).
+- Password storage? **Not a general-purpose hash** -- use Argon2id, bcrypt, or scrypt
+  (see `security-credential-storage`).
+- HMAC / keyed authentication? Use **HMAC-SHA256** (see `security-hmac-signatures`).
+
+## Anti-Patterns
+
+1. **MD5 for integrity in adversarial contexts.** MD5 chosen-prefix collisions enable an
+   attacker to create two files with identical hashes but different content. The Flame
+   malware (2012) used an MD5 collision to forge a Microsoft code-signing certificate,
+   allowing malware to be distributed through Windows Update. MD5 is acceptable only for
+   non-security checksums where no adversary is in the threat model.
+
+2. **SHA-256(password) for credential storage.** General-purpose hash functions are
+   designed to be fast -- a modern GPU can compute billions of SHA-256 hashes per second.
+   This speed advantage benefits attackers performing brute-force or dictionary attacks
+   against password hashes. Purpose-built password hashing functions (Argon2id, bcrypt,
+   scrypt) are deliberately slow, memory-hard, and parameterizable to maintain resistance
+   as hardware improves. See `security-credential-storage`.
+
+3. **hash(secret || message) for authentication.** Vulnerable to length extension attacks
+   on all Merkle-Damgard hashes (SHA-256, SHA-512, MD5, SHA-1). An attacker who observes
+   the hash output and knows the message can append arbitrary data and compute a valid
+   hash without knowing the secret. Use HMAC(key, message) instead. HMAC is provably
+   secure under standard assumptions and is immune to length extension regardless of the
+   underlying hash function.
+
+4. **Truncating hashes without understanding the security impact.** Truncating SHA-256
+   output from 256 bits to 128 bits reduces collision resistance from 2^128 to 2^64 -- a
+   reduction of 2^64 in the attacker's required work. If space constraints require shorter
+   hashes, explicitly analyze whether the reduced collision resistance is acceptable for
+   the specific threat model and document the decision. For content addressing where
+   collision probability (not adversarial collision) is the concern, truncation may be
+   acceptable with sufficient analysis.
+
+5. **Assuming hash uniqueness as an invariant.** Hash functions map an infinite input
+   space to a finite output space -- collisions exist by the pigeonhole principle. Systems
+   that assume hash uniqueness without verification will fail silently when collisions
+   occur (whether natural or adversarial). Content-addressed storage must verify that
+   retrieved content matches the expected content, not just the hash. Database schemas
+   using hash columns as unique keys must handle collision cases.

package/dist/agents/skills/cursor/security-hashing-fundamentals/skill.yaml

@@ -0,0 +1,40 @@
+name: security-hashing-fundamentals
+version: "1.0.0"
+description: Cryptographic hash functions (SHA-256, SHA-3, BLAKE3), collision resistance, preimage resistance, and correct use cases for hashing vs encryption vs MAC
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - security-hmac-signatures
+  - security-credential-storage
+  - security-symmetric-encryption
+  - security-cryptographic-randomness
+  - owasp-cryptography
+stack_signals: []
+keywords:
+  - hash function
+  - SHA-256
+  - SHA-3
+  - BLAKE3
+  - collision resistance
+  - preimage attack
+  - content addressing
+  - integrity verification
+  - MD5
+  - SHA-1
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/security-hmac-signatures/SKILL.md

@@ -0,0 +1,165 @@
+# HMAC and Digital Signatures
+
+> HMAC proves a message was created by someone with the shared secret; digital signatures prove it was created by a specific private key holder -- choose based on whether you need symmetric verification or non-repudiation
+
+## When to Use
+
+- Verifying webhook payloads from third-party services (Stripe, GitHub, Slack)
+- Signing JWTs and choosing between HS256 and RS256/ES256
+- Authenticating API requests between internal services
+- Signing software artifacts, commits, or release packages
+- Designing a system that requires non-repudiation (proving who did what)
+- Implementing message integrity checks on data in transit or at rest
+
+## Threat Context
+
+Message authentication failures enable man-in-the-middle tampering, webhook forgery, and API request replay. The 2022 Heroku/GitHub OAuth token theft exploited stolen HMAC secrets to forge session tokens. Weak HMAC implementations using plain SHA-256 instead of HMAC-SHA-256 are vulnerable to length extension attacks.
+
+JWT libraries that accept `alg: none` or allow algorithm confusion (treating an RSA public key as an HMAC secret) have caused authentication bypasses in Auth0 (2015), Okta, and countless custom implementations. The PlayStation 3 code signing was broken in 2010 because Sony reused the same ECDSA nonce for every signature -- a single nonce reuse leaks the private key entirely. The 2014 OpenSSL Heartbleed bug exposed private signing keys from server memory, enabling signature forgery for any service using the compromised keys.
+
+## Instructions
+
+1. **Understand the core distinction.** HMAC uses a shared symmetric key -- both the signer and verifier possess the same secret. Digital signatures use an asymmetric key pair -- only the private key holder can sign, but anyone with the public key can verify. HMAC provides authentication (who sent this?) and integrity (was it modified?). Digital signatures additionally provide non-repudiation (the signer cannot deny signing). Choose HMAC for internal service communication where both parties are trusted. Choose digital signatures when the verifier should not be able to forge signatures.
+
+2. **Use HMAC for symmetric trust relationships.** When both parties share a secret (webhook provider and your server, two internal microservices), HMAC-SHA-256 is the standard choice. Compute: `HMAC(key, message)` and compare using constant-time comparison. Never use string equality (`==`) -- timing side channels leak information about the correct MAC byte by byte, allowing an attacker to reconstruct the correct value over thousands of requests by measuring response time differences.
+
+3. **Use digital signatures when the verifier should not be able to sign.** When the signer and verifier are different trust domains (package signing where users verify, JWT issuance where resource servers verify, code signing), use asymmetric signatures. Recommended algorithms in priority order:
+   - **Ed25519:** Fast, small signatures (64 bytes), no configuration pitfalls, deterministic nonce (eliminates nonce-reuse attacks). Preferred for all new systems.
+   - **ECDSA with P-256:** Widely supported, NIST approved, but requires cryptographically secure random nonce generation -- nonce reuse leaks the private key.
+   - **RSA-PSS with 2048+ bit keys:** Legacy compatibility, larger signatures (256 bytes for RSA-2048). Use PSS padding, not PKCS#1 v1.5 (vulnerable to Bleichenbacher's padding oracle attack).
+
+4. **Prevent algorithm confusion.** In JWT systems, always validate the `alg` header server-side against an allowlist. Never let the token specify which algorithm to use. The classic JWT vulnerability: the server expects RS256 (asymmetric) but the attacker sends a token with `alg: HS256` and uses the RSA public key (which is public knowledge) as the HMAC secret. The server's JWT library treats the public key as an HMAC key and validates the forged token successfully.
+
+5. **Include anti-replay mechanisms.** HMAC and signatures prove integrity and origin but not freshness. Add a timestamp or nonce to the signed payload and reject messages older than a threshold (e.g., 5 minutes). For critical operations, store seen nonces in a cache and reject duplicates within the validity window. Without anti-replay protection, a captured valid request can be replayed indefinitely.
+
+6. **Rotate keys on a schedule.** HMAC secrets and signing keys must have rotation schedules. Support multiple active keys during rotation: verify against both old and new keys for a transition period, sign only with the new key. For digital signature keys, publish rotation via JWKS endpoints with key IDs (`kid`). Automate rotation -- manual key rotation is skipped under pressure and creates permanent single points of failure.
+
+## Details
+
+### HMAC Internals and Why Plain Hash-Concat Is Insecure
+
+HMAC-SHA-256 computes:
+
+```
+HMAC(K, m) = SHA-256((K' XOR opad) || SHA-256((K' XOR ipad) || m))
+```
+
+Where `K'` is the key padded to the hash block size (64 bytes for SHA-256), `ipad` is `0x36` repeated to the block size, and `opad` is `0x5c` repeated to the block size. This nested construction is specifically designed to prevent length extension attacks.
+
+**Why `SHA-256(key || message)` is insecure:** SHA-256 uses the Merkle-Damgard construction, which processes input in blocks and exposes the internal state as the final hash output. An attacker who sees `H = SHA-256(key || message)` can use `H` as the starting state and continue hashing to compute `SHA-256(key || message || padding || attacker_data)` without knowing the key. This enables message forgery by appending arbitrary data and computing a valid MAC for the extended message.
+
+**Why `SHA-256(message || key)` is also insecure:** This construction is vulnerable to collision attacks. If the attacker finds two messages `m1` and `m2` where `SHA-256(m1) == SHA-256(m2)` (a collision in the intermediate state), then `SHA-256(m1 || key) == SHA-256(m2 || key)` regardless of the key value. The key cannot differentiate messages that already collide.
+
+**Why HMAC is secure:** The nested structure uses two different derived keys (via XOR with ipad and opad). The inner hash produces an intermediate result that is then re-hashed with the outer key. This breaks both the length extension property (the outer hash re-initializes the state) and the collision transferability (the two hashing stages use different keys).
+
+Note: SHA-3 (Keccak) is not vulnerable to length extension attacks due to its sponge construction. `SHA3-256(key || message)` is safe, but using HMAC-SHA3-256 is still recommended for consistency and defense in depth.
+
+### Signature Scheme Comparison
+
+| Property           | HMAC-SHA-256                   | RSA-2048 PSS                 | ECDSA P-256                   | Ed25519               |
+| ------------------ | ------------------------------ | ---------------------------- | ----------------------------- | --------------------- |
+| Key type           | Symmetric (shared)             | Asymmetric (pub/priv)        | Asymmetric (pub/priv)         | Asymmetric (pub/priv) |
+| Key size           | 256 bits                       | 2048 bits (private)          | 256 bits (private)            | 256 bits (private)    |
+| Signature size     | 32 bytes                       | 256 bytes                    | 64 bytes                      | 64 bytes              |
+| Signing speed      | Very fast                      | Slow                         | Fast                          | Very fast             |
+| Verification speed | Very fast                      | Fast                         | Moderate                      | Fast                  |
+| Non-repudiation    | No                             | Yes                          | Yes                           | Yes                   |
+| Nonce requirement  | None                           | None (PSS internal)          | Critical (reuse = key leak)   | Deterministic (safe)  |
+| Primary pitfall    | Timing side channel on compare | Padding oracle (PKCS#1 v1.5) | Nonce reuse leaks private key | Few known pitfalls    |
+
+Ed25519 is the recommended default for new systems. Its deterministic nonce generation eliminates the ECDSA nonce-reuse vulnerability that broke the PlayStation 3 code signing (2010) and compromised Bitcoin wallets (2013). RSA remains relevant for legacy interoperability but produces larger signatures and slower signing.
+
+### Webhook Verification Worked Example
+
+When receiving a webhook POST with an `X-Signature` header:
+
+1. **Extract the raw request body as bytes** -- before JSON parsing, because parsing may reorder object keys, change whitespace, or normalize Unicode, producing a different byte sequence than what was signed. Most web frameworks provide access to the raw body (`req.rawBody` in Express with appropriate middleware, `request.body` read as bytes in Flask).
+
+2. **Compute HMAC-SHA-256** using the shared secret from the webhook provider: `HMAC-SHA-256(webhook_secret, raw_body)`.
+
+3. **Encode the result** in the format the provider uses (typically hex or base64). Match the provider's encoding exactly.
+
+4. **Compare with the header value using constant-time comparison.** In Node.js: `crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(received))`. In Python: `hmac.compare_digest(computed, received)`. In Go: `subtle.ConstantTimeCompare([]byte(computed), []byte(received))`.
+
+The timing attack with non-constant comparison: string equality (`===`) compares byte by byte and returns false on the first mismatch. An attacker sends candidate signatures and measures response times. A signature matching the first 10 bytes takes measurably longer to reject than one matching only the first 2 bytes. Over thousands of requests with statistical analysis, the attacker reconstructs the correct signature one byte at a time without knowing the secret. This attack has been demonstrated practically against real web services.
+
+### JWT Algorithm Selection
+
+**HS256 (HMAC-SHA-256):** Appropriate only when the issuer and audience are the same service -- the secret must be shared, meaning both parties can forge tokens. If the secret leaks from any consumer, all consumers are compromised. This is a symmetric trust model identical to HMAC -- both parties hold the signing key.
+
+**RS256 (RSA-SHA-256) or ES256 (ECDSA-SHA-256):** Mandatory when tokens are verified by a different service than the issuer. Only the issuer holds the private key. Resource servers verify with the public key obtained from the JWKS endpoint. Key distribution is simple and safe because public keys are not secret -- they can be published openly.
+
+**EdDSA (Ed25519):** Preferred for new systems. Smallest tokens, fastest verification, no padding oracle risk, and deterministic signatures. Adoption is growing rapidly -- supported by most modern JWT libraries including `jose` (Node.js), `PyJWT` (Python), and `golang-jwt` (Go).
+
+Never allow the JWT `alg` field to control algorithm selection at the server. Configure the expected algorithm on the server and reject tokens using any other algorithm. The default behavior of many older libraries is to trust the `alg` header, which is the root cause of the algorithm confusion attack class.
+
+### Key Rotation in Practice
+
+Key rotation for HMAC secrets and signing keys follows a three-phase lifecycle:
+
+1. **Generation:** Create the new key and deploy it to all verifiers. Verifiers accept both old and new keys. Signers continue using the old key. This is the "dual-read" phase.
+
+2. **Promotion:** Switch signers to the new key. Verifiers still accept both keys to handle in-flight messages signed with the old key. For JWTs, use the `kid` (key ID) header to indicate which key signed the token.
+
+3. **Retirement:** After the maximum validity period of any token signed with the old key has elapsed, remove the old key from all verifiers. Only the new key remains.
+
+For HMAC webhooks, coordinate with the provider's rotation API (Stripe, GitHub, and Slack all support webhook secret rotation with a transition period). For JWKS-based systems, publish both keys in the JWKS endpoint during the transition, each with a unique `kid`.
+
+Automated rotation on a schedule (e.g., every 90 days) prevents key staleness and ensures the rotation process itself is exercised regularly. A rotation mechanism that has never been tested will fail when an emergency rotation is needed.
+
+### Choosing Between HMAC and Digital Signatures
+
+Use this decision framework:
+
+**Choose HMAC-SHA-256 when:**
+
+- Both parties are in the same trust domain (your own microservices)
+- You need maximum speed (HMAC is 10-100x faster than asymmetric signatures)
+- Key distribution is manageable (shared secret between two parties)
+- Non-repudiation is not required (you do not need to prove which specific party signed)
+- Webhook verification from a trusted provider
+
+**Choose digital signatures (Ed25519 / ECDSA / RSA) when:**
+
+- The verifier should not be able to create signatures (different trust domains)
+- Multiple parties need to verify but only one party should sign
+- Non-repudiation is required for legal, audit, or compliance reasons
+- Key distribution must be public (JWKS endpoints, public key registries)
+- Signing software packages, container images, or code commits
+- JWT tokens verified by multiple resource servers
+
+**Choose Macaroons when:**
+
+- You need delegatable, attenuatable bearer tokens
+- Authorization decisions span multiple services
+- You want to add restrictions without contacting the token issuer
+- Third-party caveats are needed for federated authorization
+
+### HMAC Key Size Requirements
+
+The HMAC key should be at least as long as the hash output. For HMAC-SHA-256, use a 256-bit (32-byte) key minimum. Keys shorter than the hash output reduce security margins. Keys longer than the hash block size (512 bits for SHA-256) are hashed first, which does not reduce security but adds unnecessary computation.
+
+Generate HMAC keys from a CSPRNG, never from passwords or human-memorable strings. If a human-memorable input must be used, derive the HMAC key using a KDF (HKDF or PBKDF2) with appropriate parameters.
+
+## Anti-Patterns
+
+1. **Using `SHA-256(secret + message)` instead of HMAC.** Vulnerable to length extension attacks on Merkle-Damgard hash functions. The attacker appends data to the message and computes a valid hash without knowing the secret. Always use the HMAC construction, which is specifically designed to prevent this class of attack.
+
+2. **Comparing MACs with string equality.** Timing side channels allow an attacker to reconstruct the correct MAC byte by byte by measuring response time differences across many requests. Always use constant-time comparison: `crypto.timingSafeEqual` (Node.js), `hmac.compare_digest` (Python), `subtle.ConstantTimeCompare` (Go), `MessageDigest.isEqual` (Java).
+
+3. **Hardcoding HMAC secrets in source code.** Secrets in code end up in version control history (persisting even after deletion), CI logs, error messages, stack traces, and developer laptops. Store HMAC secrets in a secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager) and inject them at runtime via environment variables or sidecar injection.
+
+4. **Allowing JWT `alg: none`.** Some JWT libraries accept unsigned tokens when the algorithm header is `none`. This allows any attacker to forge valid tokens by simply removing the signature and setting the algorithm to none. Always validate the algorithm against a server-side allowlist and reject `none` unconditionally.
+
+5. **No key rotation plan.** A leaked HMAC secret or signing key with no rotation mechanism means: revoking all existing tokens and signatures, coordinating an emergency key change across all consumers, and potentially losing non-repudiation for the entire validity period of the compromised key. Design key rotation from day one with overlapping validity windows. The rotation mechanism itself must be tested regularly.
+
+## 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-hashing-fundamentals, security-symmetric-encryption, security-asymmetric-encryption, security-cryptographic-randomness, owasp-cryptography, api-webhook-security
+
+## 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/cursor/security-hmac-signatures/skill.yaml

@@ -0,0 +1,40 @@
+name: security-hmac-signatures
+version: '1.0.0'
+description: HMAC for message authentication and digital signatures for non-repudiation -- when to use which, how they fail, and implementation pitfalls
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - security-hashing-fundamentals
+  - security-symmetric-encryption
+  - security-asymmetric-encryption
+  - security-cryptographic-randomness
+  - owasp-cryptography
+  - api-webhook-security
+stack_signals: []
+keywords:
+  - HMAC
+  - digital signature
+  - message authentication code
+  - MAC
+  - RSA signature
+  - ECDSA
+  - Ed25519
+  - webhook verification
+  - JWT signing
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/security-hsts-preloading/SKILL.md

@@ -0,0 +1,154 @@
+# HSTS and Preloading
+
+> Tell the browser "never connect to this domain over HTTP, ever" -- and make it permanent
+> by embedding the directive in every browser's shipped preload list
+
+## When to Use
+
+- Deploying HTTPS for a new domain and need to prevent HTTP downgrade attacks
+- Configuring security headers for production web applications
+- Evaluating whether to submit a domain to the HSTS preload list
+- Auditing existing HSTS configuration for correctness
+- Understanding SSL stripping attacks and how HSTS prevents them
+
+## Threat Context
+
+SSL stripping attacks (first demonstrated by Moxie Marlinspike at Black Hat 2009)
+intercept the initial HTTP request before the redirect to HTTPS and maintain a plaintext
+connection with the victim while establishing HTTPS with the server. The attacker proxies
+all traffic, rewriting HTTPS links to HTTP. The victim sees a working website with no
+browser warning because the connection was never upgraded to HTTPS in the first place.
+Tools like sslstrip automate this attack entirely. On public Wi-Fi networks, SSL stripping
+is trivial to execute with ARP spoofing. HSTS eliminates this by telling the browser to
+never attempt HTTP for the domain after the first successful HTTPS visit. The browser
+internally rewrites any `http://` URL to `https://` before sending the request. HSTS
+preloading eliminates even the first-visit vulnerability by shipping the directive in the
+browser itself -- the browser knows to use HTTPS before it has ever visited the domain.
+
+## Instructions
+
+1. **Set the HSTS header on all HTTPS responses.**
+   `Strict-Transport-Security: max-age=31536000; includeSubDomains`. The `max-age=31536000`
+   directive means the browser will remember the HSTS policy for 1 year (31,536,000
+   seconds). `includeSubDomains` applies the directive to all subdomains, not just the
+   apex domain. After receiving this header over a valid HTTPS connection, the browser
+   will refuse to connect to the domain over HTTP for the specified duration, automatically
+   upgrading any HTTP URL to HTTPS internally.
+
+2. **Redirect HTTP to HTTPS first.** HSTS only works if the browser receives it over a
+   valid HTTPS connection. Set up an HTTP-to-HTTPS 301 (permanent) redirect on all HTTP
+   endpoints. The HSTS header must be sent on the HTTPS response -- it is ignored on HTTP
+   responses per RFC 6797. The redirect ensures users who type `http://` are upgraded,
+   and the HSTS header ensures they stay upgraded.
+
+3. **Ramp up max-age gradually.** Start with a short max-age (5 minutes = 300 seconds)
+   while testing. Verify no mixed content issues, no broken subdomains, no HTTP-only
+   internal tools that would be affected. Increase to 1 week (604800), then 1 month
+   (2592000), then 1 year (31536000). If HSTS is deployed with a 1-year max-age and
+   HTTPS breaks (certificate expired, misconfiguration), the domain is inaccessible for
+   up to 1 year for users who cached the directive. There is no way to revoke an HSTS
+   directive from the server side once cached.
+
+4. **Submit to the HSTS preload list.** Once max-age is at least 1 year,
+   `includeSubDomains` is set, and a `preload` directive is added
+   (`Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`), submit
+   the domain at hstspreload.org. Once accepted, every Chrome, Firefox, Safari, and Edge
+   browser ships with the directive baked in at build time. The first-visit vulnerability
+   is eliminated entirely. This is the strongest transport security guarantee available.
+
+5. **Ensure all subdomains support HTTPS before adding `includeSubDomains`.** If any
+   subdomain serves HTTP-only content (legacy internal tools, staging environments,
+   development servers, marketing landing pages on a subdomain), `includeSubDomains` will
+   break it. Audit all subdomains -- including those managed by other teams, third-party
+   services using CNAME records, and forgotten legacy systems -- before enabling
+   `includeSubDomains`.
+
+6. **Understand preload list removal is slow.** Removing a domain from the preload list
+   requires: removing the `preload` directive from the header, submitting a removal
+   request at hstspreload.org, waiting for browser vendors to process it (weeks to
+   months), and then waiting for all users to update their browsers. Full removal can take
+   6-12 months. This is intentional -- preloading is a commitment, not a toggle.
+
+## Details
+
+### SSL Stripping Attack Flow
+
+1. Victim connects to `http://bank.com` (typed without `https://` or clicked a link)
+2. Attacker on the same network intercepts the HTTP request (via ARP spoofing, rogue AP)
+3. Attacker connects to `https://bank.com` on behalf of the victim
+4. Attacker proxies all traffic, rewriting `https://` links in responses to `http://`
+5. Victim sees a fully functional bank website served over HTTP
+6. Attacker captures all credentials, session tokens, and financial data in plaintext
+
+The victim has no browser warning because the connection was HTTP from the start. HSTS
+defeats this because the browser knows (from a previous visit or the preload list) that
+bank.com must use HTTPS and refuses to send any HTTP request.
+
+### HSTS Preload List Mechanics
+
+The preload list is maintained as a JSON file in the Chromium source code
+(`net/http/transport_security_state_static.json`). Firefox, Safari, and Edge consume the
+same list. Submission requirements: the `preload` directive in the HSTS header,
+`includeSubDomains` directive, max-age of at least 31536000 (1 year), valid HTTPS on the
+apex domain (not just `www`), and valid HTTPS on all subdomains. The list is checked at
+browser build time and shipped with each browser release, not fetched at runtime.
+
+### Common Deployment Mistakes
+
+- Mixed content: loading images, scripts, or stylesheets over HTTP from an HTTPS page
+  (browsers block or warn, degrading user experience)
+- Redirect loops: HTTP redirects to HTTPS which redirects back to HTTP
+- Subdomains without HTTPS: `internal.example.com` only serves HTTP, but
+  `includeSubDomains` forces HTTPS
+- HSTS header on HTTP responses: ignored by spec, but confusing during debugging
+- Setting `max-age=0` accidentally: disables HSTS, removing protection
+
+### Testing HSTS Configuration
+
+Before deploying HSTS to production, verify the configuration thoroughly. Use
+`curl -sI https://example.com | grep -i strict` to check the header is present and
+correctly formatted. Use the Qualys SSL Labs test (ssllabs.com/ssltest) which reports
+HSTS status, max-age, and preload eligibility. Use hstspreload.org to check whether the
+domain meets all preload requirements. Test from multiple clients and browsers: some
+proxies strip security headers, and some CDN configurations do not forward them. Verify
+that the header is not sent on HTTP responses (it should only appear on HTTPS). Test
+subdomain coverage by checking HTTPS on every subdomain you can discover.
+
+### Interaction with Other Security Headers
+
+HSTS works with `Content-Security-Policy: upgrade-insecure-requests` which automatically
+rewrites HTTP sub-resource URLs to HTTPS within the page. Together they ensure that both
+navigation and sub-resource loading use HTTPS. HSTS also interacts with
+`Referrer-Policy`: HTTPS-to-HTTP transitions strip the referrer header, which HSTS
+prevents by ensuring all connections are HTTPS. The combination of HSTS, CSP
+upgrade-insecure-requests, and proper referrer policy creates a comprehensive transport
+security posture.
+
+## Anti-Patterns
+
+1. **HSTS without testing subdomains.** Enabling `includeSubDomains` when
+   `legacy.example.com` only serves HTTP breaks that subdomain for the HSTS max-age
+   duration. Users cannot bypass this -- the browser refuses to connect. Audit all
+   subdomains first, including those managed by other teams.
+
+2. **max-age of 0 in production.** `max-age=0` disables HSTS for any browser that
+   receives it. If an attacker can force the browser to receive this header (via MITM on
+   the first request before HSTS is cached), HSTS protection is removed for that user.
+   Never set max-age to 0 in production.
+
+3. **Preloading before readiness.** Submitting to the preload list before all subdomains
+   support HTTPS, before the team understands the commitment, or before testing with a
+   long max-age. Preload removal takes months and requires browser updates to propagate.
+   Treat preloading as irreversible for practical purposes.
+
+4. **HSTS on HTTP responses.** The `Strict-Transport-Security` header on an HTTP response
+   is ignored per RFC 6797 Section 7.2. If browsers honored it on HTTP, an attacker could
+   inject this header on an HTTP response to DoS a domain by forcing HTTPS on a domain
+   that does not support it. Browsers correctly ignore it on HTTP, but its presence
+   indicates a misconfiguration.
+
+5. **Relying only on HTTP-to-HTTPS redirects.** Redirects alone do not prevent SSL
+   stripping. The first request is still HTTP and interceptable. The redirect itself
+   travels over HTTP and can be modified by the attacker. HSTS ensures subsequent requests
+   are HTTPS without relying on a redirect. Preloading ensures even the first request is
+   HTTPS.

package/dist/agents/skills/cursor/security-hsts-preloading/skill.yaml

@@ -0,0 +1,38 @@
+name: security-hsts-preloading
+version: '1.0.0'
+description: HTTP Strict Transport Security and preload lists -- eliminating the first-request HTTP downgrade window and ensuring browsers never connect over plaintext
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - security-tls-fundamentals
+  - security-certificate-management
+  - security-mtls-design
+  - owasp-security-headers
+stack_signals: []
+keywords:
+  - HSTS
+  - HTTP Strict Transport Security
+  - preload
+  - SSL stripping
+  - HTTPS redirect
+  - max-age
+  - includeSubDomains
+  - transport security
+  - downgrade attack
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []