webapp: organizations behind a Directory seam

The hub already abstracted authentication — AuthProvider, with BuiltinAuth
as the built-in implementation — and then reached around that seam three
times: Accounts() was declared on neither interface, admin.go type-asserted
*BuiltinAuth (five handlers silently degraded to 404/empty under any other
provider), and organizations were not on the seam at all.

That last gap had teeth. A deployment whose identities come from elsewhere
had no way to own its orgs, so the code that did own them wrote into the
hub's OrgDB from the side — and nothing stopped the hub from inventing an
org that the identity system had never heard of. One did: a hub-created org
held every project while the mirrored one sat empty, and no sync path could
see the difference.

Directory (directory.go) is where organizations live now. LocalDirectory
wraps today's OrgDB unchanged — same last-owner protection, same normEmail,
same "o-"+randHex(4) ids, same file/SQL persistence — so a self-hosted hub
behaves exactly as before. A deployment whose orgs are owned elsewhere
implements the same interface, returns ErrManagedElsewhere from the write
half, and the handlers answer 409 with ManageURL. The hub never learns why
a write was refused, only where to send the user.

Two rules shape the interface. Reads are on the request path: Role runs on
every project request, including the /store/* endpoints a device hits every
few seconds with a token that carries no identity claims, so an
implementation backed by a remote system answers from its own cache — and
that cache is its business, not the hub's. Writes are optional, because
"this hub owns its orgs" is a deployment fact, not a code path.

- Server.Orgs *OrgDB becomes Server.Dir Directory: 28 call sites, 8
  nil-checks, one writeDirErr helper for the 409 translation.
- /api/orgs gains manage_url per org — the destination of the account
  menu's Settings entry. The client follows a link and never branches on
  which kind of hub it is talking to.
- Org administration becomes a real route, /orgs/<id>, retiring one of the
  two URL-less panels CLAUDE.md grandfathers. When a directory's ManageURL
  is not hub-local, the SPA fallback redirects there instead — so a hub that
  cannot administer its orgs cannot paint a console whose every control 409s.
- Accounts() moves onto AuthProvider. admin.go's type assertion becomes an
  optional AccountApprover, and a provider without one now answers 503
  rather than an empty approval queue: "no queue here" and "queue is empty"
  are different answers and only one of them was true.

Two reviews drove the rest. The architecture review caught a browser page
load that could delete org members (a display read ran the full membership
reconcile, and a 200 with an empty user list evicted everyone), one write
site that escaped the 409 translation, and a webhook that could wedge an
event stream behind an unappliable event. The design review, over eight
rounds, caught the org page rendering live controls on a hub that cannot
use them, a share link made unrevokable by a long filename, nine keyboard
tab stops parked off-screen behind a closed drawer, and — five separate
times — a fix of mine that looked right in the source and did nothing in
the browser.

Conformance tests run both a writable and a read-only implementation against
one contract; the seat, prune, and out-of-order regressions each have a test
written to fail against the old code.
This commit is contained in:
Snow Lee
2026-07-20 03:06:19 -07:00
parent 93f2c6bc84
commit dfef5720df
56 changed files with 1068 additions and 208 deletions
+53 -4
View File
@@ -400,6 +400,29 @@ func (a *BuiltinAuth) grantDevice(id, userID string) bool {
return true
}
// Branding is the hub name this provider renders on its own pages.
func (a *BuiltinAuth) Branding() string { return a.Brand }
// Policy reports this provider's signup gates (webapp.AccountApprover). The
// provider assembles it so the hub never reaches into these fields itself.
func (a *BuiltinAuth) Policy() SignupPolicy {
a.mu.Lock()
defer a.mu.Unlock()
admins := make([]string, 0, len(a.Admins))
for e := range a.Admins {
admins = append(admins, e)
}
sort.Strings(admins)
return SignupPolicy{
RequireVerification: a.RequireVerification,
RequireApproval: a.RequireApproval,
AllowSignup: a.AllowSignup,
AllowedDomains: a.AllowedDomains,
Admins: admins,
Mailer: a.Mail != nil,
}
}
// PendingUsers lists accounts awaiting admin approval, oldest first.
func (a *BuiltinAuth) PendingUsers() []User {
a.mu.Lock()
@@ -606,8 +629,34 @@ font-family:ui-monospace,Menlo,monospace}
}
func field(label, name, typ, value string) string {
return fmt.Sprintf(`<label>%s</label><input name=%q type=%q value=%q required>`,
html.EscapeString(label), name, typ, html.EscapeString(value))
return fmt.Sprintf(`<label for="f-%s">%s</label><input id="f-%s" name=%q type=%q value=%q autocomplete=%q required>`,
name, html.EscapeString(label), name, name, typ, html.EscapeString(value), autocompleteFor(name, typ))
}
// autocompleteFor names a field's purpose so browsers and password managers
// fill it (WCAG 1.3.5). A password field's purpose depends on the page, not
// its name: offering a saved credential on a signup form is worse than
// offering nothing, so those callers use newPasswordField.
func autocompleteFor(name, typ string) string {
switch name {
case "email":
return "email"
case "name":
return "name"
case "code":
return "one-time-code"
}
if typ == "password" {
return "current-password"
}
return "on"
}
// newPasswordField is field() for a password being CREATED (signup, reset),
// so a manager generates one instead of filling an existing login.
func newPasswordField(label, name string) string {
return fmt.Sprintf(`<label for="f-%s">%s</label><input id="f-%s" name=%q type="password" autocomplete="new-password" required>`,
name, html.EscapeString(label), name, name)
}
func (a *BuiltinAuth) pageLogin(w http.ResponseWriter, r *http.Request) {
@@ -715,7 +764,7 @@ func (a *BuiltinAuth) pageSignup(w http.ResponseWriter, r *http.Request) {
field("Name", "name", "text", r.FormValue("name")),
field("Email", "email", "email", r.FormValue("email")),
domainNote,
field("Password (min 8 chars)", "password", "password", ""),
newPasswordField("Password (min 8 chars)", "password"),
errMsg, url.QueryEscape(next)))
}
@@ -863,7 +912,7 @@ func (a *BuiltinAuth) pageResetConfirm(w http.ResponseWriter, r *http.Request) {
func resetForm(token, msg string) string {
return fmt.Sprintf(`<form method="post"><input type="hidden" name="token" value=%q>%s%s<button>Set password</button></form>`,
html.EscapeString(token), field("New password (min 8 chars)", "password", "password", ""), msg)
html.EscapeString(token), newPasswordField("New password (min 8 chars)", "password"), msg)
}
func requestBaseURL(r *http.Request) string {