Metadata-Version: 2.4
Name: brainsless-connect
Version: 1.0.0
Summary: Seals a repository's environment variables and hands them to Brainsless
Author: Brainsless
License-Expression: MIT
Project-URL: Homepage, https://brainsless.com
Keywords: brainsless,env,handover
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=42

# brainsless-connect

Seals the environment variables a repository needs in order to run, and hands only ciphertext to
Brainsless. The stack-agnostic twin of `npx @brainsless/connect`, for machines without Node. The
repository it reads can be any stack; only Python is needed to run the tool.

Run it from the root of the repo Brainsless read, with the URL the Brainsless screen rendered.

```
uvx brainsless-connect https://brainsless.com/api/staging/handover/blh_...
```

Without `uv`:

```
pipx run brainsless-connect <url>
```

With neither, using only the standard library. PEP 668 does not apply inside a venv, so this needs
no root and leaves nothing on the system path:

```
python3 -m venv /tmp/brainsless && /tmp/brainsless/bin/pip -q install brainsless-connect
/tmp/brainsless/bin/brainsless-connect <url>
```

Every one of these fetches the same immutable, version-pinned wheel from PyPI. Nothing is piped
into an interpreter, and nothing is installed permanently.

## Flags

| | |
|---|---|
| `--list` | print every variable name, not just the counts |
| `--yes` | send without a prompt |

With neither `--yes` nor a terminal, it prints what would be sent and sends nothing.

## What it reads

`.env`, `.env.local`, `.env.staging`, `.env.development`, `.env.test` for values; `.env.example`,
`.env.sample`, `.env.template` for names only. Four directories deep, skipping `node_modules`,
`.git`, build output and virtualenvs. A deeper directory wins over a shallower one, so in a
monorepo the service's own env is the operative one.

## What it refuses

Refused before anything is sealed, so the values never leave the machine:

- database, cache and queue addresses -- the sandbox makes its own
- live-mode payment keys
- `PORT`, `NODE_ENV`, `PATH` and the rest of the runtime the sandbox provides itself

## Security

- AES-256-GCM under a fresh data key, that key RSA-OAEP-SHA256 wrapped against the public key the
  handover serves. The handover token is the GCM AAD, so a payload cannot be replayed against a
  different handover.
- Crypto is [`cryptography`](https://pypi.org/project/cryptography), the audited Python binding to
  OpenSSL. Nothing is hand-rolled.
- Reads only. There is no write call in the tool.

## Development

```
python3 -m venv .venv && .venv/bin/pip -q install -e . && .venv/bin/python test_connect.py
```

## Publishing

Pure Python, no compiler.

```
uv build
uv publish
```
