Document every exported symbol and how callers use the library.

Co-authored-by: Cursor <cursoragent@cursor.com>

signer.go

@@ -38,6 +38,9 @@ type Signer struct {
 
 // NewSignerFromEnv reads USER_TOKEN_PRIVATE_KEY_FILE, USER_TOKEN_ISSUER,
 // USER_TOKEN_AUDIENCE, and optional USER_TOKEN_TTL.
+// It returns an error when the private-key path is empty, the PEM is not an
+// RSA key, USER_TOKEN_TTL is set and is not a time.Duration, or issuer or
+// audience is empty. An empty USER_TOKEN_TTL uses 5 minutes.
 func NewSignerFromEnv() (*Signer, error) {
 	path := strings.TrimSpace(os.Getenv("USER_TOKEN_PRIVATE_KEY_FILE"))
 	if path == "" {
@@ -63,6 +66,8 @@ func NewSignerFromEnv() (*Signer, error) {
 }
 
 // NewSigner checks the key, issuer, and audience.
+// It returns an error when PrivateKey is nil or issuer or audience is empty.
+// A TTL of zero or less uses 5 minutes.
 func NewSigner(cfg SignConfig) (*Signer, error) {
 	if cfg.PrivateKey == nil {
 		return nil, fmt.Errorf("private key is nil")
@@ -85,7 +90,9 @@ type tokenClaims struct {
 	Groups            *[]string `json:"groups,omitempty"`
 }
 
-// Mint signs one token at now. Subject becomes sub and preferred_username.
+// Mint signs one RS256 token at now.
+// Subject becomes both sub and preferred_username.
+// It returns an error when Subject is empty or the key cannot sign.
 func (s *Signer) Mint(now time.Time, in MintInput) (string, error) {
 	subject := strings.TrimSpace(in.Subject)
 	if subject == "" {