Metadata-Version: 2.4
Name: metricbraid-connect
Version: 0.1.1
Summary: Pair Garmin with MetricBraid while keeping credentials on your computer.
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: garminconnect==0.3.6
Requires-Dist: httpx==0.28.1
Description-Content-Type: text/markdown

# MetricBraid Connect

`metricbraid-connect` pairs a Garmin account with MetricBraid while keeping the
Garmin email, password, and MFA response on the user's computer. Only the
validated Garmin token payload is sent to the configured MetricBraid pairing
endpoint.

> **Pre-alpha:** package availability does not activate a pairing endpoint. A
> real endpoint and interactive Garmin flow require separate operational
> approval.

## Requirements

- Python 3.12 or later
- A POSIX platform with effective-owner checks and no-follow file opening
- A pairing code issued by an activated MetricBraid dashboard
- An explicitly approved HTTPS pairing endpoint

Windows fails closed because equivalent ACL behavior has not been verified.

## Local package check

From the MetricBraid repository:

```sh
uvx --from ./cli metricbraid-connect --help
```

After a separately approved package publication, the intended command is:

```sh
uvx metricbraid-connect garmin --code 123-456
```

The six-digit code must come from the dashboard. Do not place it in the
endpoint URL, logs, or persistent configuration.

## Pairing endpoint

The executable reads only `METRICBRAID_GARMIN_PAIRING_URL`. The value must be
an ASCII HTTPS URL whose path is exactly
`/api/v1/providers/garmin/pair`, with no credentials, query, or fragment.
There is intentionally no default hostname.

For example, an operator can provide a reviewed endpoint through the process
environment:

```sh
export METRICBRAID_GARMIN_PAIRING_URL="https://api.example.test/api/v1/providers/garmin/pair"
```

`api.example.test` is a reserved placeholder, not an active MetricBraid
service. Missing, empty, malformed, insecure, or unsupported configuration
exits before credential prompts, Garmin client construction, token-file work,
or HTTP transport.

## Security behavior

- Garmin credentials and MFA stay on the local machine.
- Temporary token storage must be an owner-only `0700` directory containing an
  owner-only `0600` regular token file.
- Symlinks, permissive modes, invalid token shapes, redirects, unexpected
  responses, and unsafe platform semantics fail closed.
- Terminal errors are fixed and do not include credentials, tokens, pairing
  codes, endpoint details, provider exceptions, or response bodies.

MetricBraid is not a medical device. See the repository
[license](LICENSE).
