certmate-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{certmate_cli-0.1.2 → certmate_cli-0.1.4}/.gitignore

@@ -64,9 +64,11 @@ Thumbs.db
 # Logs
 *.log
 
-# Backup files
-*_old.*
-*_backup.*
+# Backup files. Anchored to the repository root: unanchored, `*_backup.*`
+# also matched tests/test_backup.py, which therefore existed on disk for
+# months without ever being committed or run in CI.
+/*_old.*
+/*_backup.*
 
 # Planning and development documents
 NEXT_FEATURES.md
@@ -88,12 +90,15 @@ app.py.backup
 .claude/
 test_screenshots/
 
-# Test files with sensitive data
-test_real_cert_*.py
-test_api_*.py
-test_certificate_creation_*.py
-real_world_test_*.py
-integration_test_*.py
+# Ad-hoc test scripts with real credentials, written at the repository root.
+# Anchored (leading /) on purpose: unanchored, `test_api_*.py` swallowed
+# tests/test_api_key_expiry_and_masking.py — a committed-looking test file
+# that git silently refused to track, so it protected nothing in CI.
+/test_real_cert_*.py
+/test_api_*.py
+/test_certificate_creation_*.py
+/real_world_test_*.py
+/integration_test_*.py
 github_response.md
 
 # local

{certmate_cli-0.1.2 → certmate_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: certmate-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: CertMate command-line interface — the SSL certificate lifecycle from your terminal
 Project-URL: Homepage, https://github.com/fabriziosalmi/certmate
 Project-URL: Source, https://github.com/fabriziosalmi/certmate/tree/main/clients/certmate-cli
@@ -23,7 +23,7 @@ Classifier: Topic :: Security
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: Utilities
 Requires-Python: >=3.9
-Requires-Dist: certmate-sdk>=0.1.2
+Requires-Dist: certmate-sdk>=0.1.3
 Requires-Dist: rich>=13
 Requires-Dist: typer>=0.9
 Description-Content-Type: text/markdown
@@ -46,6 +46,30 @@ certmate cert create app.example.com --dns cloudflare --dry-run
 certmate audit verify
 ```
 
+## Pulling certificates onto a host
+
+`cert download` fetches one file at a time, so a target server can pull
+exactly what it deploys instead of the certificate manager pushing to it:
+
+```bash
+certmate cert download app.example.com --file fullchain -o /etc/ssl/certs/app.pem
+certmate cert download app.example.com --file privkey   -o /etc/ssl/private/app.key
+```
+
+Files are created **0600**, with the mode set at creation rather than after
+the write, so the key is never briefly world-readable.
+
+This is worth preferring over pushing when the manager would otherwise need
+credentials on every target host. Give each host an API key scoped to its own
+domain and run the pull on a timer: the host needs no inbound access, and the
+manager holds no credentials for it. `cert`, `chain` and `fullchain` are
+readable by a viewer-role key; `privkey`, `combined` and `pfx` need operator.
+
+`--file privkey --key-format pkcs1` serves the legacy
+`BEGIN RSA PRIVATE KEY` form for stacks that reject certbot's PKCS#8.
+`--bundle zip` or `--bundle json` fetch the whole certificate instead, and
+`-o -` writes to stdout.
+
 Connection comes from `--url`/`--token` or `CERTMATE_URL`/`CERTMATE_TOKEN`.
 Prefer the `CERTMATE_TOKEN` environment variable over `--token`: command-line
 arguments are visible to other local processes (`ps`) and shell history.

certmate_cli-0.1.4/README.md

@@ -0,0 +1,45 @@
+# certmate-cli
+
+The [CertMate](https://github.com/fabriziosalmi/certmate) SSL certificate
+lifecycle from your terminal — built on `certmate-sdk`.
+
+```bash
+pip install certmate-cli
+export CERTMATE_URL=http://localhost:8000
+export CERTMATE_TOKEN=...
+
+certmate cert create app.example.com --dns cloudflare --wait
+certmate cert ls
+certmate cert info app.example.com
+certmate cert renew app.example.com --force
+certmate cert create app.example.com --dns cloudflare --dry-run
+certmate audit verify
+```
+
+## Pulling certificates onto a host
+
+`cert download` fetches one file at a time, so a target server can pull
+exactly what it deploys instead of the certificate manager pushing to it:
+
+```bash
+certmate cert download app.example.com --file fullchain -o /etc/ssl/certs/app.pem
+certmate cert download app.example.com --file privkey   -o /etc/ssl/private/app.key
+```
+
+Files are created **0600**, with the mode set at creation rather than after
+the write, so the key is never briefly world-readable.
+
+This is worth preferring over pushing when the manager would otherwise need
+credentials on every target host. Give each host an API key scoped to its own
+domain and run the pull on a timer: the host needs no inbound access, and the
+manager holds no credentials for it. `cert`, `chain` and `fullchain` are
+readable by a viewer-role key; `privkey`, `combined` and `pfx` need operator.
+
+`--file privkey --key-format pkcs1` serves the legacy
+`BEGIN RSA PRIVATE KEY` form for stacks that reject certbot's PKCS#8.
+`--bundle zip` or `--bundle json` fetch the whole certificate instead, and
+`-o -` writes to stdout.
+
+Connection comes from `--url`/`--token` or `CERTMATE_URL`/`CERTMATE_TOKEN`.
+Prefer the `CERTMATE_TOKEN` environment variable over `--token`: command-line
+arguments are visible to other local processes (`ps`) and shell history.

{certmate_cli-0.1.2 → certmate_cli-0.1.4}/certmate_cli/__init__.py

@@ -1,2 +1,2 @@
 """certmate-cli — the CertMate SSL lifecycle from your terminal (built on certmate-sdk)."""
-__version__ = "0.1.2"
+__version__ = "0.1.4"

{certmate_cli-0.1.2 → certmate_cli-0.1.4}/certmate_cli/main.py

@@ -9,8 +9,12 @@ Connection comes from --url/--token or CERTMATE_URL/CERTMATE_TOKEN.
 """
 from __future__ import annotations
 
+import json
+import os
 import re
+import stat
 import sys
+from pathlib import Path
 from typing import List, Optional
 
 import typer
@@ -35,6 +39,24 @@ app.add_typer(deploy_app, name="deploy")
 out = Console()
 err = Console(stderr=True)
 
+
+def _version_callback(value: bool) -> None:
+    """`--version` prints the version and exits 0, before anything else runs.
+
+    It has to be eager: the flag must work with no server configured, no
+    token, and no network — reporting which build you have is the first thing
+    anyone does when something is wrong.
+    """
+    if value:
+        from certmate_cli import __version__
+
+        # Plain print, not `out.print`: a version string gets piped and
+        # compared, so it must not pick up Rich's wrapping or markup.
+        print(__version__)
+        raise typer.Exit(0)
+
+
+
 # A lax hostname/wildcard check for the client-side --dry-run preflight; the
 # server is the real authority, this just catches obvious typos before we
 # spend an API call.
@@ -67,6 +89,13 @@ def _main(
                                         help="API bearer token. Prefer the CERTMATE_TOKEN "
                                              "environment variable: --token is visible to other "
                                              "local processes (ps) and shell history."),
+    # Lives on THIS callback rather than a second one: Typer keeps only one
+    # root callback, so a separate `@app.callback()` silently replaces this
+    # whole function — including the --token warning above.
+    version: Optional[bool] = typer.Option(None, "--version", "-V",
+                                           callback=_version_callback,
+                                           is_eager=True,
+                                           help="Show the certmate-cli version and exit."),
 ):
     # Kept for compatibility, but discourage --token interactively: argv is
     # world-readable via ps and lands in shell history. Warn only on a TTY so
@@ -264,6 +293,91 @@ def cert_rm(ctx: typer.Context, domain: str,
     out.print(f"[green]deleted[/] {domain}.")
 
 
+_FILE_DEFAULT_NAME = {
+    "cert": "cert.pem",
+    "chain": "chain.pem",
+    "fullchain": "fullchain.pem",
+    "privkey": "privkey.pem",
+    "combined": "combined.pem",
+    "pfx": "cert.pfx",
+}
+# Anything that can carry key material is written owner-only. The public
+# files get the same treatment: a deploy script that later relaxes them is
+# an explicit act, whereas a private key written 0644 is a silent one.
+_DOWNLOAD_MODE = 0o600
+
+
+@cert_app.command("download")
+def cert_download(
+    ctx: typer.Context,
+    domain: str,
+    file: str = typer.Option(
+        "fullchain", "--file", "-f",
+        help="Which file: cert, chain, fullchain, privkey, combined, pfx. "
+             "Use --bundle for a whole-certificate archive instead."),
+    output: Optional[str] = typer.Option(
+        None, "--output", "-o",
+        help="Where to write it. Defaults to the file's usual name in the "
+             "current directory; '-' writes to stdout."),
+    key_format: Optional[str] = typer.Option(
+        None, "--key-format",
+        help="pkcs1 or pkcs8, for --file privkey. certbot writes pkcs8; "
+             "pkcs1 is the legacy 'BEGIN RSA PRIVATE KEY' form."),
+    bundle: Optional[str] = typer.Option(
+        None, "--bundle",
+        help="Download a bundle instead of a single file: zip or json."),
+):
+    """Download a certificate file, so a host can pull what it needs.
+
+    Pulling beats pushing when the certificate manager would otherwise need
+    credentials on every target host: give each host an API key scoped to its
+    own domain and let it fetch on a timer.
+
+        certmate cert download example.com --file fullchain -o /etc/ssl/certs/x.pem
+        certmate cert download example.com --file privkey   -o /etc/ssl/private/x.key
+    """
+    # Every one of these is checked before a request goes out: being told
+    # "invalid key_format" by the server after a round trip is a worse error
+    # than being told here, and it costs an authenticated call to learn it.
+    if bundle is not None and bundle not in ("zip", "json"):
+        _die("--bundle must be zip or json")
+    if bundle and key_format:
+        _die("--key-format applies to --file privkey, not to a bundle")
+    if key_format is not None:
+        if key_format not in ("pkcs1", "pkcs8"):
+            _die(f"unknown --key-format {key_format!r}; use pkcs1 or pkcs8")
+        if not bundle and file != "privkey":
+            _die(f"--key-format applies to --file privkey, not to {file!r}")
+
+    if bundle:
+        data = _run(lambda: _client(ctx).download_certificate(domain, fmt=bundle))
+        default_name = f"{domain}.zip" if bundle == "zip" else f"{domain}.json"
+        payload = json.dumps(data, indent=2).encode() if bundle == "json" else data
+    else:
+        if file not in _FILE_DEFAULT_NAME:
+            _die(f"unknown --file {file!r}; use one of "
+                 f"{', '.join(sorted(_FILE_DEFAULT_NAME))}")
+        payload = _run(lambda: _client(ctx).download_certificate_file(
+            domain, file, key_format=key_format))
+        default_name = _FILE_DEFAULT_NAME[file]
+
+    if output == "-":
+        # Binary-safe: .pfx and .zip are not text.
+        sys.stdout.buffer.write(payload)
+        return
+
+    target = Path(output or default_name)
+    # Create with the restrictive mode rather than chmod-ing after: between
+    # an open() and a chmod() the key is readable by anyone on the box.
+    fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, _DOWNLOAD_MODE)
+    with os.fdopen(fd, "wb") as fh:
+        fh.write(payload)
+    # An existing file keeps its old mode through O_CREAT, so state what was
+    # actually written rather than claiming 0600 unconditionally.
+    mode = stat.S_IMODE(os.stat(target).st_mode)
+    out.print(f"[green]wrote[/] {target} ({len(payload)} bytes, mode {mode:04o})")
+
+
 @cert_app.command("reissue")
 def cert_reissue(ctx: typer.Context, domain: str,
                  san: Optional[str] = typer.Option(None, "--san", help="Comma-separated SAN domains.")):

{certmate_cli-0.1.2 → certmate_cli-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "certmate-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "CertMate command-line interface — the SSL certificate lifecycle from your terminal"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -33,7 +33,7 @@ classifiers = [
 # The SDK floor tracks the CLI release: 0.1.2 needs TransportError and the
 # renew/audit semantics introduced in certmate-sdk 0.1.2.
 dependencies = [
-    "certmate-sdk>=0.1.2",
+    "certmate-sdk>=0.1.3",
     "typer>=0.9",
     "rich>=13",
 ]

certmate_cli-0.1.2/README.md

@@ -1,21 +0,0 @@
-# certmate-cli
-
-The [CertMate](https://github.com/fabriziosalmi/certmate) SSL certificate
-lifecycle from your terminal — built on `certmate-sdk`.
-
-```bash
-pip install certmate-cli
-export CERTMATE_URL=http://localhost:8000
-export CERTMATE_TOKEN=...
-
-certmate cert create app.example.com --dns cloudflare --wait
-certmate cert ls
-certmate cert info app.example.com
-certmate cert renew app.example.com --force
-certmate cert create app.example.com --dns cloudflare --dry-run
-certmate audit verify
-```
-
-Connection comes from `--url`/`--token` or `CERTMATE_URL`/`CERTMATE_TOKEN`.
-Prefer the `CERTMATE_TOKEN` environment variable over `--token`: command-line
-arguments are visible to other local processes (`ps`) and shell history.