htrust

Open Source Trust for Humans.

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.

The interface is intentionally flat: one command per claim type, one positional value to check, a short status on stdout and a meaningful exit code.

---

Table of contents

• Installation
• Configuration
• Static validation first
• Commands
  • htrust info
  • htrust mobile
  • htrust email
  • htrust ip
  • htrust url
  • Global flags
• Endpoint mapping
• Exit codes
• Output format
• Development
• Testing
• Makefile targets
• Project layout

---

Installation

Build from source

You need a working Rust toolchain (edition 2021 or newer) and cargo.

git clone https://github.com/openapi/htrust.git
cd htrust
cargo build --release

The binary is produced at:

target/release/htrust

Local install with Make

make install

This builds the release binary and copies it to ~/.local/bin/htrust. Make sure ~/.local/bin is in your PATH.

To install to a custom prefix:

make install PREFIX=/usr/local

The binary will be copied to $PREFIX/bin/htrust.

---

Configuration

htrust reads API tokens from the environment.

Variable	Required by	Description
OPENAPI_TOKEN	production commands	Production token for trust.openapi.com
OPENAPI_SANDBOX_TOKEN	--sandbox commands	Sandbox token for test.trust.openapi.com

Set them in your shell or in a .env file:

export OPENAPI_TOKEN=your-production-token
export OPENAPI_SANDBOX_TOKEN=your-sandbox-token

A ready-to-edit example is provided in .env.example.

---

Static validation first

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.

Why? 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.

htrust email not-an-email
# error: invalid email format: not-an-email

Local validators currently cover:

Kind	Static checks
mobile	E.164 format (+ followed by 2-15 digits)
email	Basic RFC-like structure (local@domain.tld)
ip	Valid IPv4 or IPv6 address
url	Valid URL with http or https scheme

This "validate before you trust" principle is a core design goal of htrust.

---

Commands

htrust info

Prints runtime configuration: sandbox mode, token status, and CLI version.

htrust info

Example output:

htrust runtime
  sandbox: false
  token env: OPENAPI_TOKEN (set)

info does not perform any API call.

---

htrust mobile

Verifies a mobile phone number.

# basic check — prints a short status and sets the exit code
htrust mobile +393331234567

# advanced / detailed endpoint
htrust mobile +393331234567 --detail

# full JSON response
htrust mobile +393331234567 --json
htrust mobile +393331234567 --full

Argument	Description
VALUE	Phone number with international prefix (e.g. +393331234567)

--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.

---

htrust email

Verifies an email address.

htrust email info@example.com
htrust email info@example.com --detail
htrust email info@example.com --json

Argument	Description
VALUE	Email address to verify

---

htrust ip

Verifies an IP address.

htrust ip 8.8.8.8
htrust ip 8.8.8.8 --json

Argument	Description
VALUE	IPv4 or IPv6 address

--detail is accepted for interface consistency but the underlying endpoint is always the advanced one.

---

htrust url

Verifies a URL.

htrust url https://example.com
htrust url https://example.com --json

Argument	Description
VALUE	Absolute URL to verify

Like ip, --detail is accepted but maps to the advanced endpoint.

---

Global flags

Flag	Description
--sandbox	Use the sandbox environment (test.trust.openapi.com) and OPENAPI_SANDBOX_TOKEN
--detail / --details	Use the richer endpoint where available (synonyms)
--json, --full	Print the full API response as JSON
-h, --help	Print help
-V, --version	Print version

Examples:

htrust --sandbox info
htrust --sandbox mobile +393331234567 --detail
htrust email info@example.com --json

---

Endpoint mapping

Command	Default endpoint	--detail endpoint
mobile	mobile-start	mobile-advanced
email	email-start	email-advanced
ip	ip-advanced	ip-advanced
url	url-advanced	url-advanced

Base URL:

• production: https://trust.openapi.com
• sandbox: https://test.trust.openapi.com

The final URL is built as:

{base_url}/{endpoint}/{value}

For example:

https://trust.openapi.com/mobile-start/+393331234567

---

Exit codes

