exlim/cyberchef
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Absorb PAYMENT_VALIDATION_AUDIT.md into PAYMENT_RECIPES.md; tighten AGENTS.md

Browse Source 
PAYMENT_RECIPES.md:
- Removed stale AWS_PAYMENT_CRYPTOGRAPHY_RECIPES.md and PAYMENT_VALIDATION_AUDIT.md cross-references
- Added Validation Status section: class legend, full op matrix (current names, includes DUKPT Derive AES Key, HSM parse ops; removes deprecated Translate Payment PIN Data), release posture, references

AGENTS.md:
- Added Code Style section pointing to CONTRIBUTING.md conventions
- Merged "When Docker is unavailable" rule into Test And Debugging Baseline
- Removed now-redundant Current Project Preference section

PAYMENT_VALIDATION_AUDIT.md deleted (content absorbed above)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
J8k3 2026-05-18 20:24:48 -04:00
parent 09040b6bb7
commit f4bd260363
3 changed files with 72 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
AGENTS.md
View File

@ -11,6 +11,7 @@
- Do not spend time fixing Windows-only runtime or dependency issues unless explicitly requested. - Do not spend time fixing Windows-only runtime or dependency issues unless explicitly requested.
- Do not commit repo changes whose only purpose is to make local Windows execution work. - Do not commit repo changes whose only purpose is to make local Windows execution work.
- If a failure appears only in the local Windows shell, do not treat it as a code regression until it reproduces in Docker/Linux. - If a failure appears only in the local Windows shell, do not treat it as a code regression until it reproduces in Docker/Linux.
- When Docker is unavailable, restore Docker availability first rather than switching to Windows-specific debugging.
## Session Start ## Session Start
@ -19,6 +20,10 @@
- Only do this automatically when the worktree is clean. - Only do this automatically when the worktree is clean.
- If there are local changes already present, do not pull/rebase blindly; inspect first and avoid overwriting user work. - If there are local changes already present, do not pull/rebase blindly; inspect first and avoid overwriting user work.
## Code Style
Follow `CONTRIBUTING.md` coding conventions: 4-space indentation, CamelCase class identifiers, camelCase function/variable names, UNDERSCORE_UPPER_CASE constants, UTF-8 source encoding, UNIX line endings, all files end with a newline.
## Commit Scope ## Commit Scope
- Keep commits small and reviewable by default. - Keep commits small and reviewable by default.
@ -48,7 +53,3 @@ When adding, renaming, or removing a payment operation:
``` ```
Or `npx grunt dev` / `npx grunt prod`, which runs both steps automatically. CI runs them on every build. **Symptom of a stale registry:** `TypeError: f[e.module][e.name] is not a constructor` at runtime. Or `npx grunt dev` / `npx grunt prod`, which runs both steps automatically. CI runs them on every build. **Symptom of a stale registry:** `TypeError: f[e.module][e.name] is not a constructor` at runtime.
## Current Project Preference
- For this fork, validate payment-related changes through the Docker-based workflow before judging safety to commit.
- When Docker is unavailable, fix Docker availability first rather than switching to Windows-specific debugging.

69
PAYMENT_RECIPES.md
View File

