Metadata-Version: 2.4
Name: certbot-dns-yeil
Version: 3.1.0
Summary: yeil DNS Authenticator plugin for Certbot
Home-page: https://docs.yeil.app/dns
Author: yeil
License: MIT
Project-URL: Documentation, https://docs.yeil.app/dns
Keywords: certbot dns yeil acme letsencrypt dns-01 dns-authenticator
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Plugins
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certbot>=1.1.0
Requires-Dist: zope.interface
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# certbot-dns-yeil

yeil DNS Authenticator plugin for [Certbot](https://certbot.eff.org/).

Authenticates to the yeil public DNS API (`https://api.yeil.app/v1/dns`)
with a yeil **App key** (`yk_...`) sent as a Bearer token, then
adds/removes TXT records to satisfy ACME DNS-01 challenges. Works for any
yeil team with an App that has DNS record-write permission; the certbot
host just needs HTTPS reachability to `api.yeil.app`.

Wildcard certs require DNS-01, so this plugin (or another DNS
authenticator) is needed for `*.example.com`.

Full API docs: <https://docs.yeil.app/dns>.

## Installation

```sh
pip install certbot-dns-yeil
```

## Configuration

In your yeil team settings, open **Apps**, create an App, grant it DNS
**record-write** permission on the zone(s) you'll issue certs for, and
mint a key. Drop the key (`yk_...`) into a credentials INI:

```ini
dns_yeil_api_key = yk_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy
```

`chmod 600` it.

> Migrating from 2.x: the old `dns_yeil_email` / `dns_yeil_app_password`
> login was retired with personal app passwords. Replace those two lines
> with a single `dns_yeil_api_key`.

Optional override if you're testing against a non-production API base:

```ini
dns_yeil_base_url = https://api.staging.example/v1/dns
```

## Usage

```sh
certbot certonly \
  --authenticator dns-yeil \
  --dns-yeil-credentials /etc/letsencrypt/yeil.ini \
  -d smtp.yeil.org \
  --preferred-challenges dns
```

For wildcards:

```sh
certbot certonly \
  --authenticator dns-yeil \
  --dns-yeil-credentials /etc/letsencrypt/yeil.ini \
  -d yeil.org -d '*.yeil.org'
```

## How it works

The plugin sends the App key as a Bearer token on every request to
`https://api.yeil.app/v1/dns`. For each requested name it asks the API
which of the App's zones covers the FQDN (`GET /zones?suffix_of=<fqdn>`),
creates a TXT at `_acme-challenge.<rel>` (`POST /zones/{id}/records`),
waits for propagation, and on cleanup deletes the record by id
(`DELETE /zones/{id}/records/{recordId}`).

Revoking the App key (or disabling the App) in your team settings cuts
off access cleanly. The key only carries the DNS permissions you granted
the App, so scope it to record-write on just the zones you need.

## License

MIT. See [LICENSE](LICENSE).