Code	Meaning
0	Trusted result (valid / verified) or neutral/no-op
1	Distrusted result (risky / invalid), API error, or CLI usage error
2	Missing required environment variable or empty token

This makes htrust composable in shell scripts:

if htrust email info@example.com >/dev/null; then
  echo "Email looks trustworthy"
else
  echo "Email is risky or invalid"
fi

---

Output format

By default trust commands print a short status string to stdout:

$ htrust email info@example.com
valid

The status mirrors the API's own assessment (e.g. valid, risky, invalid). Use --json or --full to see the complete API response:

$ htrust email info@example.com --json
{
  "data": { ... },
  "error": null,
  "message": "",
  "success": true
}

Errors are printed to stderr.

---

Development

Build the debug binary:

cargo build

Run the CLI from the build directory:

./target/debug/htrust info

Run clippy and formatting checks:

cargo clippy --all-targets
cargo fmt --check

---

Testing

Rust unit tests

Unit tests live inside the source files under src/ in #[cfg(test)] modules.

cargo test

Bash smoke tests (tests/)

The tests/ directory contains simple, practical smoke tests. Each command has its own file that shows the real command being executed:

tests/
├── run.sh            # runs all smoke tests
├── test_info.sh      # htrust info in action
├── test_mobile.sh    # htrust mobile in action
├── test_email.sh     # htrust email in action
├── test_ip.sh        # htrust ip in action
└── test_url.sh       # htrust url in action

Run smoke tests:

make test-smoke

or directly:

./tests/run.sh
./tests/test_mobile.sh

Negative / side-case asserts (tests/asserts/)

The tests/asserts/ directory contains more formal assertions for error handling and edge cases:

tests/asserts/
├── run.sh                   # runs all assert tests
├── lib.sh                   # tiny assert helpers
├── test_info_asserts.sh     # info edge cases
├── test_mobile_asserts.sh   # mobile error cases
├── test_email_asserts.sh    # email error cases
├── test_ip_asserts.sh       # ip error cases
└── test_url_asserts.sh      # url error cases

Run assert tests:

make test-asserts

or directly:

./tests/asserts/run.sh
./tests/asserts/test_mobile_asserts.sh

Run everything

make test

This runs cargo test, the smoke suite and the assert suite.

To run live tests against the sandbox:

export OPENAPI_SANDBOX_TOKEN=your-sandbox-token
make test

---

Makefile targets

Target	Description
make or make build	Build the release binary
make install	Build and install to ~/.local/bin (or $PREFIX/bin)
make test	Run Rust unit tests, smoke tests and assert tests
make test-smoke	Run only the practical smoke tests
make test-asserts	Run only the negative/side-case assert tests
make clean	Remove build artifacts

---

Project layout

.
├── Cargo.toml
├── Makefile
├── README.md
├── .env.example
├── src/
│   ├── main.rs          # CLI entrypoint
│   ├── cli.rs           # clap argument definitions
│   ├── client.rs        # HTTP client and auth
│   ├── config.rs        # Token loading
│   └── commands/
│       ├── info.rs      # htrust info
│       ├── mod.rs       # command module exports
│       └── trust.rs     # mobile/email/ip/url implementation
└── tests/
    ├── run.sh                 # smoke-test runner
    ├── test_info.sh           # info command smoke test
    ├── test_mobile.sh         # mobile command smoke test
    ├── test_email.sh          # email command smoke test
    ├── test_ip.sh             # ip command smoke test
    ├── test_url.sh            # url command smoke test
    └── asserts/
        ├── run.sh             # assert-test runner
        ├── lib.sh             # tiny assert helpers
        ├── test_info_asserts.sh
        ├── test_mobile_asserts.sh
        ├── test_email_asserts.sh
        ├── test_ip_asserts.sh
        └── test_url_asserts.sh

---

Scope

This first cut wraps the current trust.openapi.com subset:

• mobile-start
• mobile-advanced
• email-start
• email-advanced
• ip-advanced
• url-advanced

The long-term shape can expand to commands like htrust iban ... or htrust vat ..., but those endpoints are not wired in this first baseline yet.