跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
安全

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 — EncryptionEngine deliberately re-reads on every call (src/Encryption/EncryptionEngine.php:53-54) so key rotation via BETTER_DATA_ENCRYPTION_KEY_PREVIOUS actually works. A process-long cache defeats rotation.
  • "== and === are fine for comparing two Secrets; the constant-time stuff is paranoia." Wrong — string compare is timing-dependent and leaks length / first-byte equality through repeated probing. Secret::equals uses hash_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 null instead of the expected secret may treat it as "user never set a key" and proceed. EncryptionEngine::decrypt throws DecryptionFailedException (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, or RequestSource guards.
  • New code introduces a Secret typed 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:

ConditionThrows
Encryption key constant not definedRuntimeException
decrypt called on garbageDecryptionFailedException
decrypt called with tampered ciphertext (GCM auth tag mismatch)DecryptionFailedException
Secret __serialize invokedSecretSerializationException
MetaKeyRegistry::register collision (one key, two DTOs)RuntimeException
RequestSource::noCollision finds an unexpected route-owned field in the bodyRequestParamCollisionException
strict mode + unknown DTO field in incoming dataUnknownFieldException

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 sideRead side
SinkProjection::prepareValue encrypts when `#[Encrypte
阅读完整来源 ↗