{"id":50491199,"url":"https://github.com/crime-trix/metastr-cpp","last_synced_at":"2026-06-02T03:00:37.533Z","repository":{"id":361958283,"uuid":"1256623276","full_name":"crime-trix/metastr-cpp","owner":"crime-trix","description":"C++20 compile-time string encoding with per-call-site blobs and scoped runtime decode","archived":false,"fork":false,"pushed_at":"2026-06-02T01:18:09.000Z","size":37,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T02:21:39.318Z","etag":null,"topics":["compile-time","cpp","cpp20","header-only","reverse-engineering","string-obfuscation","windows"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crime-trix.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-02T00:29:32.000Z","updated_at":"2026-06-02T01:18:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/crime-trix/metastr-cpp","commit_stats":null,"previous_names":["crime-trix/metastr-cpp"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/crime-trix/metastr-cpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crime-trix%2Fmetastr-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crime-trix%2Fmetastr-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crime-trix%2Fmetastr-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crime-trix%2Fmetastr-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crime-trix","download_url":"https://codeload.github.com/crime-trix/metastr-cpp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crime-trix%2Fmetastr-cpp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33803734,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compile-time","cpp","cpp20","header-only","reverse-engineering","string-obfuscation","windows"],"created_at":"2026-06-02T03:00:36.853Z","updated_at":"2026-06-02T03:00:37.522Z","avatar_url":"https://github.com/crime-trix.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# metastr-cpp\n\n`metastr-cpp` is a C++20 header-only library for compile-time string encoding and scoped runtime decode.\n\n[![ci](https://github.com/crime-trix/metastr-cpp/actions/workflows/ci.yml/badge.svg)](https://github.com/crime-trix/metastr-cpp/actions/workflows/ci.yml)\n\nThe library is meant for reducing obvious string exposure in compiled binaries. It is not a cryptographic storage format and it does not claim to protect strings after they are decoded at runtime. Use `metacrypt-cpp` or another authenticated encryption scheme for data that needs real confidentiality and integrity.\n\n## Features\n\n- `consteval` literal encoding;\n- stream and automaton-backed encoding modes;\n- per-call-site seed material from file, line and counter;\n- per-build key material generated by CMake and mixed into seed/stream generation;\n- no fixed maximum string length;\n- support for `char`, `wchar_t`, `char8_t`, `char16_t` and `char32_t`;\n- move-only decoded buffers that wipe storage on destruction;\n- scoped callback decode with `with_decoded`;\n- manual decode into caller-provided buffers;\n- non-zero mask bytes to avoid unchanged plaintext bytes caused by zero keystream bytes;\n- encoded blob metadata: seed, size, byte size, checksum and format version;\n- CMake target, install rules, examples and CI-tested test coverage;\n- no platform headers pulled into user translation units.\n\n## Quick Start\n\n```cpp\n#include \u003cmetastr/metastr.hpp\u003e\n\n#include \u003ccstdio\u003e\n\nint main()\n{\n    auto text = METASTR(\"compile-time encoded string\");\n    std::puts(text.c_str());\n}\n```\n\nWide and UTF literals use dedicated macros:\n\n```cpp\nauto wide = METASTR_W(L\"wide string\");\nauto utf8 = METASTR_U8(u8\"utf8 string\");\nauto utf16 = METASTR_U16(u\"utf16 string\");\nauto utf32 = METASTR_U32(U\"utf32 string\");\n```\n\nFor a stateful finite-automaton transform, use the `AUTO` macros:\n\n```cpp\nauto text = METASTR_AUTO(\"encoded through a state machine\");\nauto wide = METASTR_AUTO_W(L\"wide state machine string\");\n```\n\n## Application Strings\n\nTypical application use is intentionally small:\n\n```cpp\n#include \u003cmetastr/metastr.hpp\u003e\n\n#include \u003cstring_view\u003e\n\nbool login(std::string_view user, std::string_view password)\n{\n    const auto expected_user = METASTR(\"admin\");\n    const auto expected_password = METASTR_AUTO(\"change-me\");\n\n    return user == expected_user.view() \u0026\u0026 password == expected_password.view();\n}\n```\n\nUse `METASTR` for the default compact transform. Use `METASTR_AUTO` when you want a stateful transform with per-character automaton state. Both are compile-time encoders and both decode only when the expression is evaluated.\n\n## Scoped Decode\n\nUse `with_decoded` when the plaintext should live only for the duration of a call:\n\n```cpp\nconstexpr auto label = metastr::make_blob\u003c0x1234fedc98760011ull\u003e(\"scoped decode\");\n\nlabel.with_decoded([](std::string_view text) {\n    std::puts(text.data());\n});\n```\n\nThe callback receives a `std::basic_string_view`. Do not store that view after the callback returns.\n\n## Manual Buffers\n\nFor code that already owns storage, decode directly into a caller-provided span:\n\n```cpp\nconstexpr auto blob = metastr::make_blob\u003c0xdecafbad10002000ull\u003e(\"manual buffer\");\n\nstd::array\u003cchar, blob.storage_size()\u003e output{};\nif (blob.decode_into(std::span\u003cchar\u003e(output.data(), output.size()))) {\n    std::puts(output.data());\n}\n\nmetastr::secure_zero(std::span\u003cchar\u003e(output.data(), output.size()));\n```\n\n## API Notes\n\n`METASTR(...)` is the convenient macro for normal use. It returns a move-only `decoded_string`.\n\n`make_blob\u003cSeed\u003e(literal)` creates an encoded compile-time blob. This is useful when a stable seed is needed for tests, examples, or generated code.\n\n`decoded_string` owns plaintext storage and wipes that storage when destroyed or reassigned.\n\n`basic_blob::decode()` returns a `decoded_string`.\n\n`basic_blob::decode_into(span)` writes decoded text plus the null terminator into an existing buffer.\n\n`basic_blob::with_decoded(fn)` decodes, calls `fn(view)`, then wipes the temporary buffer when the call finishes.\n\n## Security Model\n\nThis library protects against simple static string scans and low-effort extraction from binary data. It does not protect against:\n\n- a debugger attached while the string is decoded;\n- runtime memory inspection;\n- tracing or emulating the decode routine;\n- an attacker who can execute the binary and observe behavior;\n- secrets that should never be shipped to the client.\n\nTreat this as string hiding, not cryptography.\n\nCopying a decoded view into `std::string` or another long-lived buffer creates a copy that `metastr-cpp` cannot wipe. Prefer `with_decoded` for short scoped use.\n\n## Build\n\n```sh\ncmake -S . -B build -DMETASTR_BUILD_EXAMPLES=ON -DMETASTR_BUILD_TESTS=ON\ncmake --build build --config Release\nctest --test-dir build -C Release --output-on-failure\n```\n\nThe CMake build generates `metastr/metastr_build_config.hpp` with per-build key material. If the public header is used without that generated file, the library falls back to a deterministic key and emits a compile-time warning. The fallback keeps include-only use working, but separate builds become easier to correlate.\n\n## Size Benchmark\n\nThe repository includes a small size benchmark with 40 identical string call-sites:\n\n```powershell\n./tools/run_size_bench.ps1\n```\n\nIt builds three Release executables:\n\n- `baseline`: plain string literals;\n- `metastr_stream`: `METASTR`;\n- `metastr_auto`: `METASTR_AUTO`.\n\nThe script reports executable size, delta from baseline, plaintext hit count for `api.secret.endpoint`, and the runtime hash exit code.\nPlaintext hit count in the baseline can vary when the compiler/linker pools identical literals.\n\nOne MSVC `/O2 /GL /MT` run measured:\n\n| Program | Size | Delta | Plaintext hits |\n| --- | ---: | ---: | ---: |\n| baseline | 110.0 KB | - | 40 |\n| metastr_stream | 118.5 KB | +8.7 KB | 0 |\n| metastr_auto | 124.0 KB | +14.3 KB | 0 |\n\nExact numbers vary by compiler, CRT, linker options and optimization level.\n\n## Install\n\n```sh\ncmake --install build --config Release --prefix ./install\n```\n\nThen link the exported target:\n\n```cmake\nfind_package(metastr-cpp CONFIG REQUIRED)\ntarget_link_libraries(app PRIVATE metastr::metastr-cpp)\n```\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrime-trix%2Fmetastr-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrime-trix%2Fmetastr-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrime-trix%2Fmetastr-cpp/lists"}