[antoinetoussaint-byte]

Closes #32.

Summary

• A solution can offer something inside a client (the wiki's citing surface inside a Word document), and the add-in currently carries a table of who offers what. Manifest.Surfaces moves that into the solution's own declaration, served at /.well-known/solution.json beside nav and dashboard and carried in the host registration heartbeat (both derive from manifestMap()).
• Serve refuses, before touching the environment, a surface no client could load: a well-formed id unique per client, a non-empty title, a known client kind (word, powerpoint, excel, slack), a contract major >= 1, and a module that is a path on this solution's own origin. An author's mistake is the same mistake in every environment, so it should not wait on addresses resolving.
• applies defaults to "always" on the wire when undeclared; description and events are omitted when empty, because absent they say something a client can act on. A {"tagged":[…]} selector and the event namespaces are carried verbatim — what a tag selects is the client's to interpret.

What the module check is and is not

It catches an author reaching off their own origin by mistake. It is not what stops a hostile solution from doing so deliberately: a solution serves its own manifest and need not use this runtime at all. The host's registry and the client's module loader own that boundary and have to enforce it independently — please do not treat this validation as the enforcement point.

Getting it right here still took care, because Go and the browser disagree about what a rooted path is. /\evil.example/x.js passes net/url with an empty Host, but WHATWG URL (every browser, and Node) reads the backslash as a slash and what follows as an authority:

new URL("/\evil.example/footnote.js", "https://solution.example").href
  -> https://evil.example/footnote.js

Same for /\/evil.example/x.js. ASCII tab and newline are removed from the input before that parser runs, so /<tab>/evil.example/x.js arrives protocol-relative. The check now inspects the bytes rather than asking net/url what it made of them.

Test plan

• go test -race ./... -count=1 — full suite green
• go vet ./... and gofmt -l ./*.go clean (the CI checks verbatim)
• The three bypass cases verified red against the previous implementation, green after — net/url-only validation accepted both backslash forms and the boot-level test failed
• Validation rejects: empty/uppercase/slashed id, leading-, trailing- and bare-dash id, duplicate id within one client, empty title, unknown/empty client, contract 0 and negative, absolute URL module, protocol-relative module, backslash and backslash-slash authority modules, tab- and newline-smuggled modules, relative module, empty module
• One id shared across two clients is accepted; two surfaces sharing an id in one client are refused
• Served manifest carries every declared slot through JSON, including a {tagged:[…]} selector unflattened
• applies is "always" when undeclared; no description/events keys when those are empty; no surfaces key when none declared
• Serve returns a boot error naming the surface, and does not bind, on an off-origin module

Host side (the registry projection in codefly-dev/module-saas-starter) is the companion issue and is not part of this PR.

🤖 Generated with Claude Code

[antoinetoussaint-byte]

Correction to the surfaces wire contract — an earlier cross-agent note described this shape before review, and three points in it were wrong. Recording the corrections here, since this PR is the durable copy. For whoever implements the host registry (module-saas-starter) or a client loader (obin-word):

1. Do not rely on this runtime's same-origin check. The earlier note said "the runtime validates that module is a same-origin path," which invites skipping your own check. A solution serves its own manifest and need not use this Go runtime at all — that validation catches an author's mistake and nothing else. The registry and the client's module loader must enforce the origin independently.

   It is also harder than it looks: /\evil.example/x.js has an empty Host in Go's net/url but resolves to https://evil.example/x.js under WHATWG URL (every browser, and Node) — the backslash is read as a slash and what follows as an authority. Same for /\/evil.example/x.js. ASCII tab and newline are stripped before that parser runs, so /<tab>/evil.example/x.js arrives protocol-relative. Validate with the parser that will resolve the path, or inspect the bytes.

2. Ids are unique per (client, id), not per solution. The same offering in two clients carries the same id — footnote in Word and in PowerPoint — so key the registry by the pair.

3. applies is always present, defaulting to "always" when the solution declares no selector; the earlier note said it was omitted. contract is always present and >= 1, and title is always non-empty (both refused at boot otherwise). description and events are omitted when empty — absent, those mean "nothing to show" and "nothing to reconcile on". The surfaces key itself stays absent when a solution declares none.