fix(auth): clear public write errors and Grok client path

Public DEC-654 still requires a caller bearer; anonymous session now
returns that guidance as a tool error instead of silent valid:false.
Error text names JWT and API key, Grok bearer_token_file, and local
stdio. BearerFromRequest also accepts X-Api-Key / X-Verae-Key.
Document Grok stdio vs public URL; add scripts/sync-mcp-bearer.sh.

internal/server/public_test.go

@@ -147,8 +147,9 @@ func TestPublicAnonymousWritesRefusedNoHostFallback(t *testing.T) {
 		}
 	}
 	ok, out := call(t, s, "session", map[string]any{})
-	if !ok || strings.Contains(out, `"valid":true`) {
-		t.Fatalf("anonymous session must not report the host login: %v %s", ok, out)
+	// Anonymous session is a tool error (not a silent valid:false) so agents see how to attach Bearer.
+	if ok || strings.Contains(out, `"valid":true`) || !strings.Contains(out, "needs your own Verae credential") {
+		t.Fatalf("anonymous session must error with credential guidance: %v %s", ok, out)
 	}
 	if vt.stamps.Load() != 0 || vt.users.Load() != 0 || vt.hostUse.Load() != 0 {
 		t.Fatalf("upstream writes or host-token use: stamps=%d users=%d host=%d", vt.stamps.Load(), vt.users.Load(), vt.hostUse.Load())

internal/tools/bearer.go

@@ -8,12 +8,27 @@ import (
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-// BearerFromRequest extracts Authorization: Bearer from the HTTP request headers.
+// BearerFromRequest extracts the caller credential from the MCP HTTP request.
+// Order: Authorization: Bearer, then X-Api-Key / X-Verae-Key (raw token).
 func BearerFromRequest(req *mcp.CallToolRequest) string {
 	if req == nil || req.Extra == nil || req.Extra.Header == nil {
 		return ""
 	}
-	auth := strings.TrimSpace(req.Extra.Header.Get("Authorization"))
+	h := req.Extra.Header
+	if tok := bearerFromAuthHeader(h.Get("Authorization")); tok != "" {
+		return tok
+	}
+	// Some gateways forward the key under these names instead of Authorization.
+	for _, name := range []string{"X-Api-Key", "X-Verae-Key", "X-Verae-Token"} {
+		if tok := strings.TrimSpace(h.Get(name)); tok != "" {
+			return tok
+		}
+	}
+	return ""
+}
+
+func bearerFromAuthHeader(auth string) string {
+	auth = strings.TrimSpace(auth)
 	if auth == "" {
 		return ""
 	}

internal/tools/bearer_test.go

@@ -1,6 +1,12 @@
 package tools
 
-import "testing"
+import (
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
 
 func TestLooksLikeCID(t *testing.T) {
 	t.Parallel()
@@ -20,3 +26,35 @@ func TestLooksLikeCID(t *testing.T) {
 		}
 	}
 }
+
+func TestBearerFromRequest(t *testing.T) {
+	t.Parallel()
+	req := &mcp.CallToolRequest{Extra: &mcp.RequestExtra{Header: http.Header{}}}
+	if got := BearerFromRequest(req); got != "" {
+		t.Fatalf("empty headers: %q", got)
+	}
+	req.Extra.Header.Set("Authorization", "Bearer jwt-one")
+	if got := BearerFromRequest(req); got != "jwt-one" {
+		t.Fatalf("Authorization: %q", got)
+	}
+	req.Extra.Header = http.Header{}
+	req.Extra.Header.Set("X-Api-Key", "key-two")
+	if got := BearerFromRequest(req); got != "key-two" {
+		t.Fatalf("X-Api-Key: %q", got)
+	}
+	req.Extra.Header = http.Header{}
+	req.Extra.Header.Set("Authorization", "bearer  spaced ")
+	if got := BearerFromRequest(req); got != "spaced" {
+		t.Fatalf("case/space: %q", got)
+	}
+}
+
+func TestErrWriteNeedsKeyMentionsJWTAndGrok(t *testing.T) {
+	t.Parallel()
+	msg := ErrWriteNeedsKey.Error()
+	for _, want := range []string{"Authorization: Bearer", "JWT", "bearer_token_file", "stdio"} {
+		if !strings.Contains(msg, want) {
+			t.Fatalf("ErrWriteNeedsKey missing %q: %s", want, msg)
+		}
+	}
+}

internal/tools/handlers.go

@@ -293,10 +293,12 @@ func (d *Deps) session(ctx context.Context, req *mcp.CallToolRequest, _ EmptyArg
 	if d.Global == nil {
 		return nil, SessionOut{}, fmt.Errorf("global VeraeTime client not configured")
 	}
-	tok, err := d.resolveBearer(ctx, req)
+	// Public: never report the host login. Missing caller bearer is an explicit tool error so agents
+	// see how to attach Authorization (silent valid:false hid the fix from Grok/Claude).
 	if d.Public && BearerFromRequest(req) == "" {
-		err = ErrWriteNeedsKey // never report the host's own login to an anonymous caller
+		return nil, SessionOut{Valid: false}, ErrWriteNeedsKey
 	}
+	tok, err := d.resolveBearer(ctx, req)
 	if err != nil {
 		return nil, SessionOut{Valid: false}, nil
 	}

internal/tools/public.go

@@ -1,11 +1,15 @@
 package tools
 
-// DEC-654 (D): on the public HTTP server (mcp.verae.ai) every write needs the caller's own credential - a Verae API
-// key or a VeraeTime login/OAuth bearer, checked at api.veraetime.net - and never falls back to this host's stored
-// service login. Writes: stamp (any scope; global stamps are billed to the key's customer), signup, create_user,
-// session, stamp_batch; login (it would replace the host credential) is refused. Read-only verify and hash_report
-// stay anonymous for the public pages (receipt links, explorer); only those use the host login, and they are never
-// rate limited (DEC-660, George 2026-10-10: "never limit").
+// DEC-654 (D): on the public HTTP server (mcp.verae.ai) every write needs the caller's own credential - a VeraeTime
+// JWT (access_token from login) or a Verae API key - checked at api.veraetime.net - and never falls back to this
+// host's stored service login. Writes: stamp (any scope; global stamps are billed to the caller's account), signup,
+// create_user, session, stamp_batch; login (it would replace the host credential) is refused. Read-only verify and
+// hash_report stay anonymous for the public pages (receipt links, explorer); only those use the host login, and they
+// are never rate limited (DEC-660, George 2026-10-10: "never limit").
+//
+// AI clients (Grok, Claude, Cursor) must send Authorization: Bearer on every tools/call. Grok Build:
+//   bearer_token_file = "~/.verae/mcp-bearer"   # raw JWT only, not auth.properties
+// or point a local stdio MCP at this binary (Public=false) so the laptop host token is used.
 
 import (
 	"context"
@@ -19,12 +23,22 @@ import (
 )
 
 // ErrWriteNeedsKey is returned for an anonymous write on the public server.
-var ErrWriteNeedsKey = errors.New("this tool needs your own Verae credential: send Authorization: Bearer <Verae API key> " +
-	"(create one at https://zap.verae.ai/portal/ or run `verae login`)")
+var ErrWriteNeedsKey = errors.New(
+	"this tool needs your own Verae credential on Authorization: Bearer. " +
+		"Use a VeraeTime JWT (access_token from `verae login` / ~/.verae/auth.properties) " +
+		"or a Verae API key from https://zap.verae.ai/portal/. " +
+		"Grok Build: set mcp_servers.verae-timestamping.bearer_token_file to a file that holds only the raw token " +
+		"(e.g. ~/.verae/mcp-bearer), then reconnect the MCP server; " +
+		"or run this binary with -transport stdio so the laptop host login is used",
+)
 
 // ErrLoginDisabled is returned by the login tool on the public server.
-var ErrLoginDisabled = errors.New("login is not available on the public server; sign in at https://zap.verae.ai/portal/ " +
-	"(or `verae login`) and send the Verae API key as a bearer token")
+var ErrLoginDisabled = errors.New(
+	"login is not available on the public HTTP server (it would replace the host credential). " +
+		"Sign in with `verae login` or at https://zap.verae.ai/portal/, put the JWT or API key in " +
+		"Authorization: Bearer on each MCP request (Grok: bearer_token_file), " +
+		"or use a local stdio MCP transport",
+)
 
 // CredentialChecker validates a caller bearer (implemented by veraetime.Client.CheckCredential).
 type CredentialChecker interface {

internal/tools/register.go

@@ -2,11 +2,12 @@ package tools
 
 import "github.com/modelcontextprotocol/go-sdk/mcp"
 
-const instructions = "Global stamps need a VeraeTime login on the machine that runs this server, " +
-	"or a bearer token from the browser signup on the public server. " +
-	"If session is not valid, ask the user to run `uvx verae-mcp-timestamping-server setup`. " +
-	"Do not ask them to paste a token into the chat or into mcp.json. " +
-	"The token file is ~/.verae/auth.properties, mode 600."
+const instructions = "Digests-only timestamping. " +
+	"Public HTTP (mcp.verae.ai / mcp.veraetime.net): every write needs Authorization: Bearer " +
+	"<VeraeTime JWT or Verae API key> on each tools/call — no host-login fallback. " +
+	"Grok Build: set bearer_token_file to a file that holds only the raw token (e.g. ~/.verae/mcp-bearer from access_token), " +
+	"or run this binary with -transport stdio so the laptop ~/.verae/auth.properties host login is used. " +
+	"Do not paste tokens into chat. Stdio/trusted-local HTTP may use the host login when no caller bearer is sent."
 
 // NewServer builds an MCP server with the full Verae timestamping tool set.
 func NewServer(d *Deps) *mcp.Server {