docs: rewrite README and add Claude Code guidance #15

heiko · 2026-04-29T09:59:43+02:00

heiko commented

2026-04-29 09:59:43 +02:00

Summary

Rewrite README.md to reflect the current state of the project (Go 1.26, correct repo URL, all flags documented, API reference, hook scripts, PKCS12 support, password notation, known issues)
Add .claude/CLAUDE.md for Claude Code tooling context
Bump go.mod to 1.26.2
Fix misleading wildcard in client config example (authorization uses exact match, not globs)

Test plan

Verify all documented flags match cert-proxy-server -help and cert-proxy-client -help output
Verify issue tracker links resolve
Confirm make test passes

## Summary - Rewrite README.md to reflect the current state of the project (Go 1.26, correct repo URL, all flags documented, API reference, hook scripts, PKCS12 support, password notation, known issues) - Add `.claude/CLAUDE.md` for Claude Code tooling context - Bump go.mod to 1.26.2 - Fix misleading wildcard in client config example (authorization uses exact match, not globs) ## Test plan - [ ] Verify all documented flags match `cert-proxy-server -help` and `cert-proxy-client -help` output - [ ] Verify issue tracker links resolve - [ ] Confirm `make test` passes

heiko added 4 commits

2026-04-29 09:59:43 +02:00

new: add .claude/CLAUDE.md for Claude Code guidance 70821bfc0d

go: update version 8070713070

docs: rewrite README to reflect current codebase e2928fa216

Update outdated references (Go 1.14 → 1.26, old repo URL), document
all server/client flags, hook scripts, PKCS12 support, password
notation, API endpoints, and add Known Issues section linked to
the issue tracker.

fix: remove misleading wildcard from client config example 9d0fc4ff84

The authorization check does exact domain matching (map lookup),
not glob/wildcard matching. The *.example.org example would confuse
administrators into thinking wildcards are supported.

heiko reviewed

2026-04-29 10:02:38 +02:00

heiko left a comment

[AI-generated review]

Overall: Approve. Massive improvement — well-structured, accurate against the codebase, and useful for both end-users and administrators. Docs-only PR with one trivial go.mod patch bump, no functional code changes.

See inline comments for suggestions.

**[AI-generated review]** Overall: **Approve.** Massive improvement — well-structured, accurate against the codebase, and useful for both end-users and administrators. Docs-only PR with one trivial `go.mod` patch bump, no functional code changes. See inline comments for suggestions.

.claude/CLAUDE.md

					
				@ -0,0 +40,4 @@

				| `GET /v1/chain/<domain>` | none | CA chain (public) |

				| `GET /v1/fullchain/<domain>` | none | Full chain (public) |

				| `GET /v1/privkey/<domain>` | authz | Private key |

				| `GET /v1/bundle/<domain>` | authz | PKCS12 bundle (generated on-the-fly via openssl) |

[AI] Nit: "one domain pattern per line" — the word "pattern" implies glob/wildcard matching, but auth.go:58 does exact map lookup (allowedDomains[ctx[DOMAIN]]). Suggest changing to "one domain per line" for consistency with the wildcard fix in the README.

[AI] **Nit:** "one domain pattern per line" — the word "pattern" implies glob/wildcard matching, but `auth.go:58` does exact map lookup (`allowedDomains[ctx[DOMAIN]]`). Suggest changing to "one domain per line" for consistency with the wildcard fix in the README.

@claude: please fix

