feat(11.1-04): add the Database section and the core Services pages

- docs/database: models, migrations, queries and pagination, relations,
  casts and validation, attachments and transactions (lagoon.Transaction,
  lagoon.AfterCommit, nested savepoints, lagoon.OnDatabase)
- docs/services: configuration, events, routing with auth groups, rate
  limiting, authentication, the OAuth server, mail and localization
- runnable Examples for lagoon, attach, compass, surf, wire, bouncer,
  wristband, postcard, phrasebook and festival; lagoon TestDocs* regions
  run on the package's Postgres harness through DocsDB
- 15 new required pages

modules/wristband/example_test.go

@@ -0,0 +1,84 @@
+package wristband_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http/httptest"
+
+	"git.golem15.com/golem15/summercms/modules/wristband"
+)
+
+// newServer builds the authorization server of an application served at
+// https://blog.example.com. The application sets Issuer and Resource for
+// its own deployment; the defaults cover everything else.
+func newServer() *wristband.Server {
+	opts := wristband.DefaultOptions()
+	opts.Issuer = "https://blog.example.com"
+	opts.Resource = "https://blog.example.com/mcp"
+	opts.ScopesSupported = []string{"read", "write", "offline_access"}
+	return wristband.NewServer(opts)
+}
+
+func ExampleServer_Metadata() {
+	srv := newServer()
+	// srv.SetBackend(backend) attaches the application's stores; the
+	// metadata document does not need them.
+	rec := httptest.NewRecorder()
+	srv.Metadata(rec, httptest.NewRequest("GET", "/.well-known/oauth-authorization-server", nil))
+
+	var doc map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &doc); err != nil {
+		fmt.Println(err)
+		return
+	}
+	for _, key := range []string{
+		"issuer",
+		"authorization_endpoint",
+		"token_endpoint",
+		"registration_endpoint",
+		"scopes_supported",
+		"grant_types_supported",
+		"code_challenge_methods_supported",
+	} {
+		fmt.Println(key, doc[key])
+	}
+	// Output:
+	// issuer https://blog.example.com
+	// authorization_endpoint https://blog.example.com/oauth/mcp/authorize
+	// token_endpoint https://blog.example.com/oauth/mcp/token
+	// registration_endpoint https://blog.example.com/oauth/mcp/register
+	// scopes_supported [read write offline_access]
+	// grant_types_supported [authorization_code refresh_token]
+	// code_challenge_methods_supported [S256]
+}
+
+func ExampleRejectRedirectURI() {
+	for _, uri := range []string{
+		"https://client.example.org/callback",
+		"http://127.0.0.1:33418/callback",
+		"http://client.example.org/callback",
+	} {
+		if reason := wristband.RejectRedirectURI(uri); reason != "" {
+			fmt.Println("rejected:", reason)
+			continue
+		}
+		fmt.Println("accepted:", uri)
+	}
+	// Output:
+	// accepted: https://client.example.org/callback
+	// accepted: http://127.0.0.1:33418/callback
+	// rejected: Redirect URI must be https:// or loopback http://127.0.0.1 / http://localhost: http://client.example.org/callback
+}
+
+func ExampleIssueClientCredentials() {
+	// A confidential client gets a secret, shown once; store only the hash.
+	id, secret, hash, err := wristband.IssueClientCredentials("client_secret_post")
+	fmt.Println(id != "", secret != "", hash != nil && *hash != secret, err)
+
+	// A public client (PKCE only) gets no secret.
+	_, secret, hash, err = wristband.IssueClientCredentials("none")
+	fmt.Println(secret == "", hash == nil, err)
+	// Output:
+	// true true true <nil>
+	// true true <nil>
+}