{"id":51025466,"url":"https://github.com/openapi/htrust","last_synced_at":"2026-06-21T19:30:34.479Z","repository":{"id":365444978,"uuid":"1272107438","full_name":"openapi/htrust","owner":"openapi","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-17T10:19:54.000Z","size":23,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T12:06:45.741Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/openapi.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-17T09:46:05.000Z","updated_at":"2026-06-17T10:19:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/openapi/htrust","commit_stats":null,"previous_names":["openapi/htrust"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/openapi/htrust","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fhtrust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fhtrust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fhtrust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fhtrust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openapi","download_url":"https://codeload.github.com/openapi/htrust/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fhtrust/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34623906,"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-21T02:00:05.568Z","response_time":54,"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":[],"created_at":"2026-06-21T19:30:32.581Z","updated_at":"2026-06-21T19:30:34.466Z","avatar_url":"https://github.com/openapi.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# htrust\n\nOpen Source Trust for Humans.\n\n`htrust` is a Rust CLI for Linux sysadmins, shell scripts, and agentic tooling that need to check whether real-world information can be trusted before acting on it.\n\nThe interface is intentionally flat: one command per claim type, one positional value to check, a short status on stdout and a meaningful exit code.\n\n---\n\n## Table of contents\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Static validation first](#static-validation-first)\n- [Commands](#commands)\n  - [`htrust info`](#htrust-info)\n  - [`htrust mobile`](#htrust-mobile)\n  - [`htrust email`](#htrust-email)\n  - [`htrust ip`](#htrust-ip)\n  - [`htrust url`](#htrust-url)\n  - [Global flags](#global-flags)\n- [Endpoint mapping](#endpoint-mapping)\n- [Exit codes](#exit-codes)\n- [Output format](#output-format)\n- [Development](#development)\n- [Testing](#testing)\n- [Makefile targets](#makefile-targets)\n- [Project layout](#project-layout)\n\n---\n\n## Installation\n\n### Build from source\n\nYou need a working Rust toolchain (edition 2021 or newer) and `cargo`.\n\n```bash\ngit clone https://github.com/openapi/htrust.git\ncd htrust\ncargo build --release\n```\n\nThe binary is produced at:\n\n```text\ntarget/release/htrust\n```\n\n### Local install with Make\n\n```bash\nmake install\n```\n\nThis builds the release binary and copies it to `~/.local/bin/htrust`. Make sure `~/.local/bin` is in your `PATH`.\n\nTo install to a custom prefix:\n\n```bash\nmake install PREFIX=/usr/local\n```\n\nThe binary will be copied to `$PREFIX/bin/htrust`.\n\n---\n\n## Configuration\n\n`htrust` reads API tokens from the environment.\n\n| Variable | Required by | Description |\n|----------|-------------|-------------|\n| `OPENAPI_TOKEN` | production commands | Production token for `trust.openapi.com` |\n| `OPENAPI_SANDBOX_TOKEN` | `--sandbox` commands | Sandbox token for `test.trust.openapi.com` |\n\nSet them in your shell or in a `.env` file:\n\n```bash\nexport OPENAPI_TOKEN=your-production-token\nexport OPENAPI_SANDBOX_TOKEN=your-sandbox-token\n```\n\nA ready-to-edit example is provided in `.env.example`.\n\n---\n\n## Static validation first\n\n`htrust` never calls the remote trust API unless the input passes a local stack of static validators. Every command runs format, checksum and sanity checks before any network request is made.\n\nWhy? Because trust decisions should be cheap, fast and privacy-friendly. If an email is syntactically broken, a phone number is not E.164, an IP is not parseable or a URL has no valid scheme, the tool rejects it immediately without leaking the value to a third party and without consuming API quota.\n\n```bash\nhtrust email not-an-email\n# error: invalid email format: not-an-email\n```\n\nLocal validators currently cover:\n\n| Kind | Static checks |\n|------|---------------|\n| `mobile` | E.164 format (`+` followed by 2-15 digits) |\n| `email` | Basic RFC-like structure (`local@domain.tld`) |\n| `ip` | Valid IPv4 or IPv6 address |\n| `url` | Valid URL with `http` or `https` scheme |\n\nThis \"validate before you trust\" principle is a core design goal of htrust.\n\n---\n\n## Commands\n\n### `htrust info`\n\nPrints runtime configuration: sandbox mode, token status, and CLI version.\n\n```bash\nhtrust info\n```\n\nExample output:\n\n```text\nhtrust runtime\n  sandbox: false\n  token env: OPENAPI_TOKEN (set)\n```\n\n`info` does **not** perform any API call.\n\n---\n\n### `htrust mobile`\n\nVerifies a mobile phone number.\n\n```bash\n# basic check — prints a short status and sets the exit code\nhtrust mobile +393331234567\n\n# advanced / detailed endpoint\nhtrust mobile +393331234567 --detail\n\n# full JSON response\nhtrust mobile +393331234567 --json\nhtrust mobile +393331234567 --full\n```\n\n| Argument | Description |\n|----------|-------------|\n| `VALUE` | Phone number with international prefix (e.g. `+393331234567`) |\n\n`--detail` selects the richer endpoint when the API exposes both a base and an advanced check. `--json` / `--full` print the full API response instead of the short status.\n\n---\n\n### `htrust email`\n\nVerifies an email address.\n\n```bash\nhtrust email info@example.com\nhtrust email info@example.com --detail\nhtrust email info@example.com --json\n```\n\n| Argument | Description |\n|----------|-------------|\n| `VALUE` | Email address to verify |\n\n---\n\n### `htrust ip`\n\nVerifies an IP address.\n\n```bash\nhtrust ip 8.8.8.8\nhtrust ip 8.8.8.8 --json\n```\n\n| Argument | Description |\n|----------|-------------|\n| `VALUE` | IPv4 or IPv6 address |\n\n`--detail` is accepted for interface consistency but the underlying endpoint is always the advanced one.\n\n---\n\n### `htrust url`\n\nVerifies a URL.\n\n```bash\nhtrust url https://example.com\nhtrust url https://example.com --json\n```\n\n| Argument | Description |\n|----------|-------------|\n| `VALUE` | Absolute URL to verify |\n\nLike `ip`, `--detail` is accepted but maps to the advanced endpoint.\n\n---\n\n### Global flags\n\n| Flag | Description |\n|------|-------------|\n| `--sandbox` | Use the sandbox environment (`test.trust.openapi.com`) and `OPENAPI_SANDBOX_TOKEN` |\n| `--detail` / `--details` | Use the richer endpoint where available (synonyms) |\n| `--json`, `--full` | Print the full API response as JSON |\n| `-h`, `--help` | Print help |\n| `-V`, `--version` | Print version |\n\nExamples:\n\n```bash\nhtrust --sandbox info\nhtrust --sandbox mobile +393331234567 --detail\nhtrust email info@example.com --json\n```\n\n---\n\n## Endpoint mapping\n\n| Command | Default endpoint | `--detail` endpoint |\n|---------|------------------|---------------------|\n| `mobile` | `mobile-start` | `mobile-advanced` |\n| `email` | `email-start` | `email-advanced` |\n| `ip` | `ip-advanced` | `ip-advanced` |\n| `url` | `url-advanced` | `url-advanced` |\n\nBase URL:\n\n- production: `https://trust.openapi.com`\n- sandbox: `https://test.trust.openapi.com`\n\nThe final URL is built as:\n\n```text\n{base_url}/{endpoint}/{value}\n```\n\nFor example:\n\n```text\nhttps://trust.openapi.com/mobile-start/+393331234567\n```\n\n---\n\n## Exit codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Trusted result (`valid` / `verified`) or neutral/no-op |\n| `1` | Distrusted result (`risky` / `invalid`), API error, or CLI usage error |\n| `2` | Missing required environment variable or empty token |\n\nThis makes htrust composable in shell scripts:\n\n```bash\nif htrust email info@example.com \u003e/dev/null; then\n  echo \"Email looks trustworthy\"\nelse\n  echo \"Email is risky or invalid\"\nfi\n```\n\n---\n\n## Output format\n\nBy default trust commands print a short status string to stdout:\n\n```bash\n$ htrust email info@example.com\nvalid\n```\n\nThe status mirrors the API's own assessment (e.g. `valid`, `risky`, `invalid`). Use `--json` or `--full` to see the complete API response:\n\n```bash\n$ htrust email info@example.com --json\n{\n  \"data\": { ... },\n  \"error\": null,\n  \"message\": \"\",\n  \"success\": true\n}\n```\n\nErrors are printed to stderr.\n\n---\n\n## Development\n\nBuild the debug binary:\n\n```bash\ncargo build\n```\n\nRun the CLI from the build directory:\n\n```bash\n./target/debug/htrust info\n```\n\nRun clippy and formatting checks:\n\n```bash\ncargo clippy --all-targets\ncargo fmt --check\n```\n\n---\n\n## Testing\n\n### Rust unit tests\n\nUnit tests live inside the source files under `src/` in `#[cfg(test)]` modules.\n\n```bash\ncargo test\n```\n\n### Bash smoke tests (`tests/`)\n\nThe `tests/` directory contains simple, practical smoke tests. Each command has its own file that shows the real command being executed:\n\n```text\ntests/\n├── run.sh            # runs all smoke tests\n├── test_info.sh      # htrust info in action\n├── test_mobile.sh    # htrust mobile in action\n├── test_email.sh     # htrust email in action\n├── test_ip.sh        # htrust ip in action\n└── test_url.sh       # htrust url in action\n```\n\nRun smoke tests:\n\n```bash\nmake test-smoke\n```\n\nor directly:\n\n```bash\n./tests/run.sh\n./tests/test_mobile.sh\n```\n\n### Negative / side-case asserts (`tests/asserts/`)\n\nThe `tests/asserts/` directory contains more formal assertions for error handling and edge cases:\n\n```text\ntests/asserts/\n├── run.sh                   # runs all assert tests\n├── lib.sh                   # tiny assert helpers\n├── test_info_asserts.sh     # info edge cases\n├── test_mobile_asserts.sh   # mobile error cases\n├── test_email_asserts.sh    # email error cases\n├── test_ip_asserts.sh       # ip error cases\n└── test_url_asserts.sh      # url error cases\n```\n\nRun assert tests:\n\n```bash\nmake test-asserts\n```\n\nor directly:\n\n```bash\n./tests/asserts/run.sh\n./tests/asserts/test_mobile_asserts.sh\n```\n\n### Run everything\n\n```bash\nmake test\n```\n\nThis runs `cargo test`, the smoke suite and the assert suite.\n\nTo run live tests against the sandbox:\n\n```bash\nexport OPENAPI_SANDBOX_TOKEN=your-sandbox-token\nmake test\n```\n\n---\n\n## Makefile targets\n\n| Target | Description |\n|--------|-------------|\n| `make` or `make build` | Build the release binary |\n| `make install` | Build and install to `~/.local/bin` (or `$PREFIX/bin`) |\n| `make test` | Run Rust unit tests, smoke tests and assert tests |\n| `make test-smoke` | Run only the practical smoke tests |\n| `make test-asserts` | Run only the negative/side-case assert tests |\n| `make clean` | Remove build artifacts |\n\n---\n\n## Project layout\n\n```text\n.\n├── Cargo.toml\n├── Makefile\n├── README.md\n├── .env.example\n├── src/\n│   ├── main.rs          # CLI entrypoint\n│   ├── cli.rs           # clap argument definitions\n│   ├── client.rs        # HTTP client and auth\n│   ├── config.rs        # Token loading\n│   └── commands/\n│       ├── info.rs      # htrust info\n│       ├── mod.rs       # command module exports\n│       └── trust.rs     # mobile/email/ip/url implementation\n└── tests/\n    ├── run.sh                 # smoke-test runner\n    ├── test_info.sh           # info command smoke test\n    ├── test_mobile.sh         # mobile command smoke test\n    ├── test_email.sh          # email command smoke test\n    ├── test_ip.sh             # ip command smoke test\n    ├── test_url.sh            # url command smoke test\n    └── asserts/\n        ├── run.sh             # assert-test runner\n        ├── lib.sh             # tiny assert helpers\n        ├── test_info_asserts.sh\n        ├── test_mobile_asserts.sh\n        ├── test_email_asserts.sh\n        ├── test_ip_asserts.sh\n        └── test_url_asserts.sh\n```\n\n---\n\n## Scope\n\nThis first cut wraps the current `trust.openapi.com` subset:\n\n- `mobile-start`\n- `mobile-advanced`\n- `email-start`\n- `email-advanced`\n- `ip-advanced`\n- `url-advanced`\n\nThe long-term shape can expand to commands like `htrust iban ...` or `htrust vat ...`, but those endpoints are not wired in this first baseline yet.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi%2Fhtrust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenapi%2Fhtrust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi%2Fhtrust/lists"}