README.md

					
				@ -55,2 +86,2 @@

				  git clone http://gitea.schlittermann.de/heiko/cert-proxy

				  ```

				The `-ssl.pem` bundle contains the certificate, private key, and CA

				certificate in a single PEM file.

[AI] Suggestion: The old README showed bin/mkssl-pem cert-proxy.example.com cert-proxy — giving a short CN (cert-proxy) with the FQDN as a SAN. This was useful because clients default -servername to the connect hostname. With just one argument, the cert CN will be cert-proxy.example.com, which works if the client connects to that exact hostname. Both are valid, but you may want to mention the SAN variant for cases where the server is reachable under multiple names.

[AI] **Suggestion:** The old README showed `bin/mkssl-pem cert-proxy.example.com cert-proxy` — giving a short CN (`cert-proxy`) with the FQDN as a SAN. This was useful because clients default `-servername` to the connect hostname. With just one argument, the cert CN will be `cert-proxy.example.com`, which works if the client connects to that exact hostname. Both are valid, but you may want to mention the SAN variant for cases where the server is reachable under multiple names.

@claude: please improve the docs

README.md Outdated

					
				@ -197,2 +126,3 @@

				```shell

				cert-proxy-client -help

				cd /etc/cert-proxy/ca

				bin/mkssl-pem <client-name>

[AI] Suggestion: The systemd units source EnvironmentFile=-/etc/default/cert-proxy-{server,client} and pass $OPTS to the binary. Admins can add extra flags there without editing the unit file. A one-liner mentioning this would help:

Additional flags can be set in `/etc/default/cert-proxy-server` (variable `OPTS`).

[AI] **Suggestion:** The systemd units source `EnvironmentFile=-/etc/default/cert-proxy-{server,client}` and pass `$OPTS` to the binary. Admins can add extra flags there without editing the unit file. A one-liner mentioning this would help: ``` Additional flags can be set in `/etc/default/cert-proxy-server` (variable `OPTS`). ```

@claude: please fix

README.md

					
				@ -203,0 +172,4 @@

				|------|---------|-------------|

				| `-connect` | `https://localhost:4433` | Server address |

				| `-sslfile` | `client-ssl.pem` | SSL auth file (crt+key+ca) PEM |

				| `-certbase` | `certs` | Base directory for downloaded certificates |

[AI] Suggestion: The PKCS12 hook invocation is documented as <script> deploy_cert <DOMAIN> <BUNDLEFILE> <TIMESTAMP> (3 meaningful args). However, the code at cert/cert.go:243-248 always allocates an 8-element Args slice with empty strings at positions 3-6 — so the actual call is deploy_cert <DOMAIN> "" "" "" "" <TIMESTAMP> with BUNDLEFILE only in the environment. This is likely the root cause of #14. The README documents intended behavior, which is fine, but a parenthetical "(see [#14])" after the PKCS12 example would save admins debugging time.

[AI] **Suggestion:** The PKCS12 hook invocation is documented as `<script> deploy_cert <DOMAIN> <BUNDLEFILE> <TIMESTAMP>` (3 meaningful args). However, the code at `cert/cert.go:243-248` always allocates an 8-element Args slice with empty strings at positions 3-6 — so the actual call is `deploy_cert <DOMAIN> "" "" "" "" <TIMESTAMP>` with BUNDLEFILE only in the environment. This is likely the root cause of #14. The README documents *intended* behavior, which is fine, but a parenthetical "(see [#14])" after the PKCS12 example would save admins debugging time.

@claude: provide a fix for this issue #14 in a new branch fix/14-pkcs12, and create a separate PR for it.

heiko added 1 commit

2026-04-29 10:09:30 +02:00

docs: address PR review suggestions 5aa265050c

- Fix "domain pattern" → "domain" in CLAUDE.md (no glob matching)
- Add $OPTS/EnvironmentFile note for systemd customization
- Document SAN variant for server cert creation
- Reference #14 in PKCS12 hook section

heiko added 1 commit

2026-04-29 10:15:32 +02:00

docs: use UTF-8 box-drawing characters in README diagram 4e9060a7fb

heiko force-pushed dev from 4e9060a7fb to 6543008e8b

2026-04-29 10:19:04 +02:00

Compare

heiko force-pushed dev from 6543008e8b to 4ca146c231

2026-04-29 10:20:37 +02:00

Compare

heiko force-pushed dev from 4ca146c231 to c7ffa5e193

2026-04-29 10:22:26 +02:00

Compare