Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/openapi/htrust


https://github.com/openapi/htrust

Last synced: 25 days ago
JSON representation

Awesome Lists containing this project

README 

          
# 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](#installation)

- [Configuration](#configuration)

- [Static validation first](#static-validation-first)

- [Commands](#commands)

  - [`htrust info`](#htrust-info)

  - [`htrust mobile`](#htrust-mobile)

  - [`htrust email`](#htrust-email)

  - [`htrust ip`](#htrust-ip)

  - [`htrust url`](#htrust-url)

  - [Global flags](#global-flags)

- [Endpoint mapping](#endpoint-mapping)

- [Exit codes](#exit-codes)

- [Output format](#output-format)

- [Development](#development)

- [Testing](#testing)

- [Makefile targets](#makefile-targets)

- [Project layout](#project-layout)



---



## Installation



### Build from source



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



```bash

git clone https://github.com/openapi/htrust.git

cd htrust

cargo build --release

```



The binary is produced at:



```text

target/release/htrust

```



### Local install with Make



```bash

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:



```bash

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:



```bash

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.



```bash

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.



```bash

htrust info

```



Example output:



```text

htrust runtime

  sandbox: false

  token env: OPENAPI_TOKEN (set)

```



`info` does **not** perform any API call.



---



### `htrust mobile`



Verifies a mobile phone number.



```bash

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



```bash

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.



```bash

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.



```bash

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:



```bash

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:



```text

{base_url}/{endpoint}/{value}

```



For example:



```text

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:



```bash

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:



```bash

$ 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:



```bash

$ htrust email info@example.com --json

{

  "data": { ... },

  "error": null,

  "message": "",

  "success": true

}

```



Errors are printed to stderr.



---



## Development



Build the debug binary:



```bash

cargo build

```



Run the CLI from the build directory:



```bash

./target/debug/htrust info

```



Run clippy and formatting checks:



```bash

cargo clippy --all-targets

cargo fmt --check

```



---



## Testing



### Rust unit tests



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



```bash

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:



```text

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:



```bash

make test-smoke

```



or directly:



```bash

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



```text

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:



```bash

make test-asserts

```



or directly:



```bash

./tests/asserts/run.sh

./tests/asserts/test_mobile_asserts.sh

```



### Run everything



```bash

make test

```



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



To run live tests against the sandbox:



```bash

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



```text

.

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