model access B: refreshable-grant machinery — manager, at-rest refresh token, refresh flow

The ADR 0050 carve-out, built generic and vendor-neutral. A refreshable-grant
licence records one manager node; that node holds the refresh token encrypted at
rest, access tokens are still sealed per holder, and the refresh token is never in
a holder's delivery. Bounded on the three stated axes: refreshable-grant vendors
only, the refresh token only, the manager node only. Anthropic's actual OAuth
refresh stays a Phase-C plug-in behind a clean seam.

- New at-rest crypto (secrets.SealAtRest/OpenAtRest): envelope encryption distinct
  from the per-holder anonymous-box seal. The refresh token is under a symmetric
  data key (secretbox); the data key is wrapped to the manager node's public
  sealing key. The database alone holds ciphertext and a wrapped key with no
  private half to open either — only the manager node reads it back.

- Refreshable-grant adapter dispatch: anthropic is now refreshable-grant,
  anthropic-api-key the static-key second case. The adapter implements the
  Refresher seam by delegating to an injected VendorRefresher (the Phase-C plug,
  none shipped). static-key is untouched. The type assertion to Refresher is what
  gates the carve-out to refreshable-grant vendors.

- Refresh lease/rotate/publish flow (Licences.Refresh): a transaction-scoped
  advisory lock is the single-refresher lease; the new access token comes from the
  vendor refresh, is sealed per holder (secrets.Seal, as Accept does) and delivered
  on the next push — doc 13's reseal-and-publish half, all-or-nothing. The refresh
  token stays put, re-encrypted at rest only if the vendor rotated it.

- Manager and refresh_grant schema: consolidated into migrations/0001 and carried
  by a new incremental 0003 (the dual-write rule).

- 17 new tests, including the four security checks: KeyFor never carries the
  refresh token, a static key has no manager and cannot be refreshed, the at-rest
  token needs the manager's key, and a refresh delivers a new sealed access token.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

internal/licences/adapters/adapters.go

@@ -5,13 +5,15 @@
 // vendor answers, and the lifecycle that vendor's credential needs, lives here — exactly as
 // `public-dns` is one neutral interface answered by registrar-scoped providers (ADR 0044).
 //
