bd-security
Apply better-data's security discipline when touching Secret, EncryptionEngine, #[Sensitive], #[Encrypted], MetaKeyRegistry::register, RequestSource guards, or user_pass handling. Loud-over-silent — missing key throws, tampered ciphertext throws, unknown strict-whitelist field throws, colliding route-owned field throws; silent degradation is the worst outcome for security. Symmetric end-to-end — encrypt on write, decrypt on read; redact on toArray, reveal explicitly via $secret->reveal() inside compute() closures (the audit point); a new leak path needs a SecretTest leak probe. Never cache the raw key — EncryptionEngine re-reads BETTER_DATA_ENCRYPTION_KEY on every call so rotation works. Constant-time comparison — hash_equals, never == or ===. Use when any of those primitives is in the diff. Triggers on EncryptionEngine, Secret, Sensitive, Encrypted, RequestSource, BETTER_DATA_ENCRYPTION_KEY.
Lonsdale201 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Lonsdale201/wp-agent-skills --skill bd-security技能说明
name: bd-security description: >- Apply better-data's security discipline when touching Secret, EncryptionEngine, #[Sensitive], #[Encrypted], MetaKeyRegistry::register, RequestSource guards, or user_pass handling. Loud-over-silent — missing key throws, tampered ciphertext throws, unknown strict-whitelist field throws, colliding route-owned field throws; silent degradation is the worst outcome for security. Symmetric end-to-end — encrypt on write, decrypt on read; redact on toArray, reveal explicitly via $secret->reveal() inside compute() closures (the audit point); a new leak path needs a SecretTest leak probe. Never cache the raw key — EncryptionEngine re-reads BETTER_DATA_ENCRYPTION_KEY on every call so rotation works. Constant-time comparison — hash_equals, never == or ===. Use when any of those primitives is in the diff. Triggers on EncryptionEngine, Secret, Sensitive, Encrypted, RequestSource, BETTER_DATA_ENCRYPTION_KEY. metadata: wp-skills-author: "Soczó Kristóf" wp-skills-contact: "mailto:lonsdale201@hotmail.com" wp-skills-plugin: "better-data" wp-skills-plugin-version-tested: "phase-9" wp-skills-php-min: "8.3" wp-skills-last-updated: "2026-04-29"
better-data: Security-sensitive changes
For library maintainers touching anything in better-data's security perimeter — Secret, EncryptionEngine, #[Sensitive], #[Encrypted], RequestSource guards, password handling. Mistakes in this perimeter aren't bugs that show up in tests; they're regressions that ship plaintext to disk or leak credentials in logs.
Misconception this skill corrects
"I'll add a debug-mode that logs the encrypted value's plaintext when developer mode is on — it's only for development."
Don't. The security-feature-with-bypass is the worst outcome — caller assumes redaction is universal, log infrastructure picks up the "debug" path in production by accident, plaintext lands in CloudWatch / Sentry / wp-debug.log forever. The discipline is no-bypass: Secret's __toString returns '***' (src/Secret.php:84-87), jsonSerialize returns '***' (src/Secret.php:89-92), __debugInfo (controls var_dump / print_r) returns ['value' => '***'] (src/Secret.php:99-103), __serialize THROWS SecretSerializationException (src/Secret.php:105-109).
The throwing __serialize is deliberate — a caller serialized a Secret has already made a security-relevant mistake. Relaxing it to redact instead would silently let the bug ship. The exception forces them to either ->reveal() explicitly (audit point) or rethink the flow.
Other AI-prone misconceptions:
- "I'll cache the encryption key in a static property to avoid re-reading the constant on every call." Wrong —
EncryptionEnginedeliberately re-reads on every call (src/Encryption/EncryptionEngine.php:53-54) so key rotation viaBETTER_DATA_ENCRYPTION_KEY_PREVIOUSactually works. A process-long cache defeats rotation. - "
==and===are fine for comparing twoSecrets; the constant-time stuff is paranoia." Wrong — string compare is timing-dependent and leaks length / first-byte equality through repeated probing.Secret::equalsuseshash_equals(src/Secret.php:78-82). Always. - "If decryption fails, return null and the caller falls back to the default." Wrong — silent failure on decrypt is worse than an exception. A caller that gets
nullinstead of the expected secret may treat it as "user never set a key" and proceed.EncryptionEngine::decryptthrowsDecryptionFailedException(src/Encryption/EncryptionEngine.php:109,130).
When to use this skill
Trigger when ANY of the following is true:
- The diff touches
src/Secret.php,src/Encryption/EncryptionEngine.php,src/Attribute/Encrypted.php,src/Attribute/Sensitive.php. - The diff touches
MetaKeyRegistry::register, route-owned-field handling, orRequestSourceguards. - New code introduces a
Secrettyped property OR#[Encrypted]attribute. - New code calls
EncryptionEngine::encrypt/decrypt/looksEncrypted. - New code introduces password handling (
user_pass, hash storage, comparison). - Reviewing a PR that adds a "debug mode" / "verbose log" / "for development" flag near sensitive material.
Workflow
1. Threat model first (in the PR description or a code comment)
Write down explicitly:
- What is this change preventing? (e.g. "API tokens stored as plaintext in
wp_options.") - What remains un-prevented? (e.g. "Plaintext key in PHP memory between hydration and use; an attacker with PHP memory access can still read it.")
- What's the threat model? (e.g. "Database compromise, log file exposure. NOT defending against in-memory attackers — that requires HSM-grade key management.")
The goal: a future contributor reads the comment and knows whether their proposed change preserves or breaks the model.
2. Loud over silent
Every degradation must throw. The catalog:
| Condition | Throws |
|---|---|
| Encryption key constant not defined | RuntimeException |
decrypt called on garbage | DecryptionFailedException |
decrypt called with tampered ciphertext (GCM auth tag mismatch) | DecryptionFailedException |
Secret __serialize invoked | SecretSerializationException |
MetaKeyRegistry::register collision (one key, two DTOs) | RuntimeException |
RequestSource::noCollision finds an unexpected route-owned field in the body | RequestParamCollisionException |
strict mode + unknown DTO field in incoming data | UnknownFieldException |
If you add a security feature, add a corresponding throw. Don't ship a flag that converts the throw into a warning.
3. Symmetric end-to-end
Every encrypt has a matching decrypt, every redact has a matching reveal. Lookup table:
| Write side | Read side |
|---|---|
SinkProjection::prepareValue encrypts when `#[Encrypte |