certmate-cli 0.1.1__tar.gz → 0.1.3__tar.gz

{certmate_cli-0.1.1 → certmate_cli-0.1.3}/.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.1 → certmate_cli-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: certmate-cli
-Version: 0.1.1
+Version: 0.1.3
 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.1
+Requires-Dist: certmate-sdk>=0.1.3
 Requires-Dist: rich>=13
 Requires-Dist: typer>=0.9
 Description-Content-Type: text/markdown
@@ -46,4 +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.3/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.1 → certmate_cli-0.1.3}/certmate_cli/__init__.py

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

{certmate_cli-0.1.1 → certmate_cli-0.1.3}/certmate_cli/main.py

@@ -9,7 +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
@@ -41,14 +46,38 @@ _DOMAIN_RE = re.compile(
     r"^(\*\.)?([a-zA-Z0-9_](-*[a-zA-Z0-9_])*\.)+[a-zA-Z]{2,}$")
 
 
+def _token_on_argv() -> bool:
+    """True when the token was passed as a command-line flag (as opposed to
+    the CERTMATE_TOKEN environment variable). argv is what leaks to `ps`
+    output and shell history, so it is exactly the thing to check."""
+    return any(a == "--token" or a.startswith("--token=") for a in sys.argv)
+
+
+def _stderr_isatty() -> bool:
+    # Indirection so tests can stub interactivity; CliRunner's captured
+    # stderr never reports a TTY.
+    try:
+        return sys.stderr.isatty()
+    except Exception:
+        return False
+
+
 @app.callback()
 def _main(
     ctx: typer.Context,
     url: Optional[str] = typer.Option(None, "--url", envvar="CERTMATE_URL",
                                       help="CertMate base URL (default http://localhost:8000)."),
     token: Optional[str] = typer.Option(None, "--token", envvar="CERTMATE_TOKEN",
-                                        help="API bearer token."),
+                                        help="API bearer token. Prefer the CERTMATE_TOKEN "
+                                             "environment variable: --token is visible to other "
+                                             "local processes (ps) and shell history."),
 ):
+    # Kept for compatibility, but discourage --token interactively: argv is
+    # world-readable via ps and lands in shell history. Warn only on a TTY so
+    # scripts and pipelines stay quiet.
+    if token and _token_on_argv() and _stderr_isatty():
+        err.print("[yellow]warning[/]: --token is visible in ps output and shell history; "
+                  "prefer the CERTMATE_TOKEN environment variable.")
     ctx.obj = {"url": url, "token": token}
 
 
@@ -156,7 +185,9 @@ def cert_create(
                                  help="Validate inputs and preflight the DNS provider WITHOUT issuing."),
 ):
     """Issue a certificate (async; waits for completion by default)."""
-    sans: List[str] = [s.strip() for s in san.split(",")] if san else []
+    # Drop empties so a trailing comma ("a.com,b.com,") never produces a
+    # bogus "" SAN entry — mirrors cert_reissue.
+    sans: List[str] = [s.strip() for s in san.split(",") if s.strip()] if san else []
     client = _client(ctx)
 
     if dry_run:
@@ -213,10 +244,18 @@ def cert_renew(ctx: typer.Context, domain: str,
                force: bool = typer.Option(False, "--force", help="Force renewal even if not due.")):
     """Renew a certificate."""
     res = _run(lambda: _client(ctx).renew_certificate(domain, force=force))
-    if res.get("renewed") is False:
-        out.print(f"[yellow]not due[/] — {domain} was not yet due for renewal.")
-    else:
+    renewed = res.get("renewed")
+    # Only servers v2.21.1+ report the outcome (`renewed: true/false`). Green
+    # requires an explicit true — an absent key means the server did not say,
+    # and claiming success would be a lie.
+    if renewed is True:
         out.print(f"[green]renewed[/] {domain}.")
+    elif renewed is False:
+        msg = res.get("message") or f"{domain} was not yet due for renewal."
+        out.print(f"[yellow]not due[/] — {msg}")
+    else:
+        out.print(f"renew requested for [bold]{domain}[/] — server did not report "
+                  "the outcome (server v2.21.1+ reports it).")
 
 
 @cert_app.command("rm")
@@ -229,6 +268,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.")):
@@ -280,13 +404,22 @@ def audit_verify(ctx: typer.Context):
     ok = bool(res.get("ok"))
     reason = res.get("reason") or ""
     cp = res.get("checkpoint_verified")
-    # "chain file does not exist" / "empty chain" is a fresh instance that has
-    # not audited anything yet — benign, not a tamper alarm. Show it neutrally.
-    if not ok and any(k in reason.lower() for k in ("does not exist", "empty")):
-        out.print(f"audit chain: [dim]none yet[/] — {reason}")
+    # Benign ONLY when the server says state='absent' (200: fresh instance,
+    # nothing audited yet). The reason wording is NOT a signal: a chain file
+    # DELETED after signed checkpoints attested it existed comes back as a 409
+    # with the very same "chain file does not exist" text — that is tampering
+    # and must exit non-zero, like every other not-ok result.
+    if not ok and res.get("state") == "absent":
+        out.print(f"audit chain: [dim]none yet[/] — {reason or 'nothing audited yet'}")
         return
-    out.print(f"audit chain: {'[green]intact[/]' if ok else '[red]BROKEN[/]'}"
-              f"{(' — ' + reason) if reason else ''}")
+    detail = (
+        f" — {reason}"
+        if reason and not (ok and reason.lower() == "intact")
+        else ""
+    )
+    out.print(
+        f"audit chain: {'[green]intact[/]' if ok else '[red]BROKEN[/]'}{detail}"
+    )
     if cp is not None:
         out.print(f"  signed checkpoint: {'[green]verified[/]' if cp else '[dim]not cross-checked[/]'}"
                   f"{(' @ seq ' + str(res.get('checkpoint_seq'))) if res.get('checkpoint_seq') is not None else ''}")

{certmate_cli-0.1.1 → certmate_cli-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "certmate-cli"
-version = "0.1.1"
+version = "0.1.3"
 description = "CertMate command-line interface — the SSL certificate lifecycle from your terminal"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -30,8 +30,10 @@ classifiers = [
 ]
 # Built ON the SDK (never the reverse). typer for the command surface, rich
 # for tables/spinners. Still light — no server deps.
+# 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.1",
+    "certmate-sdk>=0.1.3",
     "typer>=0.9",
     "rich>=13",
 ]

certmate_cli-0.1.1/README.md

@@ -1,19 +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`.