@ -6,8 +6,6 @@ Owner:
These recipe starters are for software-only payment-crypto emulation, inspection, regression tests, and interoperability work. These recipe starters are for software-only payment-crypto emulation, inspection, regression tests, and interoperability work.
For AWS operation mapping, see `AWS_PAYMENT_CRYPTOGRAPHY_RECIPES.md`.
For validation posture, standards references, and release guardrails, see `PAYMENT_VALIDATION_AUDIT.md`.
## Naming Convention ## Naming Convention
@ -371,3 +369,70 @@ Flow:
- use `Key Generate` with JSON output to get a random AES-128/192/256 or TDES key plus its CMAC KCV - use `Key Generate` with JSON output to get a random AES-128/192/256 or TDES key plus its CMAC KCV
- cross-check the KCV with `Payment Calculate KCV` if you need to verify against an HSM-generated value - cross-check the KCV with `Payment Calculate KCV` if you need to verify against an HSM-generated value
- pipe the hex key directly into derivation, MAC, or encryption recipes - pipe the hex key directly into derivation, MAC, or encryption recipes
## Validation Status
Validation classes:
- `Verified` — backed by a public standard or official vendor documentation plus deterministic local vectors
- `Vendor-aligned` — behavior is intentionally shaped to AWS Payment Cryptography or scheme/vendor semantics; the full underlying standard is not publicly auditable here
- `Externally cross-checked` — checked against known-good vectors or an external implementation; the governing spec is not public here
- `Test helper` — useful for testing, parsing, or workflow emulation but not a full standards-faithful implementation
Release guidance: `Publish` = safe with normal guardrails; `Publish with guardrails` = keep inline Validation/Security/Assumptions warnings visible.
| Operation | Validation | Primary source(s) | Release |
| --- | --- | --- | --- |
| `PIN Block Build` | Vendor-aligned | AWS `GeneratePinData`; ISO 9564 | Publish with guardrails |
| `PIN Block Parse` | Vendor-aligned | AWS `VerifyPinData`; ISO 9564 | Publish with guardrails |
| `PIN Block Translate` | Vendor-aligned | AWS `TranslatePinData`; ISO 9564 | Publish with guardrails |
| `PIN Data Generate` | Vendor-aligned | AWS `GeneratePinData` | Publish with guardrails |
| `PIN Data Verify` | Vendor-aligned | AWS `VerifyPinData` | Publish with guardrails |
| `Payment Calculate KCV` | Verified | NIST SP 800-38B; generic AES/TDES/HMAC primitives | Publish |
| `DUKPT Derive TDES Key` | Externally cross-checked | ANSI X9.24-1; AWS DUKPT terminology | Publish with guardrails |
| `DUKPT Derive AES Key` | Vendor-aligned | ANSI X9.24-3; AWS DUKPT terminology | Publish with guardrails |
| `Derive ECDH Key Material` | Verified | AWS `TranslateKeyMaterial`; AWS `EcdhDerivationAttributes`; RFC 3394 | Publish |
| `Payment Encrypt Data` | Vendor-aligned | AWS `EncryptData` | Publish with guardrails |
| `Payment Decrypt Data` | Vendor-aligned | AWS `DecryptData` | Publish with guardrails |
| `Payment Re-Encrypt Data` | Vendor-aligned | AWS `ReEncryptData` | Publish with guardrails |
| `MAC Generate` | Verified (HMAC/CMAC); Vendor-aligned (ISO9797/DUKPT/AS2805) | NIST SP 800-38B; AWS MAC overview | Publish with guardrails |
| `MAC Verify` | Verified (HMAC/CMAC); Vendor-aligned (ISO9797/DUKPT/AS2805) | NIST SP 800-38B; AWS MAC overview | Publish with guardrails |
| `EMV Generate MAC` | Vendor-aligned | AWS EMV MAC use case | Publish with guardrails |
| `EMV Verify MAC` | Vendor-aligned | AWS EMV MAC use case | Publish with guardrails |
| `EMV Generate MAC (PIN Change)` | Test helper | AWS `GenerateMacEmvPinChange` | Publish with guardrails |
| `EMV Generate ARQC` | Vendor-aligned | AWS `VerifyAuthRequestCryptogram` | Publish with guardrails |
| `EMV Verify ARQC` | Vendor-aligned | AWS `VerifyAuthRequestCryptogram` | Publish with guardrails |
| `EMV Generate ARPC` | Vendor-aligned | AWS `VerifyAuthRequestCryptogram` issuer flow | Publish with guardrails |
| `Card Validation Data Generate` | Vendor-aligned | AWS `GenerateCardValidationData` | Publish with guardrails |
| `Card Validation Data Verify` | Vendor-aligned | AWS `VerifyCardValidationData` | Publish with guardrails |
| `IBM 3624 Generate PIN Offset` | Vendor-aligned | AWS IBM 3624 PIN verification object | Publish with guardrails |
| `IBM 3624 Verify PIN` | Vendor-aligned | AWS IBM 3624 PIN verification object | Publish with guardrails |
| `VISA PVV Generate` | Vendor-aligned | AWS VISA PIN verification object | Publish with guardrails |
| `VISA PVV Verify` | Vendor-aligned | AWS VISA PIN verification object | Publish with guardrails |
| `AS2805 Generate KEK Validation` | Test helper | AWS `GenerateAs2805KekValidation` | Publish with guardrails |
| `PAN Generate` | Verified (Luhn/public ranges); Vendor-aligned (curated samples) | Discover public test-card page; Mastercard public AVS scenarios | Publish with guardrails |
| `PAN Parse` | Verified | Public card numbering rules | Publish |
| `TR-31 Parse Key Block` | Test helper | AWS `TranslateKeyMaterial` workflow context | Publish with guardrails |
| `TR-34 Parse Key Transport` | Test helper | AWS `TranslateKeyMaterial` workflow context | Publish with guardrails |
| `HSM Parse Thales Command` | Test helper | Thales payShield command syntax reference | Publish with guardrails |
| `HSM Parse Futurex Command` | Test helper | Futurex Excrypt command syntax reference | Publish with guardrails |
### Release Posture
- Publish the current payment surface with its existing inline warnings intact
- Do not describe the fork as a certified HSM, production key-custody platform, or PCI-scoped control surface
- Describe it as a software emulation and interoperability tool for development, testing, and education
Pre-publish checklist:
1. Rebuild Docker and confirm updated recipe descriptions are visible in the UI
2. Re-run the payment operation subset tests (`npm test` targeting `Payment.mjs`)
3. Spot-check `Populate test data` on argument-heavy operations
### References
- AWS Payment Cryptography Data Plane API: https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/Welcome.html
- AWS MAC overview: https://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-mac.html
- NIST SP 800-38B CMAC: https://csrc.nist.gov/pubs/sp/800/38/b/upd1/final
- RFC 3394 AES Key Wrap: https://www.rfc-editor.org/rfc/rfc3394
- Discover public test-card page: https://www.discoverglobalnetwork.com/resources/businesses/check-your-card-reader/
- Mastercard AVS test scenarios: https://static.developer.mastercard.com/content/mastercard-send-avs/uploads/avs-test-case-scenario-v4.pdf
- Payment card number background: https://en.wikipedia.org/wiki/Payment_card_number

