{
  "markdown": "# wireforge-core\n\n> ### SR2026 address check in 30 seconds\n>\n> CBPR+ SR2026 makes structured debtor/creditor postal addresses (`TwnNm` +\n> `Ctry` in dedicated fields) **mandatory on 2026-11-14**. Batch-scan your\n> outbound pacs.008 / pacs.004 / pacs.003 / pain.001 store before the deadline:\n>\n> ```bash\n> cargo install --git https://github.com/hanmahong5-arch/wireforge-core wf-cli\n> wf xform address-check outbox/     # exit 0 = compliant, 1 = gaps, 2 = unreadable\n> ```\n>\n> Runs entirely on your machine — no message ever leaves it. CI-ready exit\n> codes. This is a structural presence **DETECTOR** for the cited SR2026 rule,\n> not a full CBPR+ validation and not a certification; details\n> [below](#sr2026-address-compliance-gate-cli).\n\n## What is this?\n\nWireforge is a **local-first toolkit for financial wire messages** — a CLI\n(`wf`), an AI-agent server (`wf-mcp`, 13 read-only MCP tools), and the Rust\ncrates underneath. It exists because four problems keep landing on payment\nteams' desks:\n\n| Pain | What Wireforge does about it |\n|---|---|\n| **SR2026 deadline (2026-11-14):** CBPR+ makes structured debtor/creditor addresses mandatory; free-text `AdrLine` messages face rejection and repair queues | `wf xform address-check` batch-scans your outbound pacs.008 / pacs.004 / pacs.003 / pain.001 store and exits with a CI-ready 0/1/2 verdict per run |\n| **Silent MT↔MX data loss:** coexistence-era conversion truncates 140-char MX names/remittance into 4×35 MT blocks — an AML/screening risk nobody reports | `wf xform diff` compares a matched MT103 + pacs.008 pair and names each truncated/dropped role, including the exact lost characters |\n| **Messages are too sensitive for online tools:** you cannot paste production payment data into a web validator | Everything runs offline on your machine — no network calls, no telemetry, stdout clean for pipes |\n| **Legacy migration \"trust us\" gap:** a replaced ISO 8583 endpoint claims byte-compatibility; nobody can prove it | `wf oracle check` replays captured legacy-vs-migrated responses under an operator-approved mask spec and emits field-level regression-conformance EVIDENCE; `wf layout check` verifies recovered fixed-length specs against real captures |\n\n**Who it's for:** payment/integration engineers wiring compliance gates into\nCI, compliance teams sizing their SR2026 backlog, migration teams needing\nregression evidence, and AI-agent users who want a safe read-only tool for\nmessage forensics.\n\n**Start here → [User Guide](docs/user-guide.md)** — task-oriented manual for\nevery command, CI recipes included. No Rust knowledge required.\n\n## For developers: the crates\n\nApache-2.0 Rust crates for parsing, building, and reasoning about\nfinancial wire messages. Today covers **ISO 8583** (three on-the-wire\ndialects + runtime-loadable field specs), **SWIFT MT** (structural +\ntag-level semantic decoders, plus a typed facade), **ISO 20022 / MX**\n(inbound parse via a typed facade), **MT↔MX truncation diffing**,\n**EBCDIC** (CP037 / CP500), **China GM/T crypto** (SM3 / SM4 / SM2,\nfunctional — not 密评-certified), and the **`.wf` flat-file format**\nfor capturing message specs under Git.\n\n| Crate         | Purpose                                                            |\n|---------------|--------------------------------------------------------------------|\n| `wf-bitmap`   | ISO 8583 primary / secondary bitmap encode + decode.               |\n| `wf-codec`    | ISO 8583 parser + builder + 128-field table (HybridAscii /        |\n|               | FullAscii / FullBinary BCD dialects) + runtime-loadable FieldSpec; |\n|               | SWIFT MT structural parser + semantic decoders (20 / 32A / 50K);  |\n|               | EBCDIC CP037 / CP500 single-byte codec.                          |\n| `wf-cli`      | `wf` CLI binary — parse / build / validate from the shell.         |\n| `wf-format`   | Parser for the `.wf` Bruno-inspired flat-file DSL.                 |\n| `wf-mcp`      | Model Context Protocol server — expose codec to AI agents.         |\n| `wf-sm`       | China GM/T cryptography — SM3 hash, SM4 cipher (ECB/CBC +          |\n|               | bounded streaming), SM2 signature (functional, not 密评-certified).|\n| `wf-swift`    | Typed SWIFT MT facade over an external parser, with lossless       |\n|               | fallback to `wf-codec`'s structural parser.                        |\n| `wf-mx`       | ISO 20022 / MX inbound facade (pacs / pain / camt / admi).         |\n| `wf-xform`    | pacs.008.001.08 ↔ MT103 truncation/loss **detector** across five   |\n|               | roles — DETECTOR not converter; no certification claim.            |\n| `wf-wal`      | Append-only write-ahead log with CRC-32 + `truncate_to` recovery.  |\n| `wf-obs`      | Local-first observability: leveled `tracing` logs, bounded raw-    |\n|               | buffer hex dumps, stderr subscriber setup (no telemetry).          |\n\n**Scope & honesty (`wf-xform`):** it compares pacs.008.001.08 against\nMT103 over five core roles and is SYNTHETIC-validated only (no real\nproduction samples yet); it is a DETECTOR, not a converter, and makes\nno certification, conformance, or equivalence claim.\n\n`tools/sample-sanitize/` is a standalone (out-of-workspace) binary\nthat redacts PAN / track data from real ISO 8583 hex samples; see\n[`docs/sample-policy.md`](docs/sample-policy.md) for the redaction\ncontract.\n\n## 5-minute try\n\nNo clone needed — install `wf` straight from the repo and parse one\nsample ISO 8583 frame:\n\n```bash\ncargo install --git https://github.com/hanmahong5-arch/wireforge-core wf-cli\necho \"303230302000000000000000303030303030\" | wf parse -\n```\n\nYou should see a tree with `MTI = 0200`, the bitmap, and field 3\n(\"Processing Code\") decoded. If something looks off — wrong field, a\ncrash, anything — please file an issue using the **feedback** template.\nHonest reports beat polished stars.\n\nPrebuilt binaries for Linux / macOS / Windows are attached to each\n[GitHub release](https://github.com/hanmahong5-arch/wireforge-core/releases).\n\n## Quick start (CLI from source)\n\n```bash\ncargo install --path crates/wf-cli\necho \"303230302000000000000000303030303030\" | wf parse -\n```\n\nOutput: a tree showing MTI, bitmap, and decoded fields. ISO 8583\nauto-sniffs across HybridAscii / FullAscii / FullBinary dialects; pass\n`--dialect <name>` to force one.\n\nAdd `-v` / `-vv` / `-vvv` for info / debug / trace logging on **stderr**\n(stdout stays machine-clean); at trace, the raw input buffer is hex-dumped.\n`RUST_LOG` overrides the level. Logs are local-only — no telemetry.\n\n## SR2026 address-compliance gate (CLI)\n\nCBPR+ SR2026 makes a structured debtor/creditor postal address (`TwnNm` +\n`Ctry` in dedicated `PstlAdr` fields) mandatory on **2026-11-14**. Scan your\noutbound message store before the deadline:\n\n```bash\nwf xform address-check outbox/             # scan a directory of *.xml\nwf xform address-check a.xml b.xml c.xml   # one or more explicit files\ncat msg.xml | wf xform address-check -     # one envelope from stdin\n```\n\nThe message type (pacs.008.001.08 / pacs.004.001.09 / pacs.003.001.08 /\npain.001.001.09) is auto-detected per file, and the process exits with a\ndiff-style code so the check drops straight into CI:\n\n- `0` — every input is compliant\n- `1` — ran cleanly, but at least one input is non-compliant\n- `2` — at least one input could not be checked (unreadable / unparseable /\n  unsupported message type)\n\nOne unreadable file does not abort the batch — it is reported and folded into\nthe exit code. A directory scan is **one level, `*.xml` only, sorted**\n(recursive scan is not yet built). This\nis a **structural presence DETECTOR** for the one cited SR2026 rule — **not** a\nfull CBPR+ validation and **not** a certification; all fixtures are SYNTHETIC.\n\n`--format text|json|csv` selects the output shape: `text` (default, human-\nreadable), `json` (machine-readable, carries a `schema_version` field for CI\npipelines), or `csv` (RFC-4180, one row per file/party, for spreadsheets and\ndata pipelines). Each per-party row also carries a `remediation` field —\nactionable fix guidance naming the missing structured field(s) — a DETECTOR\nhint, not an auto-fix.\n\n## Quick start (MCP, for AI agents)\n\n**Claude Desktop**: download\n[`wireforge.mcpb`](https://github.com/hanmahong5-arch/wireforge-core/releases/download/v0.1.0/wireforge.mcpb)\nand open it (Settings → Extensions) — the bundle carries macOS (Apple\nSilicon) and Windows binaries. The server is on the MCP Registry as\n`io.github.hanmahong5-arch/wireforge`.\n\n**Other stdio clients**: install the binary —\n\n```bash\ncargo install --path crates/wf-mcp\n```\n\n— then wire it into your MCP-aware client. For Claude Code, add\nto `~/.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"wireforge\": { \"command\": \"wf-mcp\" }\n  }\n}\n```\n\nThe agent can now call 13 tools:\n\n- `wf_parse_iso8583` — hex → structured field tree\n- `wf_build_iso8583` — `{mti, fields}` → hex\n- `wf_validate_iso8583` — structural validation\n- `wf_field_lookup` — field number → FieldDef\n- `wf_decode_mti` — 4-digit MTI → semantic parts\n- `wf_explain_message` — natural-language description (no LLM call)\n- `wf_roundtrip_check` — parse → build → byte-compare\n- `wf_parse_swift_mt` — SWIFT MT raw → structural block tree\n- `wf_ebcdic_decode` — EBCDIC-encoded hex bytes → decoded text\n- `wf_sm3` — bytes → SM3 (GB/T 32905) hash digest\n- `wf_mt_mx_truncation_diff` — pacs.008.001.08 ↔ MT103 field truncation/loss\n  **detector** across five roles (DETECTOR not converter; no\n  certification / conformance / equivalence claim)\n- `wf_mx_address_compliance` — check a pacs.008.001.08, pacs.004.001.09, pacs.003.001.08 or\n  pain.001.001.09 debtor/creditor postal address for the CBPR+ SR2026 structured-address\n  requirement (`TwnNm` + `Ctry` in dedicated fields, mandatory 2026-11-14); auto-detects the\n  message type. DETECTOR, not a full CBPR+ validation and not a certification\n- `wf_mx_address_scan` — batch variant of `wf_mx_address_compliance`: runs the same SR2026\n  structured-address presence check over one-or-more MX envelopes and returns a diff-style\n  gate summarizing the whole batch. DETECTOR, not a full CBPR+ validation and not a certification\n\nSee [`docs/mcp-integration.md`](docs/mcp-integration.md) for client\nsetup details, the field-payload convention, and validator\nlimitations.\n\n## Quick start (`.wf` flat-file)\n\n```bash\ncat crates/wf-format/examples/iso8583-auth.wf\n```\n\n```text\nmeta {\n  name: Auth Request 0200\n  type: iso8583\n}\niso8583 {\n  mti: 0200\n  field 2: 4242424242424242\n  field 4: 000000010000\n}\n```\n\nParse it with the `wf-format` crate's `parse(&str) -> WfFile`. The\ngrammar is line-oriented + brace-grouped + additive: unrecognised\nblocks land in `Body::Raw` so newer files never break older parsers.\n\n## Quick start (SM3)\n\n```rust\nuse wf_sm::{sm3, sm3_hex};\nlet digest = sm3(b\"abc\");           // [u8; 32]\nlet hex    = sm3_hex(b\"abc\");        // \"66c7f0f4…8f4ba8e0\"\n```\n\nBacked by RustCrypto [`sm3`](https://docs.rs/sm3) (the `Digest` trait);\nthe streaming `Sm3` hasher keeps real 64-byte block state, so hashing a\nlarge WAL is O(1) memory. Algorithm-selection rationale, the 2026-05-29\nswap from `smcrypto`, and the GB/T 32905-2016 test vectors live in\n[`docs/sm-crypto-research-2026-05.md`](docs/sm-crypto-research-2026-05.md).\n\n## Status\n\nPre-1.0. ISO 8583-1987 parser / builder are exact inverses for every\nsupported dialect; field 1..=104 plus 128 have concrete spec\ndefinitions, and fields 105..=127 are treated as opaque binary\nenvelopes. A runtime-loadable `FieldSpec` (TOML, `spec-load` feature)\noverrides the built-in table for national / private dialects without a\nrecompile. SWIFT MT structural layer is complete; semantic field\ndecoders cover three MT103 anchor tags (20 / 32A / 50K) with the\n`MtFieldDecoder` trait as the extension point. EBCDIC CP037 / CP500\nsingle-byte codec is implemented (tables vendored under the Unicode\nLicense, see `NOTICE`); DBCS host pages are deferred. `wf-sm` exposes\nSM3 hash, SM4 (ECB / CBC + bounded streaming), and SM2 signature —\nfunctional only, with **no** 密评 / GB/T 39786 compliance claim.\n\n## Scope & honesty\n\nRead this before trusting any number.\n\n- **No real production samples yet.** Correctness is grounded on synthetic and\n  standard/specification test vectors only (labelled `SYNTHETIC` in-source) plus\n  a property-based round-trip fuzz suite. Any accuracy statement is `⏳ pending`\n  real-sample validation. The Phase 0 exit gate (≥ 5 real ISO 8583 hex samples)\n  is **unmet** — contributions welcome via `tools/sample-sanitize/`.\n- **`wf-xform` is a truncation DETECTOR, not a converter.** It compares an MT103\n  and a pacs.008.001.08 a caller already holds and reports per-role field loss\n  against cited maximum lengths. It performs **no** conversion and makes **no**\n  certification, conformance, or equivalence claim.\n- **`wf-sm` (国密) is functional only** — no 密评 / GB/T 39786 / OSCCA\n  certification claim; SM2 rests on an unaudited upstream. Suitable for\n  development against CN rails, not as a certified cryptographic product.\n- **`wf-mx` wraps a third-party upstream** (`mx-message` 3.1.4) that is currently\n  frozen. The facade isolates the dependency; owning MX parsing is a future option.\n\nA grounded, source-cited go-to-market and next-steps plan lives in\n[`docs/strategy/next-steps-2026-06.md`](docs/strategy/next-steps-2026-06.md).\n\n## Building\n\n```bash\ncargo build --workspace\ncargo test --workspace --all-targets\ncargo clippy --workspace --all-targets -- -D warnings\ncargo fmt --all -- --check\n```\n\nThe workspace pins clippy `unwrap_used` / `expect_used` / `panic` to\n`deny`. The `wf-mcp` crate relaxes those three lints locally because\n`rmcp`'s procedural macro generates code we don't control;\nhand-written handlers in that crate still funnel errors through\n`Result<_, _>`.\n\n## License\n\nApache-2.0. See `LICENSE`.\n",
  "bytes": 13829,
  "sha": "e592cfe9a630d34a67bbdbb3fe5899e8dbf68cd6533d5d5128c45aefca7ba6f9",
  "repo_slug": "hanmahong5-arch/wireforge-core",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hanmahong5_arch_wireforge_24de3330/readme"
}