-// **Phase A ships only the `static-key` shape.** A static-key vendor implements almost nothing: the
-// credential is an operator-supplied value, sealed to each holder by the generic anonymous box
-// (ADR 0024) and delivered unchanged. The refreshable-grant machinery — central rotation, an
-// identity guard, a usage reading, refresh-token-stripped delivery — is Phase B, and its verbs are
-// named here as optional capabilities (Refresher, Identifier, UsageReader) so the seam exists
-// before the code does. The abstraction earns its keep by making the common vendor small, not the
-// rare one clever (ADR 0050).
+// **Two shapes.** A `static-key` vendor implements almost nothing: the credential is an
+// operator-supplied value, sealed to each holder by the generic anonymous box (ADR 0024) and
+// delivered unchanged. A `refreshable-grant` vendor carries the bounded carve-out — a manager node
+// holds the refresh token encrypted at rest, access tokens are still sealed per holder, and the
+// refresh token is never in a holder's delivery. This package holds the generic half of both. The
+// vendor-specific half of a refresh — the actual OAuth call against a vendor's endpoint — is a
+// VendorRefresher plugged in from outside (novox/hq ADR 0050, Phase C); this build ships none, and
+// a refresh on a vendor with nothing plugged in is refused in as many words rather than pretended.
+// The abstraction earns its keep by making the common vendor small, not the rare one clever.
 package adapters
 
 import (
@@ -19,6 +21,7 @@ import (
 	"fmt"
 	"sort"
 	"strings"
+	"sync"
 
 	"github.com/novox/mesh-control/internal/secrets"
 )
@@ -55,11 +58,72 @@ type Adapter interface {
 	Deliver(sealed string) string
 }
 
-// Refresher is implemented only by a refreshable-grant adapter (ADR 0050, Phase B): the
-// lease / rotate / publish machinery a manager node runs. A static-key adapter does not implement
-// it, and a caller finds its absence by a type assertion.
+// RefreshInput is what producing a new access token needs, and all a refresh is given.
+//
+// It carries the refresh token **only as its at-rest envelope** — the caller (the control plane)
+// never holds the refresh token in the clear, because it cannot open the envelope. Opening it, and
+// the vendor call that follows, happen where the manager node's private key is (ADR 0050, Phase C).
+type RefreshInput struct {
+	Licence string
+	// Manager is the node that holds the refresh token readably — the one place the envelope opens.
+	Manager string
+	// AtRest is the refresh token encrypted at rest under the manager's key. Opaque to the control
+	// plane; meaningful only to the manager node that produced it.
+	AtRest secrets.AtRest
+}
+
+// RefreshResult is what a refresh produced: a new access token to seal per holder, and — only if the
+// vendor rotated it — the refresh token re-encrypted at rest, ready to replace the stored envelope.
+type RefreshResult struct {
+	// AccessToken is the new access token, in the clear. The mesh seals it per holder and discards
+	// it, exactly as it does an accepted key. It is never the refresh token.
+	AccessToken string
+	// NewAtRest is the refresh token re-sealed at rest, present only when the vendor rotated the
+	// refresh token too. Nil leaves the stored envelope untouched. Already encrypted, so the control
+	// plane stores it without ever seeing the refresh token in the clear.
+	NewAtRest *secrets.AtRest
+}
+
+// Refresher is implemented only by a refreshable-grant adapter (ADR 0050): the vendor-neutral half
+// of the lease / rotate / publish machinery. A static-key adapter does not implement it, and a
+// caller finds its absence by a type assertion — which is exactly what gates the carve-out to
+// refreshable-grant vendors.
 type Refresher interface {
-	Refresh(ctx context.Context, licence string) error
+	Refresh(ctx context.Context, in RefreshInput) (RefreshResult, error)
+}
+
+// VendorRefresher is the vendor-specific half, plugged in from outside (ADR 0050, Phase C): given a
+// refresh, it opens the at-rest envelope with the manager node's key, calls the vendor's endpoint,
+// and returns the new access token (and a re-sealed refresh token if the vendor rotated it). It is
+// the one component that reads a refresh token in the clear, and in production it runs where the
+// manager node's private key is. This build registers none; Anthropic's OAuth refresh is Phase C.
+type VendorRefresher interface {
+	Refresh(ctx context.Context, in RefreshInput) (RefreshResult, error)
+}
+
+// refreshers is what has been plugged in, keyed by vendor. Empty in this build.
+var refreshers struct {
+	sync.RWMutex
+	byVendor map[string]VendorRefresher
+}
+
+// RegisterRefresher plugs a vendor's real refresh in (ADR 0050, Phase C), or a fake in a test. The
+// generic refreshable-grant adapter for that vendor then delegates to it. Registering nothing leaves
+// the seam empty, and a refresh on that vendor is refused with a message that names Phase C rather
+// than failing obscurely.
+func RegisterRefresher(vendor string, r VendorRefresher) {
+	refreshers.Lock()
+	defer refreshers.Unlock()
+	if refreshers.byVendor == nil {
+		refreshers.byVendor = map[string]VendorRefresher{}
+	}
+	refreshers.byVendor[vendor] = r
+}
+
+func refresherFor(vendor string) VendorRefresher {
+	refreshers.RLock()
+	defer refreshers.RUnlock()
+	return refreshers.byVendor[vendor]
 }
 
 // Identifier is the mis-binding guard (ADR 0050, Phase B): a vendor whose credential carries an
@@ -89,15 +153,16 @@ type UsageRow struct {
 
 // registry maps a vendor name to the shape its adapter has.
 //
-// The single place a vendor is taught to the mesh. For Phase A the only entry is anthropic as a
-// static-key vendor, which is what the lab bed exercises.
+// The single place a vendor is taught to the mesh. anthropic's real credential is a subscription
+// OAuth grant, so it is the first `refreshable-grant` vendor; `anthropic-api-key` is the same
+// company's plain API keys, the early second `static-key` case ADR 0050 names — it exercises the
+// whole path with the carve-out switched off. Static-key vendors are added here as one line each.
 //
-// TODO(Phase B, ADR 0050): anthropic's real credential is a subscription OAuth grant, so its entry
-// becomes RefreshableGrant and a refreshable-grant adapter is registered for it; the static-key
-// path for the same vendor's plain API keys moves to a separate `anthropic-api-key` vendor, the
-// early second static-key case ADR 0050 names. Static-key vendors are added here as one line each.
+// TODO(Phase C, ADR 0050): register anthropic's real VendorRefresher — the OAuth refresh against the
+// vendor's endpoint — with RegisterRefresher. Until then a refresh on it is refused, naming Phase C.
 var registry = map[string]Shape{
-	"anthropic": StaticKey,
+	"anthropic":         RefreshableGrant,
+	"anthropic-api-key": StaticKey,
 }
 
 // For returns the adapter for a vendor, refusing an unknown one clearly.
@@ -115,12 +180,15 @@ func For(vendor string) (Adapter, error) {
 	switch shape {
 	case StaticKey:
 		return staticKey{vendor: vendor}, nil
+	case RefreshableGrant:
+		// The generic refreshable-grant adapter, carrying whatever VendorRefresher has been plugged
+		// in for this vendor — nil in this build, which a refresh reports rather than hides.
+		return refreshableGrant{vendor: vendor, refresher: refresherFor(vendor)}, nil
 	default:
-		// A vendor registered with a shape this build does not implement yet — the refreshable-grant
-		// seam. Said plainly rather than answered with a static-key adapter that would silently
-		// mishandle it.
+		// A shape this build has no adapter for at all. Said plainly rather than answered with an
+		// adapter that would silently mishandle it.
 		return nil, fmt.Errorf(
-			"the vendor %q needs a %s adapter, which this build does not ship yet", vendor, shape)
+			"the vendor %q has shape %q, which this build has no adapter for", vendor, shape)
 	}
 }
 
@@ -153,3 +221,48 @@ func (s staticKey) Accept(value, consumerKey, providerKey string) (secrets.Seale
 // unchanged — there is no vendor step between the store and the node, and the mesh never sees the
 // plaintext.
 func (s staticKey) Deliver(sealed string) string { return sealed }
+
+// refreshableGrant is the adapter for a vendor whose credential is an OAuth-style grant a manager
+// node refreshes centrally (novox/hq ADR 0050). It is vendor-neutral: the generic half — the shape
+// that gates the carve-out, the per-holder seal of an access token, delivery that carries only an
+// access token, and the dispatch of a refresh to a plugged-in VendorRefresher — lives here; the
+// vendor's actual OAuth call is the injected refresher.
+//
+// **What makes this the carve-out and not a second static key.** The refresh token never touches
+// this adapter and never touches a holder. It lives in the licences context's own at-rest store,
+// keyed by licence, encrypted to the manager node (secrets.AtRest). What Accept seals and Deliver
+// hands out is the ACCESS token, per holder, exactly as a static key's value is — so "the refresh
+// token is stripped on delivery" is structural here: there is nothing in a holder's row to strip,
+// because the refresh token was never put there.
+type refreshableGrant struct {
+	vendor    string
+	refresher VendorRefresher
+}
+
+func (r refreshableGrant) Vendor() string { return r.vendor }
+func (r refreshableGrant) Shape() Shape   { return RefreshableGrant }
+
+// Accept seals an access token to one holder — the generic anonymous-box seal, the same as a static
+// key. The refresh token is not accepted here: it is adopted onto the manager node and kept in the
+// at-rest store (ADR 0050, Phase C), never sealed per holder.
+func (r refreshableGrant) Accept(value, consumerKey, providerKey string) (secrets.Sealed, error) {
+	return secrets.Accept(value, consumerKey, providerKey)
+}
+
+// Deliver hands the consumer its sealed ACCESS token, unchanged. There is no refresh token to strip
+// because a holder's row never held one — the stripping is in the shape of the store, not a step
+// here.
+func (r refreshableGrant) Deliver(sealed string) string { return sealed }
+
+// Refresh is the vendor-neutral half of the lease/rotate/publish machinery: it dispatches to the
+// vendor's plugged-in refresher and returns what that produced. The lease, the per-holder reseal and
+// the publish are the licences context's (ADR 0050, Phase B); the OAuth call is the vendor's
+// (Phase C). With nothing plugged in, it refuses in a way that names why.
+func (r refreshableGrant) Refresh(ctx context.Context, in RefreshInput) (RefreshResult, error) {
+	if r.refresher == nil {
+		return RefreshResult{}, fmt.Errorf(
+			"the vendor %q is refreshable-grant but has no refresher plugged in, so its grant "+
+				"cannot be refreshed in this build (novox/hq ADR 0050, Phase C)", r.vendor)
+	}
+	return r.refresher.Refresh(ctx, in)
+}

internal/licences/adapters/adapters_test.go

@@ -0,0 +1,112 @@
+package adapters
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-control/internal/secrets"
+)
+
+func TestTheTwoShapesAreSelectedByVendor(t *testing.T) {
+	static, err := For("anthropic-api-key")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if static.Shape() != StaticKey {
+		t.Fatalf("anthropic-api-key is %q, expected static-key", static.Shape())
+	}
+
+	grant, err := For("anthropic")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if grant.Shape() != RefreshableGrant {
+		t.Fatalf("anthropic is %q, expected refreshable-grant", grant.Shape())
+	}
+}
+
+// The type assertion is what gates the carve-out: a static key is not a Refresher, so it can never
+// reach the machinery that holds a token readably. A refreshable grant is one.
+func TestOnlyARefreshableGrantIsARefresher(t *testing.T) {
+	static, _ := For("anthropic-api-key")
+	if _, ok := static.(Refresher); ok {
+		t.Fatal("a static-key adapter is a Refresher, so the carve-out is not gated by shape")
+	}
+	grant, _ := For("anthropic")
+	if _, ok := grant.(Refresher); !ok {
+		t.Fatal("a refreshable-grant adapter is not a Refresher, so it cannot be refreshed")
+	}
+}
+
+// With nothing plugged in, a refresh is refused in a way that names why — not answered with a
+// silent no-op that would look like a refresh that changed nothing.
+func TestARefreshWithNoRefresherPluggedInIsRefused(t *testing.T) {
+	grant, _ := For("anthropic")
+	r := grant.(Refresher)
+	_, err := r.Refresh(context.Background(), RefreshInput{Licence: "personal"})
+	if err == nil {
+		t.Fatal("a refresh succeeded with no vendor refresher plugged in")
+	}
+	if !strings.Contains(err.Error(), "Phase C") {
+		t.Fatalf("the refusal does not point at the missing plug-in: %v", err)
+	}
+}
+
+type fakeVendor struct {
+	result RefreshResult
+	got    RefreshInput
+}
+
+func (f *fakeVendor) Refresh(_ context.Context, in RefreshInput) (RefreshResult, error) {
+	f.got = in
+	return f.result, nil
+}
+
+// A plugged-in refresher is dispatched to, and is handed the at-rest envelope (never a plaintext
+// refresh token) plus which node is the manager.
+func TestAPluggedInRefresherIsDispatchedTo(t *testing.T) {
+	fake := &fakeVendor{result: RefreshResult{AccessToken: "at-new"}}
+	RegisterRefresher("anthropic", fake)
+	defer RegisterRefresher("anthropic", nil)
+
+	grant, _ := For("anthropic")
+	r := grant.(Refresher)
+	in := RefreshInput{
+		Licence: "personal", Manager: "workstation",
+		AtRest: secrets.AtRest{Token: "tok", WrappedKey: "wk", ManagerKey: "mk"},
+	}
+	out, err := r.Refresh(context.Background(), in)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out.AccessToken != "at-new" {
+		t.Fatalf("the dispatched result did not come back: %q", out.AccessToken)
+	}
+	if fake.got.Manager != "workstation" || fake.got.AtRest.Token != "tok" {
+		t.Fatalf("the refresher was handed the wrong input: %+v", fake.got)
+	}
+}
+
+// A vendor this build has no adapter for is refused, and the refusal lists what it does know so a
+// typo and an unsupported vendor are told apart.
+func TestAnUnknownVendorIsRefusedWithTheList(t *testing.T) {
+	_, err := For("acme-models")
+	if err == nil {
+		t.Fatal("an unknown vendor returned an adapter")
+	}
+	if !strings.Contains(err.Error(), "anthropic") {
+		t.Fatalf("the refusal does not list the known vendors: %v", err)
+	}
+}
+
+// Both shapes deliver their stored blob unchanged: a static key has no vendor step, and a
+// refreshable grant's holder row holds an access token with no refresh token to strip.
+func TestBothShapesDeliverTheStoredBlobUnchanged(t *testing.T) {
+	for _, vendor := range []string{"anthropic", "anthropic-api-key"} {
+		a, _ := For(vendor)
+		if got := a.Deliver("sealed-blob"); got != "sealed-blob" {
+			t.Fatalf("%s changed the delivered blob to %q", vendor, got)
+		}
+	}
+}

internal/licences/licences.go

@@ -21,6 +21,7 @@ import (
 
 	"github.com/jackc/pgx/v5"
 	"github.com/novox/mesh-control/internal/licences/adapters"
+	"github.com/novox/mesh-control/internal/secrets"
 	"github.com/novox/mesh-control/internal/store"
 )
 
@@ -304,6 +305,257 @@ func (l *Licences) Accept(ctx context.Context, licence, value string, keys Seali
 	return sealed, nil
 }
 
+// ManagerOf is the node that holds a licence's refresh token readably, empty if none is named.
+//
+// Empty for every static-key licence, which has nothing to refresh, and for a refreshable-grant one
+// before its manager is set (novox/hq ADR 0050).
+func (l *Licences) ManagerOf(ctx context.Context, licence string) (string, error) {
+	var manager *string
+	err := l.store.Pool().QueryRow(ctx,
+		`select manager from licence where name = $1`, licence).Scan(&manager)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", fmt.Errorf("this mesh has no licence called %q", licence)
+	}
+	if err != nil {
+		return "", err
+	}
+	if manager == nil {
+		return "", nil
+	}
+	return *manager, nil
+}
+
+// SetManager names the one node that holds a licence's refresh token and refreshes it centrally.
+//
+// **Only a refreshable-grant licence has one.** A static-key licence has no refresh token, so naming
+// a manager for it is refused rather than kept — the absent manager is part of what keeps a static
+// key from ever growing a value something holds readably at rest (novox/hq ADR 0050). The bound
+// "the manager node only" starts here, at the one place a manager is written.
+func (l *Licences) SetManager(ctx context.Context, licence, node string) error {
+	if strings.TrimSpace(node) == "" {
+		return errors.New("a manager needs a node")
+	}
+	vendor, err := l.vendorOf(ctx, licence)
+	if err != nil {
+		return err
+	}
+	adapter, err := adapters.For(vendor)
+	if err != nil {
+		return err
+	}
+	if adapter.Shape() != adapters.RefreshableGrant {
+		return fmt.Errorf(
+			"%q is a %s licence; only a refreshable-grant licence has a manager, because only it "+
+				"has a refresh token to hold", licence, adapter.Shape())
+	}
+	tag, err := l.store.Pool().Exec(ctx,
+		`update licence set manager = $2 where name = $1`, licence, node)
+	if err != nil {
+		return err
+	}
+	if tag.RowsAffected() == 0 {
+		return fmt.Errorf("this mesh has no licence called %q", licence)
+	}
+	return nil
+}
+
+// SetRefreshGrant stores, or replaces, a licence's refresh token as its at-rest envelope.
+//
+// **The envelope is opaque here.** It was produced by the manager node — the only place the refresh
+// token is ever in the clear (novox/hq ADR 0050, Phase C) — and this context keeps it and forwards
+// it to a refresh without opening it. The control plane holds no key that could, which is the whole
+// point of where the carve-out draws the line.
+func (l *Licences) SetRefreshGrant(ctx context.Context, licence string, at secrets.AtRest) error {
+	if at.Token == "" || at.WrappedKey == "" || at.ManagerKey == "" {
+		return errors.New("an incomplete refresh-token envelope is not one to keep")
+	}
+	_, err := l.store.Pool().Exec(ctx,
+		`insert into refresh_grant (licence, token, wrapped_key, manager_key)
+		 values ($1, $2, $3, $4)
+		 on conflict (licence) do update set
+		   token = excluded.token, wrapped_key = excluded.wrapped_key,
+		   manager_key = excluded.manager_key, updated_at = now()`,
+		licence, at.Token, at.WrappedKey, at.ManagerKey)
+	if err != nil && strings.Contains(err.Error(), "refresh_grant_licence_fkey") {
+		return fmt.Errorf("this mesh has no licence called %q", licence)
+	}
+	return err
+}
+
+// RefreshGrant is a licence's refresh token as its at-rest envelope, and whether one is stored.
+func (l *Licences) RefreshGrant(ctx context.Context, licence string) (secrets.AtRest, bool, error) {
+	var at secrets.AtRest
+	err := l.store.Pool().QueryRow(ctx,
+		`select token, wrapped_key, manager_key from refresh_grant where licence = $1`, licence).
+		Scan(&at.Token, &at.WrappedKey, &at.ManagerKey)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return secrets.AtRest{}, false, nil
+	}
+	if err != nil {
+		return secrets.AtRest{}, false, err
+	}
+	return at, true, nil
+}
+
+// Refresh mints a new access token for a refreshable-grant licence, seals it to every holder, and
+// leaves the refresh token where it is — re-encrypted at rest if the vendor rotated it too.
+//
+// **The lease.** One refresh of a licence at a time, held as a transaction-scoped advisory lock on
+// the licence: two refreshes serialise rather than both minting a token and racing to publish. This
+// is doc 13's single-actor rotation lease, expressed against the database that is the source of
+// truth (novox/hq ADR 0003) rather than reinvented.
+//
+// **It reuses rotation's reseal-and-publish, not its value source.** doc 13's rotate discards a
+// mesh-minted secret and regenerates it; here the new access token comes from the vendor refresh
+// instead, and is then sealed per holder (secrets.Seal, exactly as Accept does) and delivered on the
+// next push — the same publish path any credential change takes. The refresh token is never sealed
+// to a holder, so `KeyFor` cannot deliver it.
+//
+// **All or nothing.** The reseal, the grant replacement and the lease are one transaction: a refresh
+// that cannot finish leaves every holder on the token it had and the stored grant untouched — a
+// licence that has not refreshed, which is far better than one half refreshed (doc 13).
+//
+// The vendor refresh itself is the injected VendorRefresher (novox/hq ADR 0050, Phase C); with none
+// plugged in, the adapter refuses here and nothing is changed.
+func (l *Licences) Refresh(ctx context.Context, licence string, keys SealingKeys) (int, error) {
+	tx, err := l.store.Pool().Begin(ctx)
+	if err != nil {
+		return 0, err
+	}
+	defer func() { _ = tx.Rollback(context.WithoutCancel(ctx)) }()
+
+	// The lease. Released when the transaction ends, either way.
+	if _, err := tx.Exec(ctx,
+		`select pg_advisory_xact_lock(hashtext($1)::bigint)`, licence); err != nil {
+		return 0, fmt.Errorf("cannot take the refresh lease on %q: %w", licence, err)
+	}
+
+	var vendor string
+	var manager *string
+	err = tx.QueryRow(ctx,
+		`select vendor, manager from licence where name = $1`, licence).Scan(&vendor, &manager)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return 0, fmt.Errorf("this mesh has no licence called %q", licence)
+	}
+	if err != nil {
+		return 0, err
+	}
+
+	adapter, err := adapters.For(vendor)
+	if err != nil {
+		return 0, err
+	}
+	refresher, ok := adapter.(adapters.Refresher)
+	if !ok {
+		// The type assertion is what gates the carve-out to refreshable-grant vendors: a static key
+		// is not a Refresher, so it can never reach the machinery that holds a token readably.
+		return 0, fmt.Errorf(
+			"%q is a %s licence and cannot be refreshed; only a refreshable-grant licence has a "+
+				"refresh token", licence, adapter.Shape())
+	}
+	if manager == nil || *manager == "" {
+		return 0, fmt.Errorf(
+			"%q has no manager named, so there is no node to refresh it. Name one:\n"+
+				"  licence manager %s <node>", licence, licence)
+	}
+
+	var at secrets.AtRest
+	err = tx.QueryRow(ctx,
+		`select token, wrapped_key, manager_key from refresh_grant where licence = $1`, licence).
+		Scan(&at.Token, &at.WrappedKey, &at.ManagerKey)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return 0, fmt.Errorf(
+			"%q has no refresh token stored yet; its manager %s adopts one first "+
+				"(novox/hq ADR 0050, Phase C)", licence, *manager)
+	}
+	if err != nil {
+		return 0, err
+	}
+
+	result, err := refresher.Refresh(ctx,
+		adapters.RefreshInput{Licence: licence, Manager: *manager, AtRest: at})
+	if err != nil {
+		return 0, err
+	}
+	if strings.TrimSpace(result.AccessToken) == "" {
+		return 0, fmt.Errorf(
+			"the refresh produced no access token for %q, so nothing was resealed", licence)
+	}
+
+	// Reseal the new access token to the holders that exist now — the same set Accept seals to — and
+	// keep no readable copy.
+	holders, err := holdersTx(ctx, tx, licence)
+	if err != nil {
+		return 0, err
+	}
+	sealed := 0
+	for _, h := range holders {
+		key, err := keys(h.Node)
+		if err != nil {
+			return 0, err
+		}
+		if key == "" {
+			return 0, fmt.Errorf(
+				"%s has no sealing key, so the new access token cannot be sealed to it", h.Node)
+		}
+		blob, err := secrets.Seal(key, []byte(result.AccessToken))
+		if err != nil {
+			return 0, err
+		}
+		if _, err := tx.Exec(ctx,
+			`update licence_holder set sealed = $4, node_key = $5
+			  where licence = $1 and node = $2 and module = $3`,
+			h.Licence, h.Node, h.Module, blob, key); err != nil {
+			return 0, err
+		}
+		sealed++
+	}
+
+	// The refresh token stays put unless the vendor rotated it, in which case the refresher returned
+	// it already re-encrypted at rest — replaced here without ever being seen in the clear.
+	if result.NewAtRest != nil {
+		if result.NewAtRest.Token == "" || result.NewAtRest.WrappedKey == "" ||
+			result.NewAtRest.ManagerKey == "" {
+			return 0, fmt.Errorf(
+				"the refresh returned an incomplete re-sealed refresh token for %q", licence)
+		}
+		if _, err := tx.Exec(ctx,
+			`update refresh_grant set token = $2, wrapped_key = $3, manager_key = $4, updated_at = now()
+			  where licence = $1`,
+			licence, result.NewAtRest.Token, result.NewAtRest.WrappedKey,
+			result.NewAtRest.ManagerKey); err != nil {
+			return 0, err
+		}
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return 0, err
+	}
+	return sealed, nil
+}
+
+// holdersTx reads a licence's holders inside a transaction, so the reseal set is consistent under
+// the refresh lease.
+func holdersTx(ctx context.Context, tx pgx.Tx, licence string) ([]Holder, error) {
+	rows, err := tx.Query(ctx,
+		`select licence, node, module, coalesce(sealed, '') from licence_holder
+		  where licence = $1 order by node, module`, licence)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var out []Holder
+	for rows.Next() {
+		var h Holder
+		if err := rows.Scan(&h.Licence, &h.Node, &h.Module, &h.Sealed); err != nil {
+			return nil, err
+		}
+		out = append(out, h)
+	}
+	return out, rows.Err()
+}
+
 // Names is every licence's name, sorted — what a refusal lists when a consumer has not chosen.
 func Names(all []Licence) []string {
 	out := make([]string, 0, len(all))

internal/licences/migrations/0001-a-licence-is-a-named-thing.sql

@@ -19,6 +19,12 @@ create table licence (
     -- What a consumer needs to know that is not secret -- a base URL, a model name. The key is
     -- never here.
     serves   jsonb       not null default '{}'::jsonb,
+    -- The one node that holds this licence's refresh token readably, and refreshes it (novox/hq
+    -- ADR 0050's carve-out). Null for a static-key licence, which has nothing to refresh and no
+    -- manager -- and the null is the check that a static key never grows a readable-at-rest value.
+    -- A name, not a foreign key: nodes live in another context this one may not join across
+    -- (novox/hq ADR 0008).
+    manager  text,
     added_at timestamptz not null default now()
 );
 
@@ -41,3 +47,33 @@ create table licence_holder (
     added_at timestamptz not null default now(),
     primary key (licence, node, module)
 );
+
+-- The refresh token, encrypted at rest under the manager node's key.
+--
+-- **novox/hq ADR 0050's carve-out, and its one home.** A `refreshable-grant` licence cannot be both
+-- sealed so the mesh cannot read it and rotated centrally, because rotating means a node reads the
+-- refresh token back. So exactly one node -- the licence's manager -- holds it readably, and it is
+-- kept here as an envelope only that node can open: a symmetric data key encrypts the token
+-- (secretbox), and the data key is sealed to the manager's public key. This database on its own
+-- holds ciphertext and a wrapped key with no private half to open either (novox/hq ADR 0004).
+--
+-- **Separate from the access tokens.** licence_holder.sealed is the ACCESS token, sealed per holder
+-- and delivered. This is the REFRESH token, one per licence, never delivered to anybody. Keeping
+-- them in different tables is what makes "the refresh token is stripped on delivery" structural:
+-- delivery reads licence_holder, and the refresh token is not in it.
+create table refresh_grant (
+    -- One refresh token per licence. On delete cascade: forgetting a licence forgets its refresh
+    -- token with it, the same way it forgets its holders.
+    licence     text primary key references licence(name) on delete cascade,
+
+    -- base64( nonce || secretbox(data_key, refresh_token) ) -- the token under the symmetric key.
+    token       text not null,
+    -- base64( anonymous-box(manager_key, data_key) ) -- the data key closed to the manager node.
+    wrapped_key text not null,
+    -- The manager's public sealing key the data key was wrapped to. Kept so a manager that
+    -- regenerated its key can be told it can no longer open this, rather than discovering it as a
+    -- refresh that will not decrypt (the same reason licence_holder.node_key is kept).
+    manager_key text not null,
+
+    updated_at  timestamptz not null default now()
+);

internal/licences/migrations/0003-a-manager-and-its-refresh-token.sql

@@ -0,0 +1,19 @@
+-- A manager, and the refresh token it holds encrypted at rest.
+--
+-- novox/hq ADR 0050, Phase B. The consolidated schema (0001) now creates the `manager` column and
+-- the `refresh_grant` table; this migration carries an existing database the same distance, so a
+-- database that predates the carve-out gains exactly what a fresh one is created with.
+--
+-- **Guarded, so it is a no-op on a database created after 0001 was updated.** A fresh database
+-- already has both, and re-adding them would fail; `if not exists` on both makes the two paths --
+-- fresh and pre-existing -- end at the same schema.
+
+alter table licence add column if not exists manager text;
+
+create table if not exists refresh_grant (
+    licence     text primary key references licence(name) on delete cascade,
+    token       text not null,
+    wrapped_key text not null,
+    manager_key text not null,
+    updated_at  timestamptz not null default now()
+);

internal/licences/refresh_test.go

@@ -0,0 +1,331 @@
+package licences
+
+import (
+	"context"
+	"crypto/ecdh"
+	"crypto/rand"
+	"encoding/base64"
+	"strings"
+	"testing"
+
+	"golang.org/x/crypto/nacl/box"
+
+	"github.com/novox/mesh-control/internal/licences/adapters"
+	"github.com/novox/mesh-control/internal/secrets"
+)
+
+// nodeKeyPair is a node's key as the node would hold it: the public half the mesh seals to, and an
+// open closure holding the private half the mesh never sees.
+func nodeKeyPair(t *testing.T) (public string, open func(string) ([]byte, error)) {
+	t.Helper()
+	priv, err := ecdh.X25519().GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var pub, sk [32]byte
+	copy(pub[:], priv.PublicKey().Bytes())
+	copy(sk[:], priv.Bytes())
+	return base64.StdEncoding.EncodeToString(priv.PublicKey().Bytes()),
+		func(sealed string) ([]byte, error) {
+			blob, err := base64.StdEncoding.DecodeString(sealed)
+			if err != nil {
+				return nil, err
+			}
+			out, ok := box.OpenAnonymous(nil, blob, &pub, &sk)
+			if !ok {
+				return nil, context.Canceled // any error; the test only checks success/failure
+			}
+			return out, nil
+		}
+}
+
+// managerPair is like nodeKeyPair but also returns the private key string, because the manager needs
+// to OpenAtRest its own refresh token — the one node that reads it back.
+func managerPair(t *testing.T) (public, private string) {
+	t.Helper()
+	priv, err := ecdh.X25519().GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return base64.StdEncoding.EncodeToString(priv.PublicKey().Bytes()),
+		base64.StdEncoding.EncodeToString(priv.Bytes())
+}
+
+type fakeRefresher struct {
+	access    string
+	newAtRest *secrets.AtRest
+	got       adapters.RefreshInput
+}
+
+func (f *fakeRefresher) Refresh(_ context.Context, in adapters.RefreshInput) (adapters.RefreshResult, error) {
+	f.got = in
+	return adapters.RefreshResult{AccessToken: f.access, NewAtRest: f.newAtRest}, nil
+}
+
+// A refreshable-grant licence set up end to end: a manager, a refresh token sealed at rest to it, two
+// holders each with a sealing key, and a fake vendor refresher plugged in.
+func aRefreshableLicence(t *testing.T, held *Licences, ctx context.Context, fake *fakeRefresher) (
+	managerPub, managerPriv string, holders map[string]func(string) ([]byte, error), keys SealingKeys,
+) {
+	t.Helper()
+	adapters.RegisterRefresher("anthropic", fake)
+	t.Cleanup(func() { adapters.RegisterRefresher("anthropic", nil) })
+
+	if err := held.Add(ctx, "personal", "anthropic", map[string]any{"model": "a-model"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := held.SetManager(ctx, "personal", "workstation"); err != nil {
+		t.Fatal(err)
+	}
+
+	managerPub, managerPriv = managerPair(t)
+	at, err := secrets.SealAtRest("rt-the-refresh-token", managerPub)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := held.SetRefreshGrant(ctx, "personal", at); err != nil {
+		t.Fatal(err)
+	}
+
+	holders = map[string]func(string) ([]byte, error){}
+	pub := map[string]string{}
+	for _, node := range []string{"workstation", "laptop"} {
+		p, open := nodeKeyPair(t)
+		pub[node], holders[node] = p, open
+		if err := held.Use(ctx, "personal", node, "assistant"); err != nil {
+			t.Fatal(err)
+		}
+	}
+	keys = func(node string) (string, error) { return pub[node], nil }
+	return managerPub, managerPriv, holders, keys
+}
+
+// The point of the phase, in one test: a refresh seals the ACCESS token to every holder, and the
+// refresh token is nowhere a holder can reach it.
+func TestARefreshDeliversTheAccessTokenAndNeverTheRefreshToken(t *testing.T) {
+	held, ctx := fresh(t)
+	fake := &fakeRefresher{access: "at-brand-new-access-token"}
+	_, _, holders, keys := aRefreshableLicence(t, held, ctx, fake)
+
+	sealed, err := held.Refresh(ctx, "personal", keys)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sealed != 2 {
+		t.Fatalf("%d holder(s) were resealed, expected 2", sealed)
+	}
+
+	for node, open := range holders {
+		blob, err := held.KeyFor(ctx, "personal", node, "assistant")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if blob == "" {
+			t.Fatalf("%s got no access token", node)
+		}
+		got, err := open(blob)
+		if err != nil {
+			t.Fatalf("%s cannot open what it was delivered", node)
+		}
+		if string(got) != "at-brand-new-access-token" {
+			t.Fatalf("%s was delivered %q, not the access token", node, got)
+		}
+		// The refresh token is not in the holder's delivery, opened or sealed.
+		if string(got) == "rt-the-refresh-token" || strings.Contains(blob, "rt-the-refresh-token") {
+			t.Fatalf("%s was delivered the refresh token", node)
+		}
+	}
+}
+
+// KeyFor delivers the access token and cannot deliver the refresh token, because the refresh token
+// is not in licence_holder at all — the stripping is structural.
+func TestKeyForNeverCarriesTheRefreshToken(t *testing.T) {
+	held, ctx := fresh(t)
+	fake := &fakeRefresher{access: "at-access"}
+	_, _, _, keys := aRefreshableLicence(t, held, ctx, fake)
+	if _, err := held.Refresh(ctx, "personal", keys); err != nil {
+		t.Fatal(err)
+	}
+
+	// Every holder row, straight from the store: none of them holds the refresh token in any form.
+	rows, err := held.store.Pool().Query(ctx,
+		`select coalesce(sealed, '') from licence_holder where licence = 'personal'`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var sealed string
+		if err := rows.Scan(&sealed); err != nil {
+			t.Fatal(err)
+		}
+		if strings.Contains(sealed, "rt-the-refresh-token") {
+			t.Fatal("a holder row carries the refresh token")
+		}
+	}
+}
+
+// The refresh token at rest is not readable from the database alone: the row holds ciphertext and a
+// wrapped key, and only the manager node's private half opens it.
+func TestTheRefreshTokenAtRestNeedsTheManagersKey(t *testing.T) {
+	held, ctx := fresh(t)
+	fake := &fakeRefresher{access: "at-access"}
+	managerPub, managerPriv, _, _ := aRefreshableLicence(t, held, ctx, fake)
+
+	// What the database holds, read straight from the row.
+	var token, wrapped, managerKey string
+	if err := held.store.Pool().QueryRow(ctx,
+		`select token, wrapped_key, manager_key from refresh_grant where licence = 'personal'`).
+		Scan(&token, &wrapped, &managerKey); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(token, "rt-the-refresh-token") || strings.Contains(wrapped, "rt-the-refresh-token") {
+		t.Fatal("the refresh token is in the row in the clear")
+	}
+
+	// The manager, holding its private key, reads it back.
+	got, err := secrets.OpenAtRest(
+		secrets.AtRest{Token: token, WrappedKey: wrapped, ManagerKey: managerKey},
+		managerPub, managerPriv)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != "rt-the-refresh-token" {
+		t.Fatalf("the manager read back %q", got)
+	}
+
+	// Another node cannot, which is the whole of "the manager node only".
+	otherPub, otherPriv := managerPair(t)
+	if _, err := secrets.OpenAtRest(
+		secrets.AtRest{Token: token, WrappedKey: wrapped, ManagerKey: managerKey},
+		otherPub, otherPriv); err == nil {
+		t.Fatal("a node that is not the manager opened the refresh token")
+	}
+}
+
+// After a refresh, holders hold a NEW access token, and the refresh token that was not rotated is
+// unchanged — never delivered either way.
+func TestAfterRefreshHoldersHoldANewAccessTokenAndTheGrantIsUnchanged(t *testing.T) {
+	held, ctx := fresh(t)
+	fake := &fakeRefresher{access: "at-first"}
+	_, _, holders, keys := aRefreshableLicence(t, held, ctx, fake)
+
+	// A prior access token, so we can see it change.
+	if _, err := held.Refresh(ctx, "personal", keys); err != nil {
+		t.Fatal(err)
+	}
+	before := map[string]string{}
+	for node := range holders {
+		blob, err := held.KeyFor(ctx, "personal", node, "assistant")
+		if err != nil {
+			t.Fatal(err)
+		}
+		before[node] = blob
+	}
+	grantBefore := grantRow(t, held, ctx)
+
+	// A second refresh with a different access token and no rotation of the refresh token.
+	fake.access = "at-second"
+	if _, err := held.Refresh(ctx, "personal", keys); err != nil {
+		t.Fatal(err)
+	}
+	for node, open := range holders {
+		blob, err := held.KeyFor(ctx, "personal", node, "assistant")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if blob == before[node] {
+			t.Fatalf("%s was not given a new sealed access token", node)
+		}
+		got, err := open(blob)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if string(got) != "at-second" {
+			t.Fatalf("%s holds %q, not the new access token", node, got)
+		}
+	}
+	if grantRow(t, held, ctx) != grantBefore {
+		t.Fatal("the refresh token changed although the vendor did not rotate it")
+	}
+}
+
+// When the vendor rotates the refresh token too, the stored envelope is replaced with the
+// re-encrypted one — and it is still not deliverable to a holder.
+func TestARotatedRefreshTokenReplacesTheStoredEnvelope(t *testing.T) {
+	held, ctx := fresh(t)
+	fake := &fakeRefresher{access: "at-access"}
+	managerPub, managerPriv, _, keys := aRefreshableLicence(t, held, ctx, fake)
+
+	grantBefore := grantRow(t, held, ctx)
+
+	rotated, err := secrets.SealAtRest("rt-a-rotated-refresh-token", managerPub)
+	if err != nil {
+		t.Fatal(err)
+	}
+	fake.newAtRest = &rotated
+	if _, err := held.Refresh(ctx, "personal", keys); err != nil {
+		t.Fatal(err)
+	}
+
+	if grantRow(t, held, ctx) == grantBefore {
+		t.Fatal("the rotated refresh token did not replace the stored envelope")
+	}
+	at, ok, err := held.RefreshGrant(ctx, "personal")
+	if err != nil || !ok {
+		t.Fatalf("the rotated grant is not stored: ok=%v err=%v", ok, err)
+	}
+	got, err := secrets.OpenAtRest(at, managerPub, managerPriv)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != "rt-a-rotated-refresh-token" {
+		t.Fatalf("the stored grant opened to %q, not the rotated token", got)
+	}
+}
+
+// A static-key licence has no refresh token and the carve-out never fires: it has no manager, and it
+// cannot be refreshed.
+func TestAStaticKeyLicenceHasNoManagerAndNoRefresh(t *testing.T) {
+	held, ctx := fresh(t)
+	if err := held.Add(ctx, "plain", "anthropic-api-key", nil); err != nil {
+		t.Fatal(err)
+	}
+	if err := held.SetManager(ctx, "plain", "workstation"); err == nil {
+		t.Fatal("a static-key licence was given a manager")
+	}
+	if _, ok, err := held.RefreshGrant(ctx, "plain"); err != nil || ok {
+		t.Fatalf("a static-key licence has a refresh token stored: ok=%v err=%v", ok, err)
+	}
+	if _, err := held.Refresh(ctx, "plain", func(string) (string, error) { return "", nil }); err == nil {
+		t.Fatal("a static-key licence was refreshed")
+	}
+}
+
+// A refreshable licence with no manager named cannot be refreshed, and says how to name one.
+func TestARefreshableLicenceWithoutAManagerIsRefused(t *testing.T) {
+	held, ctx := fresh(t)
+	if err := held.Add(ctx, "personal", "anthropic", nil); err != nil {
+		t.Fatal(err)
+	}
+	_, err := held.Refresh(ctx, "personal", func(string) (string, error) { return "", nil })
+	if err == nil {
+		t.Fatal("a licence with no manager was refreshed")
+	}
+	if !strings.Contains(err.Error(), "manager") {
+		t.Fatalf("the refusal does not point at the missing manager: %v", err)
+	}
+}
+
+// grantRow is the whole at-rest envelope as one string, for asserting it changed or did not.
+func grantRow(t *testing.T, held *Licences, ctx context.Context) string {
+	t.Helper()
+	at, ok, err := held.RefreshGrant(ctx, "personal")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !ok {
+		return ""
+	}
+	return at.Token + "|" + at.WrappedKey + "|" + at.ManagerKey
+}