docs: align public TLS and A2A status

CHANGELOG.md

@@ -19,7 +19,7 @@ else is additive. See the [v5 → v6 migration guide](internal/website/docs/guid
 - **JWT auth ported in-module.** The external `github.com/micro/plugins/v5/auth/jwt` (pinned to v5) is replaced by `go-micro.dev/v6/auth/jwt/token`, now on the maintained `golang-jwt/jwt/v5`; the deprecated `dgrijalva/jwt-go` dependency is dropped.
 
 ### Added
-- **A2A protocol — both directions** — `gateway/a2a` exposes registered agents over the open Agent2Agent (A2A) protocol so agents on other frameworks can discover and call them: Agent Cards are generated from registry metadata (the same way the MCP gateway derives tools), and incoming tasks are translated to the agent's existing `Agent.Chat` RPC, with no per-agent code (`micro a2a serve`). The outbound `a2a.Client` calls external A2A agents by URL, wired into `flow.A2A(url)` (a workflow step) and `delegate` to an `http(s)` URL (from inside an agent). An agent can also serve A2A **directly** without a gateway via `AgentA2A(addr)` (`a2a.NewAgentHandler`), handling tasks in-process. v1 is the synchronous JSON-RPC binding (`message/send`, `tasks/get`, card discovery); streaming and push notifications are advertised as unsupported. (`gateway/a2a/`, `cmd/micro/a2a/`)
+- **A2A protocol — both directions** — `gateway/a2a` exposes registered agents over the open Agent2Agent (A2A) protocol so agents on other frameworks can discover and call them: Agent Cards are generated from registry metadata (the same way the MCP gateway derives tools), and incoming tasks are translated to the agent's existing `Agent.Chat` RPC, with no per-agent code (`micro a2a serve`). The outbound `a2a.Client` calls external A2A agents by URL, wired into `flow.A2A(url)` (a workflow step) and `delegate` to an `http(s)` URL (from inside an agent). An agent can also serve A2A **directly** without a gateway via `AgentA2A(addr)` (`a2a.NewAgentHandler`), handling tasks in-process. The JSON-RPC binding includes `message/send`, `message/stream` (SSE), `tasks/get`, multi-turn continuation by `taskId`/`contextId`, best-effort push notification callbacks, and card discovery. `input-required` and `tasks/resubscribe` remain unsupported. (`gateway/a2a/`, `cmd/micro/a2a/`)
 - **Agents (`micro.NewAgent`)** — an agent is a service with an LLM inside: it discovers its assigned services as tools, runs the model's tool loop, registers a `Chat` RPC endpoint, and is reachable like any service. `Ask` for programmatic use; `micro chat` discovers and routes to agents; `micro agent list`/`describe`. (`agent/`)
 - **Plan & delegate** — two built-in agent tools added to every agent: `plan` (an ordered, store-persisted plan surfaced back in the prompt) and `delegate` (hand a self-contained subtask to a registered agent over RPC, otherwise to an ephemeral sub-agent). No harness or graph — they're plain tools. (`agent/builtin.go`, `examples/agent-plan-delegate/`)
 - **Agent guardrails** — `MaxSteps` (stop on count), `LoopLimit` (stop repeated no-progress calls; on by default), and `ApproveTool` (human-in-the-loop / policy gate before each action), enforced at the one point every tool call passes through. (`agent/`, guide + blog)

internal/website/docs/SECURITY_MIGRATION.md

@@ -2,58 +2,64 @@
 
 ## Overview
 
-This document provides guidance for migrating to secure TLS certificate verification in go-micro v5.
+Go Micro v6 verifies TLS certificates by default. This guide is for teams
+upgrading from v5, where TLS verification was disabled by default for backward
+compatibility.
 
-## Current Status (v5)
+## Current Status (v6)
 
-**Default Behavior**: TLS certificate verification is **disabled** by default (`InsecureSkipVerify: true`)
+**Default Behavior**: TLS certificate verification is **enabled** by default
+(`InsecureSkipVerify: false`).
 
-**Reason**: Backward compatibility with existing deployments to avoid breaking production systems during routine upgrades.
+**What changed from v5**: v5 allowed `MICRO_TLS_SECURE=true` to opt into
+certificate verification. In v6, secure verification is the default and
+`MICRO_TLS_SECURE` is no longer used.
 
-**Security Risk**: The default behavior is vulnerable to man-in-the-middle (MITM) attacks.
+**Development escape hatch**: for local self-signed certificates only, set
+`MICRO_TLS_INSECURE=true` or provide an explicit insecure TLS config.
 
-## Migration Path
+## Migration Path from v5
 
-### Option 1: Enable Secure Mode (RECOMMENDED)
+### 1. Remove the old opt-in flag
 
-Set the environment variable to enable certificate verification:
+Delete any use of the v5-only environment variable:
 
 ```bash
-export MICRO_TLS_SECURE=true
+unset MICRO_TLS_SECURE
 ```
 
-This enables proper TLS certificate verification while maintaining compatibility with v5.
+No replacement is required for production: verification is already on in v6.
 
-### Option 2: Use SecureConfig Directly
+### 2. Use the default secure config
 
-In your code, explicitly use the secure configuration:
+Most services need no TLS-specific code. If you configure TLS explicitly, use a standard `crypto/tls` config with verification enabled:
 
 ```go
 import (
+    "crypto/tls"
     "go-micro.dev/v6/broker"
-    mls "go-micro.dev/v6/util/tls"
 )
 
-// Create broker with secure TLS config
+// Create broker with certificate verification enabled.
 b := broker.NewHttpBroker(
-    broker.TLSConfig(mls.SecureConfig()),
+    broker.TLSConfig(&tls.Config{MinVersion: tls.VersionTLS12}),
 )
 ```
 
-### Option 3: Provide Custom TLS Configuration
+### 3. Provide a custom trust root when needed
 
-For fine-grained control, provide your own TLS configuration:
+For private CAs, provide your own TLS configuration:
 
 ```go
 import (
     "crypto/tls"
     "crypto/x509"
     "go-micro.dev/v6/broker"
-    "io/ioutil"
+    "os"
 )
 
 // Load CA certificates
-caCert, err := ioutil.ReadFile("/path/to/ca-cert.pem")
+caCert, err := os.ReadFile("/path/to/ca-cert.pem")
 if err != nil {
     log.Fatal(err)
 }
@@ -73,52 +79,61 @@ b := broker.NewHttpBroker(
 )
 ```
 
+### 4. Use insecure mode only for local development
+
+If a development environment still uses self-signed certificates that are not in
+your trust store, opt out explicitly:
+
+```bash
+export MICRO_TLS_INSECURE=true
+```
+
+or in code:
+
+```go
+broker.TLSConfig(&tls.Config{InsecureSkipVerify: true, MinVersion: tls.VersionTLS12})
+```
+
+Do not use insecure mode in production.
+
 ## Production Deployment Strategy
 
 ### Rolling Upgrade Considerations
 
-The current implementation maintains backward compatibility, allowing safe rolling upgrades:
+The default changed at the v6 major-version boundary. Before rolling v6 into a
+fleet that uses TLS, verify that:
 
-1. **Mixed Version Deployments**: v5 instances can communicate regardless of TLS security settings
-2. **No Immediate Breaking Changes**: Systems continue working with existing behavior
-3. **Gradual Migration**: Enable security incrementally across your infrastructure
+1. All services present certificates trusted by their peers.
+2. Private or self-signed CAs are installed consistently on every host.
+3. Certificates include the DNS names or IP subject alternative names used by
+   clients.
+4. Any deliberate development-only insecure settings are excluded from
+   production manifests.
 
 ### Recommended Approach
 
-1. **Test in Staging**:
-   ```bash
-   # In staging environment
-   export MICRO_TLS_SECURE=true
-   ```
-   
-2. **Deploy with Feature Flag**: Use environment-based configuration for gradual rollout
-
-3. **Monitor for Issues**: Watch for TLS handshake failures or certificate validation errors
-
-4. **Full Production Rollout**: Once validated, enable across all services
+1. **Test in Staging** with the same certificate chain and service names used in
+   production.
+2. **Remove v5 flags** such as `MICRO_TLS_SECURE`; they no longer control v6.
+3. **Monitor for Issues**: watch for TLS handshake failures or certificate
+   validation errors.
+4. **Use explicit insecure mode only in dev** when a short-lived environment
+   cannot yet provide trusted certificates.
 
 ### Multi-Host/Multi-Process Considerations
 
-**Certificate Trust**: When enabling secure mode, ensure:
+**Certificate Trust**: With secure mode as the default, ensure:
 
-1. All hosts trust the same root CAs
-2. Self-signed certificates are properly distributed if used
-3. Certificate validity periods are monitored
-4. Certificate chains are complete
+1. All hosts trust the same root CAs.
+2. Self-signed certificates are properly distributed if used.
+3. Certificate validity periods are monitored.
+4. Certificate chains are complete.
 
 **Service Mesh Alternative**: Consider using a service mesh (Istio, Linkerd, etc.) for:
 - Automatic mTLS between services
 - Certificate management and rotation
 - No application code changes required
 
-## Future Changes (v6)
-
-In go-micro v6, the default will change to **secure by default**:
-
-- `InsecureSkipVerify: false` (certificate verification enabled)
-- Breaking change requiring major version bump
-- Migration completed before v6 release avoids disruption
-
 ## Testing Your Migration
 
 ### Verify Secure Mode is Active
@@ -127,14 +142,12 @@ In go-micro v6, the default will change to **secure by default**:
 package main
 
 import (
+    "crypto/tls"
     "fmt"
-    mls "go-micro.dev/v6/util/tls"
-    "os"
 )
 
 func main() {
-    os.Setenv("MICRO_TLS_SECURE", "true")
-    config := mls.Config()
+    config := &tls.Config{MinVersion: tls.VersionTLS12}
     fmt.Printf("InsecureSkipVerify: %v (should be false)\n", config.InsecureSkipVerify)
 }
 ```
@@ -155,7 +168,7 @@ Create a test service and verify it:
 **Solution**:
 1. Add the CA certificate to the trusted root CAs
 2. Use a properly signed certificate
-3. For development only: Use `InsecureConfig()` explicitly
+3. For development only: use `MICRO_TLS_INSECURE=true` or an explicit insecure TLS config
 
 ### Issue: "x509: certificate has expired"
 
@@ -166,24 +179,17 @@ Create a test service and verify it:
 2. Implement certificate rotation
 3. Monitor certificate expiry dates
 
-### Issue: Services can't communicate after enabling secure mode
+### Issue: Services can't communicate after upgrading to v6
 
-**Cause**: Mixed certificate authorities or missing certificates
+**Cause**: Certificates that v5 accepted by default are now verified.
 
 **Solution**:
-1. Ensure all services use certificates from the same CA
+1. Ensure all services use certificates from a trusted CA
 2. Distribute CA certificates to all nodes
 3. Verify certificate SANs match service addresses
+4. Use insecure mode only as a temporary local-development workaround
 
 ## Questions?
 
-For issues or questions about TLS security migration, please:
-- Open an issue on GitHub
-- Check the documentation at https://go-micro.dev/docs/
-- Review the security guidelines
-
-## Security Resources
-
-- [OWASP TLS Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Protection_Cheat_Sheet.html)
-- [Go TLS Documentation](https://pkg.go.dev/crypto/tls)
-- [Certificate Best Practices](https://www.ssl.com/guide/ssl-best-practices/)
+For issues or questions about TLS security migration, open an issue on GitHub or
+check the documentation at https://go-micro.dev/docs/.

internal/website/docs/TLS_SECURITY_UPDATE.md

@@ -2,66 +2,36 @@
 
 ## What Changed
 
-The TLS configuration in go-micro now includes a security deprecation warning.
+Go Micro v6 verifies TLS certificates by default. This completes the v5 security
+migration where verification was opt-in.
 
-## Current Behavior (v5.x)
+## Current Behavior (v6.x)
 
-**Default**: TLS certificate verification is **disabled** for backward compatibility
-- This maintains existing behavior to avoid breaking production deployments
-- A deprecation warning is logged once per process startup
+**Default**: TLS certificate verification is **enabled**.
+- `MICRO_TLS_SECURE` was a v5 opt-in flag and is no longer used.
+- For local development with untrusted self-signed certificates, opt out
+  explicitly with `MICRO_TLS_INSECURE=true` or an explicit insecure TLS config.
 
-**Why**: Changing the default to secure would be a **breaking change** that could disrupt:
-- Production systems during routine upgrades
-- Distributed systems with mixed versions
-- Services using self-signed certificates
+## Production Recommendation
 
-## How to Enable Security (Recommended)
-
-### Option 1: Environment Variable
-
-```bash
-export MICRO_TLS_SECURE=true
-```
-
-### Option 2: Use SecureConfig
-
-```go
-import (
-    "go-micro.dev/v6/broker"
-    mls "go-micro.dev/v6/util/tls"
-)
-
-broker := broker.NewHttpBroker(
-    broker.TLSConfig(mls.SecureConfig()),
-)
-```
+For production deployments:
+1. Use CA-signed certificates or distribute your private CA to every host.
+2. Remove old `MICRO_TLS_SECURE` settings from v5-era manifests.
+3. Do not set `MICRO_TLS_INSECURE=true` in production.
+4. Consider service mesh mTLS (Istio, Linkerd) if certificate lifecycle should be
+   managed outside the application.
 
 ## Migration Timeline
 
-- **v5.x (Current)**: Insecure by default, opt-in security via `MICRO_TLS_SECURE=true`
-- **v6.x (Future)**: Secure by default (breaking change with major version bump)
-
-## Why This Approach?
-
-This addresses the concerns raised about:
-
-1. **Major version requirements**: No breaking change in v5, deferred to v6
-2. **Cross-host compatibility**: All hosts use same default behavior
-3. **Production safety**: Existing deployments continue working during upgrades
-4. **Migration path**: Clear opt-in path with documentation
+- **v5.x**: Insecure by default, opt-in security via `MICRO_TLS_SECURE=true`.
+- **v6.x current**: Secure by default; use `MICRO_TLS_INSECURE=true` only for an
+  explicit development opt-out.
 
 ## Documentation
 
-See [SECURITY_MIGRATION.md](SECURITY_MIGRATION.html) for detailed migration guide.
-
-## Security Recommendation
-
-For production deployments:
-1. Test with `MICRO_TLS_SECURE=true` in staging
-2. Use proper CA-signed certificates
-3. Consider service mesh (Istio, Linkerd) for automatic mTLS
-4. Plan migration before v6 release
+See [SECURITY_MIGRATION.md](SECURITY_MIGRATION.html) for the detailed migration
+guide.
 
 ## Questions?
 
-Open an issue on GitHub or check the documentation at https://go-micro.dev/docs/
+Open an issue on GitHub or check the documentation at https://go-micro.dev/docs/.