carlos / platform Public

claim: the launch source mints the instance key under the guard, syncs it before Establish, gates a replica on its home's key, and names the key it delivers (L21)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Paul Campbell pushed by claude 1 week ago 4a7ee0e607624363762f2db2b5c60f84e812c297 parent 3ab3cbe

7 files changed, +468 −15

internal/activator/claim_instancekey_test.go +112 −0
internal/activator/claim_snapshot.go +65 −12
internal/activator/claimretry_instancekey_linux_test.go +71 −0
internal/activator/replicakey.go +3 −3
internal/host/claim_instancekey_test.go +142 −0
internal/host/claim_replica_instancekey_test.go +62 −0
internal/host/claimowners.go +13 −0

CI passed — run details

CI log

=== gate ===
cd launchctx && go vet ./... && go test ./... -count=1
ok  	amadan.net/carlos/platform.git/launchctx	0.011s
?   	amadan.net/carlos/platform.git/launchctx/controlname	[no test files]
?   	amadan.net/carlos/platform.git/launchctx/wireid	[no test files]
go vet ./...
gofmt -l .: clean
go test ./... -count=1 -timeout 30m
ok  	github.com/carlosframework/platform	315.231s
?   	github.com/carlosframework/platform/cmd/changelog	[no test files]
ok  	github.com/carlosframework/platform/cmd/console	3.085s
ok  	github.com/carlosframework/platform/internal/activator	197.869s
ok  	github.com/carlosframework/platform/internal/agentsock	0.016s
ok  	github.com/carlosframework/platform/internal/alerting	0.003s
ok  	github.com/carlosframework/platform/internal/analytics	0.017s
ok  	github.com/carlosframework/platform/internal/appconfig	2.222s
ok  	github.com/carlosframework/platform/internal/apperr	0.072s
ok  	github.com/carlosframework/platform/internal/applog	0.123s
ok  	github.com/carlosframework/platform/internal/awsinv	0.003s
ok  	github.com/carlosframework/platform/internal/boxchoice	0.004s
ok  	github.com/carlosframework/platform/internal/boxid	0.568s
?   	github.com/carlosframework/platform/internal/boxid/boxidtest	[no test files]
?   	github.com/carlosframework/platform/internal/boxid/internal/signtest	[no test files]
ok  	github.com/carlosframework/platform/internal/boxvolumes	0.008s
ok  	github.com/carlosframework/platform/internal/caps	0.012s
ok  	github.com/carlosframework/platform/internal/certwarm	0.002s
ok  	github.com/carlosframework/platform/internal/cgroup	0.187s
ok  	github.com/carlosframework/platform/internal/changelog	0.244s
ok  	github.com/carlosframework/platform/internal/clamd	0.055s
?   	github.com/carlosframework/platform/internal/cliflag	[no test files]
ok  	github.com/carlosframework/platform/internal/console	320.193s
?   	github.com/carlosframework/platform/internal/controlname	[no test files]
?   	github.com/carlosframework/platform/internal/controlsock	[no test files]
ok  	github.com/carlosframework/platform/internal/dbdoor	6.278s
ok  	github.com/carlosframework/platform/internal/dbdoor/dbdoortest	0.009s
ok  	github.com/carlosframework/platform/internal/dbverify	0.005s
ok  	github.com/carlosframework/platform/internal/dnsrec	0.005s
ok  	github.com/carlosframework/platform/internal/docsite	0.006s
ok  	github.com/carlosframework/platform/internal/domains	1.998s
ok  	github.com/carlosframework/platform/internal/doorkey	0.009s
ok  	github.com/carlosframework/platform/internal/economics	0.004s
ok  	github.com/carlosframework/platform/internal/edge	25.915s
?   	github.com/carlosframework/platform/internal/edgeproof	[no test files]
ok  	github.com/carlosframework/platform/internal/edgesfile	0.006s
ok  	github.com/carlosframework/platform/internal/fleetapi	0.132s
ok  	github.com/carlosframework/platform/internal/gate	1.655s
ok  	github.com/carlosframework/platform/internal/genselect	0.024s
ok  	github.com/carlosframework/platform/internal/geo	0.018s
ok  	github.com/carlosframework/platform/internal/geoip	0.037s
ok  	github.com/carlosframework/platform/internal/host	45.484s
ok  	github.com/carlosframework/platform/internal/hostactors	0.493s
ok  	github.com/carlosframework/platform/internal/hostbox	1.220s
ok  	github.com/carlosframework/platform/internal/hostclaim	0.223s
ok  	github.com/carlosframework/platform/internal/hostevidence	0.007s
ok  	github.com/carlosframework/platform/internal/hostexec	0.302s
ok  	github.com/carlosframework/platform/internal/hostfence	0.043s
ok  	github.com/carlosframework/platform/internal/hostfiles	4.065s
ok  	github.com/carlosframework/platform/internal/hostfloor	0.009s
ok  	github.com/carlosframework/platform/internal/hostguard	0.149s
ok  	github.com/carlosframework/platform/internal/hostops	1.266s
ok  	github.com/carlosframework/platform/internal/hostquarantine	0.016s
ok  	github.com/carlosframework/platform/internal/hostresolve	0.139s
ok  	github.com/carlosframework/platform/internal/hostwrite	0.003s
ok  	github.com/carlosframework/platform/internal/infraview	0.002s
ok  	github.com/carlosframework/platform/internal/instancectl	1.705s
ok  	github.com/carlosframework/platform/internal/instanceexec	2.690s
ok  	github.com/carlosframework/platform/internal/instancefs	0.004s
ok  	github.com/carlosframework/platform/internal/instancekey	0.004s
ok  	github.com/carlosframework/platform/internal/layout	1.339s
ok  	github.com/carlosframework/platform/internal/lease	9.436s
ok  	github.com/carlosframework/platform/internal/lease/leasetest	0.005s
ok  	github.com/carlosframework/platform/internal/ledger	0.012s
ok  	github.com/carlosframework/platform/internal/mail	0.157s
ok  	github.com/carlosframework/platform/internal/maintenance	0.089s
ok  	github.com/carlosframework/platform/internal/maintenanceexec	5.530s
ok  	github.com/carlosframework/platform/internal/maintenanceguard	0.075s
ok  	github.com/carlosframework/platform/internal/metrics	0.005s
ok  	github.com/carlosframework/platform/internal/moves	21.207s
ok  	github.com/carlosframework/platform/internal/moves/archive	0.733s
ok  	github.com/carlosframework/platform/internal/objstore	0.161s
ok  	github.com/carlosframework/platform/internal/ops	0.156s
ok  	github.com/carlosframework/platform/internal/park	0.181s
ok  	github.com/carlosframework/platform/internal/privatefile	0.004s
ok  	github.com/carlosframework/platform/internal/provision	3.062s
ok  	github.com/carlosframework/platform/internal/publicrelease	0.007s
ok  	github.com/carlosframework/platform/internal/registry	3.578s
ok  	github.com/carlosframework/platform/internal/relay	7.230s
ok  	github.com/carlosframework/platform/internal/release	18.248s
ok  	github.com/carlosframework/platform/internal/rollout	1.482s
ok  	github.com/carlosframework/platform/internal/rootaws	0.007s
ok  	github.com/carlosframework/platform/internal/s3compat	0.005s
ok  	github.com/carlosframework/platform/internal/safefile	0.003s
ok  	github.com/carlosframework/platform/internal/schedule	2.209s
ok  	github.com/carlosframework/platform/internal/sim/hostlife	2.419s
ok  	github.com/carlosframework/platform/internal/sim/litestreamfacts	4.211s
ok  	github.com/carlosframework/platform/internal/status	0.039s
ok  	github.com/carlosframework/platform/internal/steering	0.006s
ok  	github.com/carlosframework/platform/internal/stopevidence	0.132s
ok  	github.com/carlosframework/platform/internal/svcrole	0.002s
ok  	github.com/carlosframework/platform/internal/telemetry	0.004s
ok  	github.com/carlosframework/platform/internal/termfence	0.004s
ok  	github.com/carlosframework/platform/internal/tunnelclient	0.004s
ok  	github.com/carlosframework/platform/internal/unixdial	0.003s
ok  	github.com/carlosframework/platform/internal/updatewords	0.002s
ok  	github.com/carlosframework/platform/internal/usage	0.004s
ok  	github.com/carlosframework/platform/internal/version	0.002s
ok  	github.com/carlosframework/platform/internal/vet	1.527s
=== cross ===
--- shard 0 of 5 ---
cross-compiling darwin/arm64
--- shard 1 of 5 ---
cross-compiling darwin/amd64
--- shard 2 of 5 ---
cross-compiling linux/arm64
--- shard 3 of 5 ---
cross-compiling windows/amd64
--- shard 4 of 5 ---
cross-compiling windows/arm64
=== minio-contract ===
minio contract: arm64, minio RELEASE.2025-09-07T16-13-09Z, mc RELEASE.2025-08-13T08-35-41Z
  minio: cached, digest verified
  mc: cached, digest verified
  minio healthy on 127.0.0.1:20999
Added `local` successfully.
Bucket created successfully `local/contract-bucket`.
Bucket created successfully `local/denied-bucket`.
Created policy `contract-only` successfully.
Added user `scopeduser` successfully.
Attached Policies: [contract-only]
To User: scopeduser
  buckets and scoped user ready
=== RUN   TestDeliveredContractMinio
=== RUN   TestDeliveredContractMinio/put
=== RUN   TestDeliveredContractMinio/get_round-trips_the_body
=== RUN   TestDeliveredContractMinio/list_shows_the_key
=== RUN   TestDeliveredContractMinio/head_and_list_agree_on_the_version
=== RUN   TestDeliveredContractMinio/the_app_cannot_tag_its_own_object
=== RUN   TestDeliveredContractMinio/the_app_cannot_tag_its_own_object/not_by_PutObjectTagging
=== RUN   TestDeliveredContractMinio/the_app_cannot_tag_its_own_object/and_not_by_x-amz-tagging_on_upload
=== RUN   TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route
=== RUN   TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/not_by_CreateMultipartUpload
=== RUN   TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/not_by_CopyObject_with_a_REPLACE_tagging_directive
=== RUN   TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/but_multipart_itself_is_allowed
=== RUN   TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/and_copy_itself_is_allowed
=== RUN   TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/a_POST-policy_forged_tag_with_a_matching_version_is_still_not_a_verdict
=== RUN   TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/and_an_ordinary_tagged-with-something-else_upload_is_allowed
=== RUN   TestDeliveredContractMinio/delete_removes_it
=== RUN   TestDeliveredContractMinio/cross-bucket_denial
--- PASS: TestDeliveredContractMinio (0.02s)
    --- PASS: TestDeliveredContractMinio/put (0.00s)
    --- PASS: TestDeliveredContractMinio/get_round-trips_the_body (0.00s)
    --- PASS: TestDeliveredContractMinio/list_shows_the_key (0.00s)
    --- PASS: TestDeliveredContractMinio/head_and_list_agree_on_the_version (0.00s)
    --- PASS: TestDeliveredContractMinio/the_app_cannot_tag_its_own_object (0.00s)
        --- PASS: TestDeliveredContractMinio/the_app_cannot_tag_its_own_object/not_by_PutObjectTagging (0.00s)
        --- PASS: TestDeliveredContractMinio/the_app_cannot_tag_its_own_object/and_not_by_x-amz-tagging_on_upload (0.00s)
    --- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route (0.01s)
        --- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/not_by_CreateMultipartUpload (0.00s)
        --- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/not_by_CopyObject_with_a_REPLACE_tagging_directive (0.00s)
        --- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/but_multipart_itself_is_allowed (0.00s)
        --- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/and_copy_itself_is_allowed (0.00s)
        --- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/a_POST-policy_forged_tag_with_a_matching_version_is_still_not_a_verdict (0.00s)
        --- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/and_an_ordinary_tagged-with-something-else_upload_is_allowed (0.00s)
    --- PASS: TestDeliveredContractMinio/delete_removes_it (0.00s)
    --- PASS: TestDeliveredContractMinio/cross-bucket_denial (0.00s)
PASS
ok  	github.com/carlosframework/platform/internal/objstore	0.023s
=== RUN   TestT4StorageProbeMinio
2026/10/11 16:43:02 moves: T4: STORE: list: operation error S3: ListObjectsV2, https response error StatusCode: 403, RequestID: 18DD874AF315063C, HostID: 7c420053e0fbcd7f41653fdd92ffa2802c903d05303b1aa15adc2e8bb65d183f, api error SignatureDoesNotMatch: The request signature we calculated does not match the signature you provided. Check your key and signing method.
--- PASS: TestT4StorageProbeMinio (0.01s)
PASS
ok  	github.com/carlosframework/platform/internal/host	0.016s
minio contract: PASS

diff --git a/internal/activator/claim_instancekey_test.go b/internal/activator/claim_instancekey_test.go

new file mode 100644

index 000000000..c3323232d

--- /dev/null

+++ b/internal/activator/claim_instancekey_test.go

@@ -0,0 +1,112 @@

+package activator

+import (

+ "context"

+ "errors"

+ "os"

+ "path/filepath"

+ "strings"

+ "testing"

+ "github.com/carlosframework/platform/internal/registry"

+// Finding 2 on the claim path: when the token and the key are already

+// present, EnsureClaimAdminToken writes nothing and calls no authorizer,

+// but it does not answer until the env file and its directory are synced.

+// A file that is not 0600 goes through the authorized write, which sets it.

+func TestEnsureClaimAdminTokenSyncsAPresentKeyBeforeItAnswers(t *testing.T) {

+ probe := probeInstanceKeySync(t)

+ const host = "claim-key.example"

+ b := &ExecBackend{DataDir: t.TempDir()}

+ rt := registry.Route{Host: host, Socket: "/run/carlos/claim-key.sock", DBPath: "/data/claim-key.db"}

+ envPath := filepath.Join(b.DataDir, host+".env")

+ body := "CARLOS_ADMIN_TOKEN=" + strings.Repeat("d", 64) + "\n" + InstanceKeyVar + "=" + strings.Repeat("A", 43) + "=\n"

+ if err := os.WriteFile(envPath, []byte(body), 0o600); err != nil {

+ t.Fatal(err)

+ }

+ authorized := 0

+ authorize := func(_ context.Context, write func() error) error { authorized++; return write() }

+ for _, fail := range []func(error){func(e error) { probe.fileErr = e }, func(e error) { probe.dirErr = e }} {

+ fail(errors.New("injected: EIO"))

+ if err := b.EnsureClaimAdminToken(context.Background(), rt, authorize); err == nil {

+ t.Fatal("the launch source answered while the env file's sync fails")

+ }

+ fail(nil)

+ }

+ before := *probe

+ if err := b.EnsureClaimAdminToken(context.Background(), rt, authorize); err != nil {

+ t.Fatal(err)

+ }

+ if authorized != 0 || probe.file != before.file+1 || probe.dir != before.dir+1 {

+ t.Fatalf("authorized %d, synced file %d dir %d; want 0, 1, 1", authorized, probe.file-before.file, probe.dir-before.dir)

+ }

+ if err := os.Chmod(envPath, 0o644); err != nil {

+ t.Fatal(err)

+ }

+ if err := b.EnsureClaimAdminToken(context.Background(), rt, authorize); err != nil {

+ t.Fatal(err)

+ }

+ if st, _ := os.Stat(envPath); authorized != 1 || st.Mode().Perm() != 0o600 {

+ t.Fatalf("a 0644 file: authorized %d, mode %o; want the guarded path to set 600", authorized, st.Mode().Perm())

+ }

+ if raw, _ := os.ReadFile(envPath); string(raw) != body {

+ t.Fatal("the claim path rewrote the env file")

+ }

+// Pre-flight ruling A: the early return never fails a launch that succeeds

+// today. With no <host>.env at all and both the token and the key supplied

+// by the rendered configuration, there is no file to make durable (a

+// configured key is exempt, ruling 5, and an absent own file is ruling 7's

+// case), so the launch source answers as it did before: no open failure, no

+// authorizer, and no file created.

+func TestEnsureClaimAdminTokenProceedsWithNoOwnEnvFileWhenConfigSuppliesBoth(t *testing.T) {

+ const host = "claim-cfg.example"

+ b := &ExecBackend{DataDir: t.TempDir()}

+ rt := registry.Route{Host: host, Socket: "/run/carlos/claim-cfg.sock", DBPath: "/data/claim-cfg.db"}

+ cfg := "CARLOS_ADMIN_TOKEN=" + strings.Repeat("d", 64) + "\n" + InstanceKeyVar + "=configured\n"

+ if err := os.WriteFile(filepath.Join(b.DataDir, host+".config.env"), []byte(cfg), 0o600); err != nil {

+ t.Fatal(err)

+ }

+ authorized := 0

+ authorize := func(_ context.Context, write func() error) error { authorized++; return write() }

+ if err := b.EnsureClaimAdminToken(context.Background(), rt, authorize); err != nil {

+ t.Fatalf("a launch that succeeds today failed: %v", err)

+ }

+ if _, err := os.Stat(filepath.Join(b.DataDir, host+".env")); !errors.Is(err, os.ErrNotExist) || authorized != 0 {

+ t.Fatalf("the early return wrote: authorized %d, own env file: %v", authorized, err)

+ }

+// The guarded write mints only what the effective env lacks. A token the

+// rendered configuration supplies is present (the launch delivers it), so

+// the guarded path mints the key alone and does not put a second token

+// into the own file above it: only a missing token is minted, as the

+// function has always promised.

+func TestEnsureClaimAdminTokenMintsOnlyTheKeyWhenConfigSuppliesTheToken(t *testing.T) {

+ const host = "claim-cfgtok.example"

+ b := &ExecBackend{DataDir: t.TempDir()}

+ rt := registry.Route{Host: host, Socket: "/run/carlos/claim-cfgtok.sock", DBPath: "/data/claim-cfgtok.db"}

+ tok := strings.Repeat("d", 64)

+ if err := os.WriteFile(filepath.Join(b.DataDir, host+".config.env"), []byte("CARLOS_ADMIN_TOKEN="+tok+"\n"), 0o600); err != nil {

+ t.Fatal(err)

+ }

+ authorized := 0

+ authorize := func(_ context.Context, write func() error) error { authorized++; return write() }

+ if err := b.EnsureClaimAdminToken(context.Background(), rt, authorize); err != nil {

+ t.Fatal(err)

+ }

+ raw, err := os.ReadFile(filepath.Join(b.DataDir, host+".env"))

+ if err != nil {

+ t.Fatalf("the guarded path minted no key: %v", err)

+ }

+ own := parseEnvBytes(raw)

+ if authorized != 1 || !wellFormedInstanceKey(own[InstanceKeyVar]) || own["CARLOS_ADMIN_TOKEN"] != "" {

+ t.Fatalf("authorized %d, own file %q; want one guarded write with a key and no token", authorized, raw)

+ }

+ vars, err := b.instanceEnv(rt)

+ if err != nil || vars["CARLOS_ADMIN_TOKEN"] != tok {

+ t.Fatalf("the launch's token changed: %q, %v", vars["CARLOS_ADMIN_TOKEN"], err)

+ }

diff --git a/internal/activator/claim_snapshot.go b/internal/activator/claim_snapshot.go

index 976b3ecbc..7ef54377c 100644

--- a/internal/activator/claim_snapshot.go

+++ b/internal/activator/claim_snapshot.go

@@ -5,12 +5,14 @@ import (

"crypto/sha256"

"encoding/hex"

"encoding/json"

+ "errors"

"io"

"os"

"path/filepath"

"github.com/carlosframework/platform/internal/cgroup"

"github.com/carlosframework/platform/internal/hostwrite"

+ "github.com/carlosframework/platform/internal/instancekey"

"github.com/carlosframework/platform/internal/registry"

)

@@ -22,6 +24,11 @@ type ClaimLaunchSnapshot struct {

Args, Env []string

Roles []string

Limit cgroup.Limit

+ // InstanceKeySHA256 and InstanceKeySource name the CARLOS_INSTANCE_KEY

+ // Env delivers (its digest) and the file that supplied it

+ // (instancekey.SourcePlatform or SourceConfig); both empty when Env

+ // delivers none. O6 hands them to the process's adoption verb.

+ InstanceKeySHA256, InstanceKeySource string

}

// claimLaunchRoute is the route shape the claim launch path serves.

@@ -31,12 +38,12 @@ func claimLaunchRoute(rt registry.Route) bool {

// EnsureClaimAdminToken is the claim path's half of what startChild and

// seedChild do before reading the env: a first wake has no

-// CARLOS_ADMIN_TOKEN until something mints it, and the claim path never

-// runs the legacy launch preparation. A token already present is left

-// exactly as it is and authorize is not called, so a retry never rotates

-// it. Only a missing token is minted, and only inside authorize, which must

-// run the write under the claim's current serving authority and refuse

-// otherwise. SnapshotClaimLaunch stays read-only.

+// CARLOS_ADMIN_TOKEN and no CARLOS_INSTANCE_KEY until something mints

+// them, and the claim path never runs the legacy launch preparation. A

+// token already present is left exactly as it is, so a retry never rotates

+// it. Only a missing token, or a missing key, is minted, and only inside

+// authorize, which must run the write under the claim's current serving

+// authority and refuse otherwise. SnapshotClaimLaunch stays read-only.

func (b *ExecBackend) EnsureClaimAdminToken(ctx context.Context, rt registry.Route, authorize func(context.Context, func() error) error) error {

if ctx.Err() != nil {

return ctx.Err()

@@ -51,18 +58,50 @@ func (b *ExecBackend) EnsureClaimAdminToken(ctx context.Context, rt registry.Rou

if err != nil {

return err

}

- if vars["CARLOS_ADMIN_TOKEN"] != "" {

- return nil

+ // The instance key is initialized the same way and in the same

+ // authorized write (L21). vars is the effective env, so a key the

+ // rendered configuration supplies counts as present, and a replica

+ // gets none (ruling 26). When both are present nothing is written and

+ // authorize is not called, but the file is still made durable before

+ // the launch source answers: a key whose mint failed its sync is never

+ // launched with until a sync succeeds (settleClaimInstanceEnv, ruling

+ // 18). A file that needs its mode set takes the guarded path, which

+ // sets it.

+ if vars["CARLOS_ADMIN_TOKEN"] != "" && (rt.Replica || vars[InstanceKeyVar] != "") {

+ err := b.settleClaimInstanceEnv(rt)

+ switch {

+ case err == nil:

+ return nil

+ case errors.Is(err, os.ErrNotExist):

+ // No own env file: the token and the key both come from the

+ // rendered configuration. A configured key is the app's and

+ // is not the platform's to make durable (ruling 5), and an

+ // absent file is not created here (ruling 7), so the launch

+ // proceeds as it did before the key existed.

+ return nil

+ case !errors.Is(err, errInstanceEnvNeedsWrite):

+ return err

+ }

}

if authorize == nil {

return hostwrite.ErrUnavailable

}

paths := b.pathsFor(rt)

return authorize(ctx, func() error {

- if paths.layout == LayoutNested {

- return EnsureAdminTokenBeneath(paths.dataDir, rt.Host+".env")

+ // Only a missing token is minted: one the rendered configuration

+ // supplies is the one the launch delivers, and a second one in the

+ // own file would shadow it.

+ if vars["CARLOS_ADMIN_TOKEN"] == "" {

+ if paths.layout == LayoutNested {

+ if err := EnsureAdminTokenBeneath(paths.dataDir, rt.Host+".env"); err != nil {

+ return err

+ }

+ } else if err := EnsureAdminToken(paths.envFile); err != nil {

+ return err

+ }

}

- return EnsureAdminToken(paths.envFile)

+ _, err := b.ensureInstanceKeyFor(rt, paths)

+ return err

})

}

@@ -77,13 +116,27 @@ func (b *ExecBackend) SnapshotClaimLaunch(ctx context.Context, rt registry.Route

if err := b.claimLaunchShape(rt); err != nil {

return out, err

}

- vars, err := b.instanceEnv(rt)

+ cfgEnv, ownEnv, err := b.instanceEnvParts(rt)

if err != nil {

return out, err

}

+ vars := mergeEnv(cfgEnv, ownEnv) // instanceEnv, with its two layers kept

if vars["CARLOS_ADMIN_TOKEN"] == "" {

return out, hostwrite.ErrUnavailable

}

+ // The key this launch delivers and the file that supplied it, from

+ // the same read as vars: what the replica gate decides on (ruling 29)

+ // and what the process's adoption report is checked against (ruling

+ // 21, O6). Not in the identity: the env already is.

+ key, layer := instancekey.Effective(cfgEnv, ownEnv)

+ // A claim launch has no control socket until O6, so a replica is

+ // selected only with its home's key, verified (ruling 26).

+ if err := b.replicaKeyGate(rt, vars, layer, false); err != nil {

+ return out, err

+ }

+ if key != "" {

+ out.InstanceKeySHA256, out.InstanceKeySource = instancekey.Digest(key), instancekey.SourceOf(layer)

+ }

out.Executable = b.liveLink(rt.Host)

f, err := os.Open(out.Executable)

if err != nil {

diff --git a/internal/activator/claimretry_instancekey_linux_test.go b/internal/activator/claimretry_instancekey_linux_test.go

new file mode 100644

index 000000000..c29cc11b6

--- /dev/null

+++ b/internal/activator/claimretry_instancekey_linux_test.go

@@ -0,0 +1,71 @@

+//go:build linux

+package activator

+import (

+ "context"

+ "errors"

+ "os/exec"

+ "slices"

+ "sync"

+ "testing"

+ "time"

+ "github.com/carlosframework/platform/internal/hostclaim"

+ "github.com/carlosframework/platform/internal/hostwrite"

+ "github.com/carlosframework/platform/internal/registry"

+// Open question 5's premise, corrected (instance-key plan rev 2): on a

+// claim box a session's process retries do not go back to the launch

+// source, which is where the key is minted. Prepare runs once per

+// admitted session and captures the launch inputs, and every attempt

+// calls Materialize (the C8 provider's Establish) before it reserves a

+// start. So no attempt runs with a key minted after the files manifest

+// was established. This pins that shape of startAdmitted: one Prepare,

+// and Materialize before each attempt's start.

+func TestStartAdmittedRetriesReuseTheirInputsAndMaterializeFirst(t *testing.T) {

+ var (

+ mu sync.Mutex

+ events []string

+ prepares int

+ )

+ note := func(e string) { mu.Lock(); events = append(events, e); mu.Unlock() }

+ obs := hostclaim.Observed{Host: "x.example", ETag: "one", Claim: &hostclaim.Claim{Holder: &hostclaim.Holder{Location: "instances/x.example/inc", Session: 1, Generation: "one"}, Op: hostclaim.Op{Kind: "landing", ID: "op", Phase: "probing", Exec: "box"}}}

+ work, _ := (hostwrite.Config{}).Select(t.Context(), obs.Host, "spawn")

+ a := &Service{cfg: Config{HostWrites: hostwrite.Config{Enabled: true}, Claims: &ClaimRuntime{Box: "box", Read: func(context.Context, string) (hostclaim.Observed, error) { return obs, nil }, Prepare: func(context.Context, registry.Route, hostclaim.Observed, startPolicy) (ClaimStart, error) {

+ mu.Lock()

+ prepares++

+ mu.Unlock()

+ return ClaimStart{RoleLauncher: &RoleLaunch{}, CurrentAttempt: func() hostclaim.WakeRetryAttempt { return hostclaim.WakeRetryAttempt{} }, Host: obs.Host, Work: work, Identity: hostwrite.Identity{Config: "c", Release: "r"},

+ OpenProbe: func(context.Context, time.Time) (time.Time, error) {

+ return time.Time{}, errors.New("unreachable while Start refuses")

+ },

+ Restore: func(context.Context) error { note("restore"); return nil },

+ Materialize: func(context.Context) error {

+ note("materialize")

+ return nil

+ },

+ Build: func() *exec.Cmd { return nil },

+ Ready: func(context.Context, *exec.Cmd) error { return nil },

+ Reserve: func(context.Context, int) error { note("reserve"); return nil },

+ Failed: func(context.Context, int) error { note("failed"); return nil },

+ Healthy: func(context.Context, int, *exec.Cmd) error { return nil },

+ Replicate: func(context.Context, string) (Rep, error) { return nil, nil },

+ Publish: func(context.Context, hostclaim.Observed) (hostclaim.Observed, error) { return obs, nil },

+ Retain: func(Proc, Rep, error) {},

+ }, nil

+ }}}}

+ // Two starts: the first refused (RoleLaunch.Start refuses until claim

+ // Plan 9 Group D), a 1 s backoff, then the second.

+ err := a.startAdmitted(t.Context(), &actEntry{host: obs.Host}, obs, startPolicy{MaxStarts: 2, Window: 30 * time.Second, Deadline: time.Now().Add(time.Minute), Probe: true})

+ if !errors.Is(err, ErrClaimIsolationUnavailable) {

+ t.Fatalf("the loop should end on the last start's refusal: %v", err)

+ }

+ want := []string{"restore", "reserve", "materialize", "failed", "reserve", "materialize", "failed"}

+ mu.Lock()

+ defer mu.Unlock()

+ if prepares != 1 || !slices.Equal(events, want) {

+ t.Fatalf("prepares %d, events %v; want 1 and %v", prepares, events, want)

+ }

diff --git a/internal/activator/replicakey.go b/internal/activator/replicakey.go

index 17da24047..d171798b4 100644

--- a/internal/activator/replicakey.go

+++ b/internal/activator/replicakey.go

@@ -6,9 +6,9 @@ package activator

// platform never mints one on a replica row (ensureInstanceKeyFor), and

// every replica launch passes replicaKeyGate before anything runs: the

// flat seed and spawn (seedChild, spawnChildFrom), the nested run, seed

-// and sidecar roles (prepareAt), the worker (StartWorkerStaged) and the

-// legacy co-spawned sidecar (startSidecarChildFrom). The claim launch's

-// snapshot is gated by its own task (Task 4).

+// and sidecar roles (prepareAt), the worker (StartWorkerStaged), the

+// legacy co-spawned sidecar (startSidecarChildFrom) and the claim launch's

+// snapshot (SnapshotClaimLaunch, which has no control socket until O6).

// - a replica whose env files deliver a key starts only when that key's

// digest is its entry in the box's verified list (ReplicaHomeKeys, which

diff --git a/internal/host/claim_instancekey_test.go b/internal/host/claim_instancekey_test.go

new file mode 100644

index 000000000..733ab21ee

--- /dev/null

+++ b/internal/host/claim_instancekey_test.go

@@ -0,0 +1,142 @@

+package host

+import (

+ "context"

+ "os"

+ "path/filepath"

+ "strings"

+ "testing"

+ "time"

+ "github.com/carlosframework/platform/internal/activator"

+ "github.com/carlosframework/platform/internal/hostclaim"

+ "github.com/carlosframework/platform/internal/hostwrite"

+ "github.com/carlosframework/platform/internal/instancekey"

+ "github.com/carlosframework/platform/internal/lease/leasetest"

+// keyCapturingFiles is a C8 provider that records the instance's own env

+// file as it stands when Establish runs: the moment the provider must

+// publish it (ruling 6).

+type keyCapturingFiles struct {

+ path string

+ seen []byte

+func (k *keyCapturingFiles) Establish(ctx context.Context, o hostclaim.Observed, in ClaimLaunchInputs, work hostwrite.Work) error {

+ raw, err := os.ReadFile(k.path)

+ k.seen = raw

+ return err

+type keyTestMarkers struct{}

+func (keyTestMarkers) PutMarker(context.Context, string, string, []byte, string, func(context.Context) error) (string, error) {

+ return "v1", nil

+type passWork struct{}

+func (passWork) With(_ context.Context, _ hostwrite.Identity, fn func() error) error { return fn() }

+// The claim's first wake mints the key in Select (the launch source), so

+// the env file the C8 provider publishes in Materialize already carries it,

+// and the launch env the app will run with carries the same value.

+func TestClaimFirstWakeKeyIsOnDiskBeforeTheFilesManifest(t *testing.T) {

+ f := newAdminTokenFixture(t, "box-1")

+ files := &keyCapturingFiles{path: f.envPath()}

+ owners := &claimServingOwners{Data: leasetest.NewVersionedBucket(), Bucket: "data", Region: "ie", Box: "box-1",

+ NewID: func() string { return "g1" }, Now: func() time.Time { return time.Date(2026, 10, 10, 9, 0, 0, 0, time.UTC) },

+ Sources: ClaimServingSources{Launch: claimServingLaunchSource(f.backend, f.tokens), Markers: keyTestMarkers{}, Files: files}}

+ o, err := hostclaim.Read(t.Context(), f.claims, adminTokenHost)

+ if err != nil {

+ t.Fatal(err)

+ }

+ in, err := owners.Select(t.Context(), f.rt, o, activator.StartPolicy{})

+ if err != nil {

+ t.Fatalf("select: %v", err)

+ }

+ if err := owners.Materialize(t.Context(), o, in, passWork{}); err != nil {

+ t.Fatalf("materialize: %v", err)

+ }

+ var key string

+ for _, line := range strings.Split(string(files.seen), "\n") {

+ if v, ok := strings.CutPrefix(line, activator.InstanceKeyVar+"="); ok {

+ key = v

+ }

+ if len(key) != 44 {

+ t.Fatalf("the env file at Establish carries no minted key: %d bytes", len(files.seen))

+ }

+ found := false

+ for _, kv := range in.Env {

+ found = found || kv == activator.InstanceKeyVar+"="+key

+ }

+ if !found {

+ t.Fatal("the launch env does not carry the key the provider published")

+ }

+// An instance from before this build has a token and no key. Its next

+// claim launch mints the key under the same guarded write, leaves the

+// token alone, and a retry keeps both.

+func TestClaimLaunchMintsAKeyBesideAnExistingToken(t *testing.T) {

+ f := newAdminTokenFixture(t, "box-1")

+ tok := strings.Repeat("c", 64)

+ if err := os.WriteFile(f.envPath(), []byte("CARLOS_ADMIN_TOKEN="+tok+"\n"), 0o600); err != nil {

+ t.Fatal(err)

+ }

+ launch := claimServingLaunchSource(f.backend, f.tokens)

+ first, err := launch(t.Context(), f.rt)

+ if err != nil {

+ t.Fatal(err)

+ }

+ raw, _ := os.ReadFile(f.envPath())

+ if f.token() != tok || !strings.HasPrefix(string(raw), "CARLOS_ADMIN_TOKEN="+tok+"\n"+activator.InstanceKeyVar+"=") {

+ t.Fatalf("env file after the launch: %d bytes, token kept %v", len(raw), f.token() == tok)

+ }

+ again, err := launch(t.Context(), f.rt)

+ if err != nil {

+ t.Fatal(err)

+ }

+ raw2, _ := os.ReadFile(f.envPath())

+ if string(raw2) != string(raw) || again.Identity != first.Identity {

+ t.Fatal("a retried launch changed the env file or the launch identity")

+ }

+// Ruling 21: the claim snapshot names the key its env delivers, by digest,

+// and the file that supplied it, for O6 to check a process's report

+// against. The identity is the env's alone, so it does not change.

+func TestClaimSnapshotNamesTheDeliveredKeyAndItsSource(t *testing.T) {

+ f := newAdminTokenFixture(t, "box-1")

+ first, err := claimServingLaunchSource(f.backend, f.tokens)(t.Context(), f.rt)

+ if err != nil {

+ t.Fatal(err)

+ }

+ snap, err := f.backend.SnapshotClaimLaunch(t.Context(), f.rt)

+ if err != nil {

+ t.Fatal(err)

+ }

+ own, _ := os.ReadFile(f.envPath())

+ var key string

+ for _, line := range strings.Split(string(own), "\n") {

+ if v, ok := strings.CutPrefix(line, activator.InstanceKeyVar+"="); ok {

+ key = v

+ }

+ if snap.InstanceKeySource != instancekey.SourcePlatform || snap.InstanceKeySHA256 != instancekey.Digest(key) || snap.Identity != first.Identity {

+ t.Fatalf("platform key: source %q, digest match %v, identity kept %v", snap.InstanceKeySource, snap.InstanceKeySHA256 == instancekey.Digest(key), snap.Identity == first.Identity)

+ }

+ tok := "CARLOS_ADMIN_TOKEN=" + f.token() + "\n"

+ if err := os.WriteFile(f.envPath(), []byte(tok+activator.InstanceKeyVar+"=\n"), 0o600); err != nil {

+ t.Fatal(err)

+ }

+ if err := os.WriteFile(filepath.Join(f.data, adminTokenHost+".config.env"), []byte(activator.InstanceKeyVar+"=from-config\n"), 0o600); err != nil {

+ t.Fatal(err)

+ }

+ snap, err = f.backend.SnapshotClaimLaunch(t.Context(), f.rt)

+ if err != nil || snap.InstanceKeySource != instancekey.SourceConfig || snap.InstanceKeySHA256 != instancekey.Digest("from-config") {

+ t.Fatalf("configured key: source %q, %v", snap.InstanceKeySource, err)

+ }

diff --git a/internal/host/claim_replica_instancekey_test.go b/internal/host/claim_replica_instancekey_test.go

new file mode 100644

index 000000000..f3178c053

--- /dev/null

+++ b/internal/host/claim_replica_instancekey_test.go

@@ -0,0 +1,62 @@

+package host

+import (

+ "context"

+ "errors"

+ "os"

+ "path/filepath"

+ "strings"

+ "testing"

+ "github.com/carlosframework/platform/internal/activator"

+ "github.com/carlosframework/platform/internal/instancekey"

+ "github.com/carlosframework/platform/internal/registry"

+// Ruling 26 on the claim path, which has no control socket before O6: a

+// keyless replica is never selected (its helper would mint), a key that is

+// not the home's is refused, and the home's key is selected and named.

+func TestClaimReplicaLaunchIsGated(t *testing.T) {

+ homeKey := strings.Repeat("H", 43) + "="

+ for _, tc := range []struct {

+ name, config string

+ refused bool

+ }{

+ {"keyless", "", true},

+ {"another key", activator.InstanceKeyVar + "=configured-B\n", true},

+ {"the home's key", activator.InstanceKeyVar + "=" + homeKey + "\n", false},

+ } {

+ t.Run(tc.name, func(t *testing.T) {

+ f := newAdminTokenFixture(t, "box-1")

+ f.rt.Replica = true

+ f.backend.ReplicaHomeKeys = func(string) (string, bool) { return instancekey.Digest(homeKey), true }

+ f.backend.ReplicaConfigKey = func(context.Context, registry.Route) (string, error) { return instancekey.Digest(homeKey), nil }

+ own := "CARLOS_ADMIN_TOKEN=" + strings.Repeat("c", 64) + "\n"

+ if err := os.WriteFile(f.envPath(), []byte(own), 0o600); err != nil {

+ t.Fatal(err)

+ }

+ if tc.config != "" {

+ if err := os.WriteFile(filepath.Join(f.data, adminTokenHost+".config.env"), []byte(tc.config), 0o600); err != nil {

+ t.Fatal(err)

+ }

+ launch, err := claimServingLaunchSource(f.backend, f.tokens)(t.Context(), f.rt)

+ if tc.refused {

+ if !errors.Is(err, activator.ErrReplicaKey) {

+ t.Fatalf("launch source = %v, want ErrReplicaKey", err)

+ }

+ } else {

+ found := false

+ for _, kv := range launch.Env {

+ found = found || kv == activator.InstanceKeyVar+"="+homeKey

+ }

+ if err != nil || !found {

+ t.Fatalf("launch source = %v, key delivered %v", err, found)

+ }

+ if raw, _ := os.ReadFile(f.envPath()); string(raw) != own {

+ t.Fatal("a replica's claim launch changed its own env file: a replica never mints")

+ }

+ })

+ }

diff --git a/internal/host/claimowners.go b/internal/host/claimowners.go

index 81f797b73..491a3e2ab 100644

--- a/internal/host/claimowners.go

+++ b/internal/host/claimowners.go

@@ -133,6 +133,19 @@ type ClaimMarkerStore interface {

// region. Missing or malformed data is an error, never an empty-files

// bootstrap; only an empty bootstrap (in.Empty, after EmptyAuthority) starts

// from no manifest.

+//

+// The instance key (L21, plan 2026-10-10-instance-key-provision.md

+// obligation O1'): the launch source has already minted

+// CARLOS_INSTANCE_KEY into the host's own <host>.env, durably, when

+// Establish runs, and the app executes only after it returns. So the

+// manifest Establish leaves must carry the env file (region HA §5.6's

+// always-continuous platform item) with exactly the bytes on disk when it

+// runs, staged and committed before it returns. A new admission starts

+// with no adoption record: the manifest carries no instancekey.AdoptionItem

+// (StagePlatformDelete), and the local <host>.instance-key-adoption.json is

+// removed under work. An error, a bucket that cannot be reached included,

+// fails the wake and the app does not start. Establish never writes the env

+// file on disk.

type ClaimFilesManifest interface {

Establish(ctx context.Context, o hostclaim.Observed, in ClaimLaunchInputs, work hostwrite.Work) error

}