[pull] master from ghostunnel:master

README.md

@@ -373,10 +373,13 @@ See [SOCKET-ACTIVATION](docs/SOCKET-ACTIVATION.md) for examples.
 ### PROXY Protocol Support
 
 Ghostunnel in server mode supports signalling of transport connection information
-to the backend using the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)
-(v2), just pass the `--proxy-protocol` flag on startup. Note that the backend must
-also support the PROXY protocol and must be configured to use it when setting
-this option.
+to the backend using the [PROXY protocol](https://www.haproxy.org/download/3.1/doc/proxy-protocol.txt)
+(v2), just pass the `--proxy-protocol` flag on startup. Use `--proxy-protocol-mode`
+to also include TLS metadata and/or client certificate details. Note that the
+backend must support the PROXY protocol and must be configured to use it when
+setting this option.
+
+See [PROXY-PROTOCOL](docs/PROXY-PROTOCOL.md) for details on modes and TLV extensions.
 
 ### Landlock Support
 

docs/ACCESS-FLAGS.md

@@ -55,7 +55,7 @@ with `spiffe://ghostunnel/client1` or `spiffe://ghostunnel/client2` URI SANs (as
 well as other values). See documentation for the [wildcard][wildcard] package
 for more information.
 
-* `--allow-policy` and `--allow-query`
+* `--allow-policy` and `--allow-query` (*OPA bundle support since v1.9.0*)
 
 Allow clients where a Rego policy evaluates to `true` with the given query.
 For more information, see the Open Policy Agent section below.
@@ -67,6 +67,15 @@ from any client. This means that anyone will be able to establish a connection
 to the Ghostunnel server. This flag is mutually exclusive with other access
 control flags.
 
+### Passing Client Identity to Backends
+
+Ghostunnel verifies client certificates before forwarding connections, but
+backends may also need to know the client's identity for their own access
+control, logging, or auditing. Use `--proxy-protocol-mode=tls-full` (available
+since v1.10.0) to forward the client certificate (CN, full DER-encoded cert) to
+the backend via [PROXY protocol v2]({{< ref "PROXY-PROTOCOL.md" >}}) TLV
+extensions.
+
 ## Client mode
 
 Ghostunnel in client mode offers various flags that can be used to augment and
@@ -119,7 +128,7 @@ with `spiffe://ghostunnel/server1` or `spiffe://ghostunnel/server2` URI SANs (as
 well as other values). See documentation for the [wildcard][wildcard] package
 for more information.
 
-* `--verify-policy` and `--verify-query`
+* `--verify-policy` and `--verify-query` (*OPA bundle support since v1.9.0*)
 
 Verify that a Rego policy evaluates to `true` with the given query.
 For more information, see the Open Policy Agent section below.
@@ -135,6 +144,8 @@ but the backend doesn't require mutual authentication.
 
 ## Open Policy Agent
 
+*Available since v1.7.0, OPA bundle support available since v1.9.0.*
+
 Ghostunnel has support for [Open Policy Agent][opa] (OPA), both in server and
 client mode. The policy must be provided as an [OPA bundle][opa-bundles] on
 disk and the use of OPA is mutually exclusive with any other `allow` (or

docs/ACME.md

@@ -9,7 +9,7 @@ certificate via the [ACME][acme-rfc] protocol. This is powered by
 [certmagic][certmagic], which handles certificate storage, renewal, and OCSP
 stapling.
 
-## Basic usage
+## Basic Usage
 
 To enable ACME, use the `--auto-acme-cert` flag with the FQDN to obtain a
 certificate for. You must also specify an email address with
@@ -41,7 +41,7 @@ resolve to the public listening interface IP.
 Ghostunnel uses the [TLS-ALPN-01][tls-alpn-01] challenge type (HTTP-01 is
 disabled), so port 443 must be reachable.
 
-## Certificate storage and renewal
+## Certificate Storage and Renewal
 
 Certmagic stores certificates and account keys on disk. The default location
 depends on your OS:
@@ -57,7 +57,7 @@ intervention or `--timed-reload` is needed for ACME certificates.
 If a valid certificate already exists locally, Ghostunnel loads it from cache
 on startup without contacting the CA.
 
-## Revoking or force-renewing
+## Revoking or Force-Renewing
 
 Certmagic handles renewal automatically, but if you need to force a renewal
 (e.g. after a key compromise), delete the certificate and key files from the
@@ -71,7 +71,7 @@ described in [RFC 8555 Section 7.6][acme-revoke].
 [certbot-revoke]: https://eff-certbot.readthedocs.io/en/latest/using.html#revoking-certificates
 [acme-revoke]: https://datatracker.ietf.org/doc/html/rfc8555#section-7.6
 
-## Startup retry behavior
+## Startup Retry Behavior
 
 On startup, Ghostunnel attempts to obtain the initial certificate up to 5
 times with exponential backoff (starting at 5 seconds, capped at 2 minutes).

docs/CERTIFICATES.md

@@ -8,7 +8,7 @@ Ghostunnel supports several certificate and private key formats. The format
 is auto-detected from the file extension or by inspecting the first few
 bytes, so you don't need to specify it explicitly.
 
-## Formats at a glance
+## Formats at a Glance
 
 | Format | Extensions | Flag | Notes |
 |--------|-----------|------|-------|
@@ -21,7 +21,7 @@ bytes, so you don't need to specify it explicitly.
 These options are mutually exclusive with each other and with `--use-workload-api`,
 `--keychain-identity`, and PKCS#11 flags.
 
-## PEM files (separate cert and key)
+## PEM Files (Separate Cert and Key)
 
 Pass the certificate chain and private key as two separate PEM files:
 
@@ -50,7 +50,7 @@ any intermediate CA certificates:
 The key file must contain a single PEM-encoded private key (RSA, ECDSA,
 or Ed25519).
 
-## PEM keystore (combined file)
+## PEM Keystore (Combined File)
 
 A single PEM file containing both the certificate chain and private key can
 be passed with `--keystore`. The private key can appear anywhere in the file,
@@ -118,7 +118,7 @@ ghostunnel server \
     --allow-cn client
 ```
 
-## CA bundle
+## CA Bundle
 
 The `--cacert` flag accepts a PEM file containing one or more trusted CA
 certificates. If omitted, Ghostunnel uses the system trust store.
@@ -129,7 +129,7 @@ To build a CA bundle from individual certificates:
 cat root-ca.pem intermediate-ca.pem > cacert.pem
 ```
 
-## Format auto-detection
+## Format Auto-Detection
 
 Ghostunnel detects the format in this order:
 
@@ -141,15 +141,15 @@ Ghostunnel detects the format in this order:
 In practice, just use the right file extension and Ghostunnel will do the
 right thing.
 
-## Common operations
+## Common Operations
 
-### Inspect a PEM certificate
+### Inspect a PEM Certificate
 
 ```bash
 openssl x509 -in server-cert.pem -noout -text
 ```
 
-### Inspect a PKCS#12 file
+### Inspect a PKCS#12 File
 
 ```bash
 openssl pkcs12 -in server.p12 -info -nokeys
@@ -168,7 +168,7 @@ openssl pkcs12 -in server.p12 -cacerts -nokeys -out ca-chain.pem
 openssl pkcs12 -in server.p12 -nocerts -nodes -out server-key.pem
 ```
 
-### Verify a certificate chain
+### Verify a Certificate Chain
 
 ```bash
 openssl verify -CAfile cacert.pem server-cert.pem

docs/DOCKER.md

@@ -15,7 +15,7 @@ variants are available:
 
 The `latest` tags always point to the most recent release.
 
-## Pulling an image
+## Pulling an Image
 
 ```bash
 # Distroless (smallest, no shell)
@@ -51,7 +51,7 @@ container) and `host.docker.internal` for `--target` (to reach services on
 the Docker host). You may need `--unsafe-target` since `host.docker.internal`
 is not localhost.
 
-## Building images from source
+## Building Images from Source
 
 ```bash
 go tool mage docker:build

docs/FLAGS.md

@@ -109,10 +109,13 @@ See [Socket Activation]({{< ref "SOCKET-ACTIVATION.md" >}}) for `systemd:NAME` a
 
 ### Proxying
 
+See [PROXY Protocol]({{< ref "PROXY-PROTOCOL.md" >}}) for details on modes and TLV extensions.
+
 | Flag | Description |
 |------|-------------|
 | `--target-status URL` | Address to target for status checking downstream healthchecks. Defaults to TCP healthcheck if not passed. |
-| `--proxy-protocol` | Enable PROXY protocol v2 to signal connection info to backend. |
+| `--proxy-protocol` | Enable PROXY protocol v2 with connection info only (equivalent to `--proxy-protocol-mode=conn`). |
+| `--proxy-protocol-mode MODE` | PROXY protocol v2 mode: `conn`, `tls`, or `tls-full`. Mutually exclusive with `--proxy-protocol`. |
 | `--unsafe-target` | Do not limit target to localhost, `127.0.0.1`, `[::1]`, or UNIX sockets. See [Security]({{< ref "SECURITY.md" >}}). |
 
 ### Access Control

docs/GRACEFUL-SHUTDOWN.md

@@ -9,7 +9,7 @@ accepting new connections and waits for existing connections to drain before
 exiting. If connections do not drain within the configured timeout, the process
 force-exits.
 
-## Shutdown triggers
+## Shutdown Triggers
 
 There are three ways to initiate a graceful shutdown:
 
@@ -35,6 +35,8 @@ reload certificates and OPA policies on a fixed interval.
 
 ### HTTP endpoint (`/_shutdown`)
 
+*Available since v1.8.1.*
+
 If `--enable-shutdown` is set (requires `--status`), you can trigger a
 shutdown via HTTP POST:
 
@@ -44,7 +46,7 @@ curl -X POST --cacert test-keys/cacert.pem https://localhost:6060/_shutdown
 
 Any HTTP method other than POST returns 405 Method Not Allowed.
 
-## Shutdown sequence
+## Shutdown Sequence
 
 When a shutdown is triggered, the following happens in order:
 
@@ -71,7 +73,7 @@ When a shutdown is triggered, the following happens in order:
 
 See [Command-Line Flags]({{< ref "FLAGS.md" >}}) for the full flag reference.
 
-## Choosing a shutdown timeout
+## Choosing a Shutdown Timeout
 
 The default timeout of 5 minutes is deliberately generous. Consider your
 workload when tuning this value:
@@ -92,6 +94,8 @@ connection behavior and may be relevant when tuning shutdown. See
 
 ## Integration with systemd
 
+*Available since v1.8.0.*
+
 When running as a systemd service with `Type=notify-reload`, Ghostunnel
 notifies systemd of its state transitions (ready, reloading, stopping). The
 graceful shutdown sequence integrates naturally with systemd's service

docs/HSM-PKCS11.md

@@ -47,8 +47,7 @@ ghostunnel server \
 The `--pkcs11-module`, `--pkcs11-token-label` and `--pkcs11-pin` flags can be
 used to select the private key to be used from the PKCS#11 module. It's also possible
 to use environment variables to set PKCS#11 options instead of flags (via
-`PKCS11_MODULE`, `PKCS11_TOKEN_LABEL` and `PKCS11_PIN`), useful if you don't
-want to show the PIN on the command line.
+`PKCS11_MODULE`, `PKCS11_TOKEN_LABEL` and `PKCS11_PIN`), useful if you don't want to show the PIN on the command line.
 
 Note that `--cert` needs to point to the certificate chain that corresponds
 to the private key in the PKCS#11 module, with the leaf certificate being the
@@ -99,7 +98,7 @@ usually want slot **9a** (Authentication):
 | 9d   | Key Management       | Encryption               |
 | 9e   | Card Authentication  | Physical access          |
 
-### Generating a key and certificate
+### Generating a Key and Certificate
 
 Generate a key pair on the YubiKey itself (the private key never leaves
 the device):
@@ -119,7 +118,7 @@ Sign the CSR with your CA, then import the signed certificate back:
 yubico-piv-tool -s 9a -a import-certificate -i server-cert.pem
 ```
 
-### Exporting the certificate for Ghostunnel
+### Exporting the Certificate for Ghostunnel
 
 Ghostunnel reads the certificate chain from disk, not from the PKCS#11
 module, so you'll need to export it:
@@ -177,7 +176,7 @@ pkcs11-tool --module /path/to/libykcs11.dylib -L
 pkcs11-tool --module /path/to/libykcs11.dylib -O
 ```
 
-## Certificate hotswapping
+## Certificate Hotswapping
 
 When using PKCS#11, certificate hotswapping (via `SIGHUP`/`SIGUSR1` or
 `--timed-reload`) reloads only the certificate from disk. The private key
@@ -188,7 +187,7 @@ Note that Landlock sandboxing is automatically disabled when PKCS#11 is used,
 as PKCS#11 modules are opaque shared libraries that may need access to
 arbitrary files and sockets.
 
-## Inspecting PKCS#11 state
+## Inspecting PKCS#11 State
 
 If you need to inspect the state of a PKCS#11 module/token, we recommend the
 [`pkcs11-tool`][pkcs11-tool] utility from OpenSC. For example, it can be used

docs/KEYCHAIN.md

@@ -9,7 +9,7 @@ Keychain or Windows Certificate Store. This lets you use Secure Enclave-backed
 keys on Touch ID MacBooks, hardware-backed keys via CNG on Windows, or simply
 manage certificates through the OS instead of as files on disk.
 
-## Prerequisites: creating a PKCS#12 bundle
+## Prerequisites: Creating a PKCS#12 Bundle
 
 Both macOS and Windows import certificates from [PKCS#12][openssl-pkcs12]
 (`.p12` / `.pfx`) files. If you have a PEM certificate and key, bundle them
@@ -64,7 +64,7 @@ and [TN3137: On Mac keychain APIs and implementations][apple-tn3137].
 [apple-keychain-services]: https://developer.apple.com/documentation/security/keychain-services
 [apple-tn3137]: https://developer.apple.com/documentation/technotes/tn3137-on-mac-keychains
 
-### Secure Enclave and hardware tokens
+### Secure Enclave and Hardware Tokens
 
 On Touch ID MacBooks, private keys can live in the Secure Enclave. Pass
 `--keychain-require-token` so Ghostunnel only loads keys backed by a hardware
@@ -121,8 +121,8 @@ Get-ChildItem Cert:\CurrentUser\My | Format-Table Subject, Thumbprint, NotAfter
 on Windows, Ghostunnel searches three stores in this order:
 
 1. **MY** (Current User), the personal certificate store
-2. **CURRENT_SERVICE**, the current service account's certificates (if accessible)
-3. **LOCAL_MACHINE**, machine-wide certificates (if accessible; may require elevation)
+2. **CURRENT_SERVICE**, the current service account's certificates (if accessible, *since v1.8.1*)
+3. **LOCAL_MACHINE**, machine-wide certificates (if accessible; may require elevation, *since v1.8.1*)
 
 Stores that fail to open are skipped rather than causing an error.
 
@@ -134,7 +134,7 @@ See Microsoft's [certutil reference][ms-certutil],
 [ms-store-locations]: https://learn.microsoft.com/en-us/windows/win32/seccrypto/system-store-locations
 [ms-import-pfx]: https://learn.microsoft.com/en-us/powershell/module/pki/import-pfxcertificate
 
-## Selecting a certificate
+## Selecting a Certificate
 
 Certificates from the keychain can be selected using one or both of the
 following flags:
@@ -147,7 +147,7 @@ When both flags are specified, Ghostunnel selects certificates where both
 attributes match (logical AND). If multiple certificates match, the one with
 the latest expiration date (NotAfter) is used.
 
-## Usage examples
+## Usage Examples
 
 ### macOS
 
@@ -184,15 +184,15 @@ ghostunnel client \
     --cacert cacert.pem
 ```
 
-## Certificate reloading
+## Certificate Reloading
 
 Keychain certificates support reloading via `SIGHUP`/`SIGUSR1` or
 `--timed-reload`. On reload, Ghostunnel re-queries the keychain for a
 certificate matching the same identity/issuer criteria. If the certificate
 has been updated in the keychain (e.g. renewed), the new certificate will
 be used for subsequent connections.
 
-## Removing certificates
+## Removing Certificates
 
 **macOS**: remove an identity (certificate + private key) by Common Name: