[MTC] Improve MTC Log docs

cmd/mtc/log/README.md

@@ -0,0 +1,51 @@
+# MTC Log Package
+
+Package `log` provides the core logic and Go API for an MTC
+([`draft-ietf-plants-merkle-tree-certs`](https://datatracker.ietf.org/doc/html/draft-ietf-plants-merkle-tree-certs))
+issuance log server using [c2sp.org/mtc-tlog](https://c2sp.org/mtc-tlog). It
+does not implement ACME-related features, nor any CA business logic.
+
+It is meant to be used with a Tessera log. At the moment, it only works with a
+[POSIX storage backend](/storage/posix/).
+
+## Functionalities
+
+This library:
+ - Logs
+   [`TBSCertificateLogEntry`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#log-entries)
+   and returns a corresponding
+   [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format)
+   including cosignatures.
+ - Pushes entries to mirrors and serves checkpoints with their cosignatures.
+ - Publishes active [landmarks](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#section-6.4.3).
+ - Builds inclusion proofs to active landmark sizes.
+
+
+## API Surface
+
+### Configuration
+
+- **`NewMTCLog(ctx, appender, opts)`**: Initializes an `MTCLog` instance backed
+  by a Tessera appender and configured with [`*Options`](./mtc.go).
+- **`NewOptions()`**: Creates an `Options` builder to configure the landmarks
+  storage backends, landmark intervals, maximum certificate lifetime, signers,
+  and subtree witness groups. Default options can be customized with
+  corresponding `With*` methods defined in [`mtc.go`](./mtc.go), such as
+  `WithMaxCertLifetime`.
+
+### MTC APIs
+
+- **`AddTBS(ctx, tbs)`**: Validates and appends a [`TBSCertificateLogEntry`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#log-entries)
+  to the log. Returns an [`AddTBSRsp`](https://github.com/search?q=repo%3Atransparency-dev%2Ftessera+symbol%3AAddTBSRsp+path%3Amtc.go&type=code)
+  containing the assigned leaf `Index` and a serialized [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format)
+  (with subtree signatures) to construct a standalone certificate.
+- **`ProofToLandmark(ctx, index)`**: Generates a TLS-encoded landmark-relative
+  [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format)
+  for the given entry index. If the enclosing landmark is still pending
+  publication, returns a retry duration.
+
+### Reads
+
+- Log data is served as a [tlog-tiles](https://c2sp.org/tlog-tiles) log,
+  through the APIs of the Tessera storage driver used.
+- Landmarks are served through the same read APIs, at `/landmarks`.

cmd/mtc/log/posix/README.md

@@ -1,14 +1,65 @@
 # POSIX MTC Log
 
-This directory contains an MTC (`draft-ietf-plants-merkle-tree-certs`) issuance
-log server backed by Tessera's POSIX storage implementation.
+This directory contains an MTC ([`draft-ietf-plants-merkle-tree-certs`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html))
+issuance log server backed by [Tessera's POSIX storage implementation](/storage/posix/).
+
+This document contains [Documentation](#documentation) and a [Codelab](#codelab).
+
+A matching POSIX Mirror implementation is available at [/cmd/mtc/mirror/posix](/cmd/mtc/mirror/posix).
 
 > [!WARNING]
 > This binary and the internal packages it uses are still under active
 > development, and should be considered experimental and not
 > production-ready. They remain outside the SemVer policy.
 
-## Running
+## Documentation
+
+### Main functionalities
+
+See [mtc/log/README.md](../README.md).
+
+### API
+
+#### HTTP Endpoints
+
+The log server exposes the following HTTP endpoints:
+
+- `POST /add-tbs`: Submits a JSON-encoded [`TBSCertificateLogEntry`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#log-entries)
+  to append to the log. Returns HTTP 201 Created with a JSON-encoded
+  [`AddTBSRsp`](https://github.com/search?q=repo%3Atransparency-dev%2Ftessera+symbol%3AAddTBSRsp+path%3Amtc.go&type=code)
+  containing the assigned entry `index` and a TLS-encoded [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format),
+  with subtree signatures.
+- `GET /proof-to-landmark?index=<index>`: Fetches a landmark-relative
+  [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format)
+  for the given entry index. Returns HTTP 200 OK with a [`ProofToLandmarkRsp`](https://github.com/search?q=repo%3Atransparency-dev%2Ftessera+symbol%3AProofToLandmarkRsp+path%3Amtc.go&type=code),
+  containing a TLS-encoded [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format),
+  or HTTP 202 Accepted with a `Retry-After` header if an enclosing landmark has
+  not been published yet.
+
+#### Log data and Landmarks
+
+Log data (checkpoints, tiles, leaves) and the `/landmarks` resource are
+accessible through the underlying POSIX storage filesystem.
+
+### Configuration
+
+Inspect the [`main.go`](./main.go) file for a full list of flags.
+
+Notable MTC-related flags are:
+
+- `landmark_interval`: Interval between publishing landmarks. If 0, defaults
+   to CQRP recommended interval for max_cert_lifetime.
+- `ca_id`: The CA ID as per [draft-ietf-plants-merkle-tree-certs Section 5.1](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certification-authority-ide)
+  (e.g. 32473.106)
+- `log_number`: The issuance log number (strictly positive).
+- `private_key`: Location of private key file. If unset, uses the contents of
+  the `LOG_PRIVATE_KEY` environment variable.
+- `max_cert_lifetime`: Maximum validity duration allowed for submitted
+  certificate entries.
+- `mirror_policy`: File containing the mirror policy in tlog-policy format. If
+  unset, no mirroring will be performed.
+
+## Codelab
 
 These instructions will help you bring up an MTC POSIX log, and send entries to
 it using the [Hammer](../hammer/hammer.go). If you'd like, you can also run a

cmd/mtc/log/posix/main.go

@@ -43,7 +43,6 @@ var (
 	// Tessera settings
 	storageDir                = flag.String("storage_dir", "", "Path to root of log storage.")
 	checkpointInterval        = flag.Duration("checkpoint_interval", 1500*time.Millisecond, "Interval between publishing checkpoints when the log has grown")
-	landmarkInterval          = flag.Duration("landmark_interval", 0, "Interval between publishing landmarks. If 0, defaults to CQRP recommended interval for max_cert_lifetime.")
 	batchMaxSize              = flag.Uint("batch_max_size", tessera.DefaultBatchMaxSize, "Maximum number of entries to process in a single sequencing batch.")
 	batchMaxAge               = flag.Duration("batch_max_age", tessera.DefaultBatchMaxAge, "Maximum age of entries in a single sequencing batch.")
 	awaiterPollInterval       = flag.Duration("awaiter_poll_interval", 100*time.Millisecond, "Interval between checkpoint polls by the publication awaiter.")
@@ -56,10 +55,11 @@ var (
 	clientHTTPMaxIdlePerHost = flag.Int("client_http_max_idle_per_host", 10, "Maximum number of idle HTTP connections per host for outgoing requests.")
 
 	// CA settings
-	caID            = flag.String("ca_id", "32473.106", "The CA ID as per draft-ietf-plants-merkle-tree-certs section 5.1 (e.g. 32473.106)")
-	logNumber       = flag.Uint64("log_number", 1, "The issuance log number (strictly positive)")
-	privKeyFile     = flag.String("private_key", "", "Location of private key file. If unset, uses the contents of the LOG_PRIVATE_KEY environment variable.")
-	maxCertLifetime = flag.Duration("max_cert_lifetime", log.DefaultMaxCertLifetime, "Maximum validity duration allowed for submitted certificate entries.")
+	landmarkInterval = flag.Duration("landmark_interval", 0, "Interval between publishing landmarks. If 0, defaults to CQRP recommended interval for max_cert_lifetime.")
+	caID             = flag.String("ca_id", "32473.106", "The CA ID as per draft-ietf-plants-merkle-tree-certs Section 5.1 (e.g. 32473.106)")
+	logNumber        = flag.Uint64("log_number", 1, "The issuance log number (strictly positive)")
+	privKeyFile      = flag.String("private_key", "", "Location of private key file. If unset, uses the contents of the LOG_PRIVATE_KEY environment variable.")
+	maxCertLifetime  = flag.Duration("max_cert_lifetime", log.DefaultMaxCertLifetime, "Maximum validity duration allowed for submitted certificate entries.")
 )
 
 func main() {