82
PAYMENT_VALIDATION_AUDIT.md
View File

@ -1,82 +0,0 @@
# Payment Validation Audit
Owner:
- Jacob Marks, `https://jacobmarks.com`
- Fork home: `https://github.com/J8k3/CyberChef`
This audit records how each payment-facing operation in this fork was validated, what source material it maps to, and how it should be described before publishing.
Validation classes:
- `Verified`: backed by a public standard or official vendor documentation plus deterministic local vectors.
- `Vendor-aligned`: behavior is intentionally shaped to AWS Payment Cryptography or scheme/vendor semantics, but the full underlying standard is not publicly auditable here.
- `Externally cross-checked`: implementation was checked against known-good vectors or an external implementation, but the governing spec is not public here.
- `Emulation helper`: intentionally useful for testing, parsing, or workflow emulation, but not a full standards-faithful implementation.
Release guidance:
- `Publish`: safe to publish with normal guardrails.
- `Publish with guardrails`: publish, but keep the validation/security/assumption warnings visible in the recipe UI and docs.
- `Hold`: do not publish without more verification.
Primary public references used in this audit:
- AWS Payment Cryptography Data Plane API Reference: https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/Welcome.html
- AWS Data Plane operations list: https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_Operations.html
- AWS MAC overview: https://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-mac.html
- AWS EMV MAC use case: https://docs.aws.amazon.com/payment-cryptography/latest/userguide/use-cases-issuers.generalfunctions.emvmac.html
- AWS TranslateKeyMaterial: https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_TranslateKeyMaterial.html
- AWS ECDH derivation attributes: https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_EcdhDerivationAttributes.html
- AWS IBM 3624 PIN verification object: https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_Ibm3624PinVerification.html
- AWS VISA PIN verification object: https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_VisaPinVerification.html
- NIST SP 800-38B CMAC: https://csrc.nist.gov/pubs/sp/800/38/b/upd1/final
- RFC 3394 AES Key Wrap: https://www.rfc-editor.org/rfc/rfc3394
- Discover public test-card page: https://www.discoverglobalnetwork.com/resources/businesses/check-your-card-reader/
- Mastercard AVS test scenarios with public sample PANs: https://static.developer.mastercard.com/content/mastercard-send-avs/uploads/avs-test-case-scenario-v4.pdf
- Payment card number background and ranges: https://en.wikipedia.org/wiki/Payment_card_number
## Matrix
| Operation | Validation | Primary source(s) | Local evidence | Release note |
| --- | --- | --- | --- | --- |
| `Build PIN Block` | `Vendor-aligned` | AWS `GeneratePinData`; ISO 9564 format conventions are used, but full ISO text is not public here. | Deterministic vectors in `tests/operations/tests/Payment.mjs` for format `0`; UI warns that only clear formats `0/1/3` are implemented. | `Publish with guardrails` |
| `Parse PIN Block` | `Vendor-aligned` | AWS `VerifyPinData`; same clear ISO 9564 format assumptions as above. | Deterministic vectors in `tests/operations/tests/Payment.mjs`; JSON output exposes the exact parsed fields. | `Publish with guardrails` |
| `Translate PIN Block` | `Vendor-aligned` | AWS `TranslatePinData`; same clear ISO 9564 format assumptions as above. | Deterministic vectors in `tests/operations/tests/Payment.mjs`; current scope is clear block translation only. | `Publish with guardrails` |
| `Generate Payment PIN Data` | `Vendor-aligned` | AWS `GeneratePinData`. | Wrapper behavior is covered by the PIN block vectors and inline scope warnings. | `Publish with guardrails` |
| `Translate Payment PIN Data` | `Vendor-aligned` | AWS `TranslatePinData`. | Wrapper behavior is covered by the PIN block vectors and inline scope warnings. | `Publish with guardrails` |
| `Verify Payment PIN Data` | `Vendor-aligned` | AWS `VerifyPinData`. | Wrapper behavior is covered by the PIN block vectors and inline scope warnings. | `Publish with guardrails` |
| `Calculate Payment KCV` | `Verified` | NIST SP 800-38B for CMAC; generic AES/TDES/HMAC primitive behavior. | Fixed vectors for HMAC, AES-CMAC empty/zeros/ones, and AES-ECB zeros in `tests/operations/tests/Payment.mjs`. | `Publish` |
| `Derive DUKPT Key` | `Externally cross-checked` | ANSI X9.24 governs DUKPT, but the spec text is not public here; AWS terminology also aligns the feature surface. | Known IPEK vector in `tests/operations/tests/Payment.mjs`; transaction-key behavior was previously cross-checked against an external implementation. | `Publish with guardrails` |
| `Derive ECDH Key Material` | `Verified` | AWS `TranslateKeyMaterial`, AWS `EcdhDerivationAttributes`, RFC 3394 for downstream AES Key Wrap usage. | PEM/SPKI/SEC1 handling is exercised locally; operation is explicit that it returns shared secret material and not a wrapped-key workflow by itself. | `Publish` |
| `Encrypt Payment Data` | `Vendor-aligned` | AWS `EncryptData`. | Covered by wrapper tests and use of existing CyberChef AES/TDES primitives; docs state this is software emulation, not key-ARN/HSM custody. | `Publish with guardrails` |
| `Decrypt Payment Data` | `Vendor-aligned` | AWS `DecryptData`. | Covered by wrapper tests and use of existing CyberChef AES/TDES primitives. | `Publish with guardrails` |
| `Re-Encrypt Payment Data` | `Vendor-aligned` | AWS `ReEncryptData`. | Wrapper logic is straightforward decrypt-then-encrypt with payment-facing terminology; docs now document the explicit chain. | `Publish with guardrails` |
| `Generate Payment MAC` | `Verified` for static `HMAC` / `CMAC`; `Vendor-aligned` for ISO9797, DUKPT, and AS2805 modes. | NIST SP 800-38B; AWS MAC overview. | Fixed vectors for HMAC SHA-256, AES-CMAC, and DUKPT MAC in `tests/operations/tests/Payment.mjs`; UI now distinguishes primitive-backed modes from payment-profile modes. | `Publish with guardrails` |
| `Verify Payment MAC` | `Verified` for static `HMAC` / `CMAC`; `Vendor-aligned` for ISO9797, DUKPT, and AS2805 modes. | NIST SP 800-38B; AWS MAC overview. | Fixed verification vectors in `tests/operations/tests/Payment.mjs`; UI mirrors generation warnings. | `Publish with guardrails` |
| `Generate EMV MAC` | `Vendor-aligned` | AWS EMV MAC use case; AWS MAC overview. | Deterministic local vectors; UI explicitly states that the caller must supply the session integrity key and payload. | `Publish with guardrails` |
| `Verify EMV MAC` | `Vendor-aligned` | AWS EMV MAC use case; AWS MAC overview. | Deterministic local verification vectors; same scope and derivation warnings as generation. | `Publish with guardrails` |
| `Generate EMV MAC For PIN Change` | `Emulation helper` | AWS `GenerateMacEmvPinChange`. | Implemented as an issuer-script MAC helper with explicit assumptions; not a full issuer-script lifecycle. | `Publish with guardrails` |
| `Generate EMV ARQC` | `Vendor-aligned` | AWS `VerifyAuthRequestCryptogram`; EMV semantics are profile-specific here. | Deterministic local vectors; UI states that the EMV session key and preassembled data must already be provided. | `Publish with guardrails` |
| `Verify EMV ARQC` | `Vendor-aligned` | AWS `VerifyAuthRequestCryptogram`. | Deterministic local verification vectors; same session-key and preimage assumptions are visible in the recipe. | `Publish with guardrails` |
| `Generate EMV ARPC` | `Vendor-aligned` | AWS `VerifyAuthRequestCryptogram` related issuer flow semantics. | Deterministic local vectors; recipe text now states that ARPC generation assumes already-derived key material. | `Publish with guardrails` |
| `Generate Card Validation Data` | `Vendor-aligned` | AWS `GenerateCardValidationData`. | Known-good CVV2 sample vector in `tests/operations/tests/Payment.mjs`; UI calls out CVV2=`000` and iCVV=`999` service-code assumptions. | `Publish with guardrails` |
| `Verify Card Validation Data` | `Vendor-aligned` | AWS `VerifyCardValidationData`. | Verification vectors in `tests/operations/tests/Payment.mjs`; scope warnings mirror generation. | `Publish with guardrails` |
| `Generate IBM 3624 PIN Offset` | `Vendor-aligned` | AWS IBM 3624 PIN verification object. | Deterministic local vectors; AWS object model validates the parameter shape, but the full scheme spec was not audited here. | `Publish with guardrails` |
| `Verify IBM 3624 PIN` | `Vendor-aligned` | AWS IBM 3624 PIN verification object. | Deterministic local vectors; recipe warns that this is a software verification helper. | `Publish with guardrails` |
| `Generate VISA PVV` | `Vendor-aligned` | AWS VISA PIN verification object. | Deterministic local vectors; UI notes the PVKI/PVV assumptions and clear-key nature. | `Publish with guardrails` |
| `Verify VISA PVV` | `Vendor-aligned` | AWS VISA PIN verification object. | Deterministic local vectors; UI mirrors generation assumptions. | `Publish with guardrails` |
| `Generate AS2805 KEK Validation` | `Emulation helper` | AWS `GenerateAs2805KekValidation`; no public AS2805 standard text was audited here. | Deterministic local vectors; recipe now explicitly labels this as emulation rather than a certified host/HSM implementation. | `Publish with guardrails` |
| `Generate Test PAN` | `Verified` for Luhn and public-brand range generation; `Vendor-aligned` for curated samples. | Discover public test-card page; Mastercard public AVS scenarios; public numbering rules. | Fixed Visa curated vector and deterministic generated Amex vector in `tests/operations/tests/Payment.mjs`; UI distinguishes curated samples from generated valid PANs. | `Publish with guardrails` |
| `Parse PAN` | `Verified` for Luhn and public-brand range parsing. | Discover public test-card page; public numbering rules. | Discover sample vector in `tests/operations/tests/Payment.mjs`; parser output exposes matched rule and Luhn result. | `Publish` |
| `Parse TR-31 key block` | `Emulation helper` | AWS `TranslateKeyMaterial` as surrounding workflow context. | Header-only deterministic test vector in `tests/operations/tests/Payment.mjs`; UI states that this is a parser/inspection helper, not full TR-31 processing. | `Publish with guardrails` |
| `Parse TR-34 B9 envelope` | `Emulation helper` | AWS `TranslateKeyMaterial` as surrounding workflow context. | Deterministic synthetic parser sample in `tests/operations/tests/Payment.mjs`; UI states that this is an inspection helper, not full TR-34 validation. | `Publish with guardrails` |
## Publish Notes
Recommended release posture:
- publish the current payment surface
- keep the current inline `Validation`, `Security`, and `Assumptions` wording visible in the recipe UI
- do not describe the fork as a certified HSM, production key-custody platform, or PCI-scoped control surface
- describe it as a software emulation and interoperability tool for development, testing, and education
Recommended final pre-publish checks:
1. Rebuild Docker and manually confirm that the updated recipe descriptions are visible.
2. Re-run the payment operation subset tests.
3. Spot-check `Populate test data` on argument-heavy operations to ensure the floating-label fix still holds after the latest UI text changes.