@cotal-ai/auth 0.53.0 → 0.55.0

package/dist/service.js

@@ -31,9 +31,9 @@
  * the public face is the credential itself: the human arm presents an EdDSA IdP JWT verified
  * against the pinned JWKS/issuer/audience; the agent arm presents an actorToken whose sha256 must
  * match a FRESH ledger row. Origin rejection, JSON-only bodies, the 64 KB bound, and no-CORS-ever
- * hold verbatim; `view` requests other than `channel-writer` and `channel-purger` are REFUSED
- * (those two stay ledger-gated on `admin`; every other operator surface stays loopback-only); a
- * managed-agent secret exchange never mints a view on either face;
+ * hold verbatim. Public views are channel-writer/channel-purger (admin-gated) and manager-caller
+ * (instance-bound, with no added command scope). Other views stay loopback-only. The agent-secret
+ * arm may request only manager-caller on either face;
  * failures are bucketed per peer (`--exchange-trusted-proxy` opts into the last X-Forwarded-For
  * hop as the peer key; otherwise the socket remote address) in a bounded LRU, under a global
  * concurrent-admission cap and a hard request deadline — all of it pools SEPARATE from the
@@ -57,8 +57,8 @@ import { createServer } from "node:http";
 import { connect, credsAuthenticator } from "@nats-io/transport-node";
 import { jetstreamManager } from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
-import { admissionMediatorGrants, assertDerivedOwnerToken, assertLifecycleToken, assertValidOwnerToken, authorizeTrustedServeSnapshot, commitSiblingIssuance, EpEnvelopeError, ensureAuthorityStores, epAuthBucket, isReachable, mintCreds, mintPublicUserJwt, newIdentity, rawDigest, reconcileEndpointGate, recordsBucket, remoteManagerActors, retirementFrontierStreams, serveIssuanceGateKv, standaloneConnectOpts, STANDING_RENEWABLE_TTL_SEC } from "@cotal-ai/core";
-import { findCotalRoot, userAuthStateDir, workspaceSecretStore } from "@cotal-ai/workspace";
+import { admissionMediatorGrants, assertDerivedOwnerToken, assertLifecycleToken, assertValidOwnerToken, authorizeTrustedServeSnapshot, commitSiblingIssuance, EpEnvelopeError, ensureAuthorityStores, epAuthBucket, isReachable, managedRetirementOpId, mintCreds, mintPublicUserJwt, newIdentity, parseEndpointGate, parseServiceSpec, parseServiceStatus, rawDigest, readSvcRecordLeader, reconcileEndpointGate, recordSpecKey, recordStatusKey, RECORD_KINDS, recordsBucket, remoteManagerActors, retirementFrontierStreams, serveIssuanceGateKv, standaloneConnectOpts, STANDING_RENEWABLE_TTL_SEC } from "@cotal-ai/core";
+import { findCotalRoot, loadManagerInstanceIdentity, userAuthStateDir, workspaceSecretStore } from "@cotal-ai/workspace";
 import { decodeJwt } from "jose";
 import { deriveOwnerForIdpSubject } from "./derive.js";
 import { startAuthCallout } from "./callout.js";
@@ -68,6 +68,7 @@ import { pinnedJwksResolver } from "./issuer.js";
 import { calloutPermissions } from "./permissions.js";
 import { issueRemoteManagerAuthority } from "./manager-authority.js";
 import { authorizeRemoteRetainedAgentValidation, completeRemoteRetainedAgentValidation, remoteManagerCurrentRegistrationProof } from "./retained-manager-validation.js";
+import { authorizeRemoteManagedAgentEnrollment, authorizeRemoteManagedAgentPrepareRetirement } from "./managed-agent-enrollment.js";
 import { authorizeRemoteManagerGoalIndexScan, completeRemoteManagerGoalIndexScan } from "./manager-goal-index.js";
 import { authorizeRemoteManagerAdmin } from "./manager-admin-authorization.js";
 import { authorizeRemoteManagerMaintenance, completeRemoteManagerMaintenance } from "./manager-maintenance.js";
@@ -85,15 +86,22 @@ import { makeDeliveryAdminEvictor } from "./barrier-evict.js";
 import { resumeAgentRetirement, runAgentRetirementBarrier } from "./retirement-barrier.js";
 import { makeRetirementCleaners } from "./retirement-cleaner.js";
 import { makeDrainRepairers } from "./drain-repair.js";
-import { openAuthAdminListener } from "./auth-admin.js";
+import { joinOrStartRetirement, openAuthAdminListener } from "./auth-admin.js";
 import { drainTargetForEndpoint, openAdmissionMediator } from "./admission-mediator.js";
-import { AGENT_BEARER_TTL_SEC, findInteractiveActor, ledgerAclResolver, ledgerAuthorizeAgentExchange, ledgerAuthorizeConnect, ledgerAuthorizeGrant, } from "./ledger.js";
+import { AGENT_BEARER_TTL_SEC, findInteractiveActor, findManagedActor, ledgerAclResolver, ledgerAuthorizeAgentExchange, ledgerAuthorizeConnect, ledgerAuthorizeGrant, } from "./ledger.js";
 import { AUTH_PROVIDER_NAME, clearAuthServiceInfo, loadCalloutAuth, loadIssuer, loadOwnerSecret, loadPinnedIdp, loadServiceKeys, saveAuthServiceInfo, spaceIssuer, } from "./store.js";
 /** JWKS max-age seconds — the cache contract's knob. Exported so a rotation tool can compute the
  *  retire floor (max-age + max bearer TTL) from it. */
 export const JWKS_MAX_AGE_SEC = 300;
 /** Loopback-only operator route used by `cotal actor grant/revoke` before rotating or deleting an interactive lifecycle. */
 export const INTERACTIVE_RETIRE_PATH = "/interactive-lifecycle/retire";
+/** Loopback-only host route that finishes a managed lifecycle's terminal retirement after the host
+ *  revoked its grant, when the remote manager that should have requested it is gone (#2070). */
+export const MANAGED_RETIRE_PATH = "/managed-lifecycle/retire";
+/** Loopback-only host route a platform calls BEFORE it enrolls or releases a managed agent for a
+ *  remote manager (#1972 §2.2). The platform owns the writers; this door owns the decision. It
+ *  derives the caller's scope from the local ledger and never accepts one from the caller. */
+export const VERIFY_ENROLLMENT_PATH = "/manager-service-authority/verify-enrollment";
 /** Failed-exchange rate limit: at most this many REFUSED exchanges per rolling minute; further
  *  attempts get 429 until the window drains. Successes are unthrottled (the CLI's normal path). */
 const FAILED_EXCHANGE_PER_MIN = 30;
@@ -307,6 +315,9 @@ export async function openAuthAuthorityPlane(opts) {
         await writer.close();
         throw e;
     }
+    // ONE in-flight map for the rail and the loopback managed-retire door: both run the same
+    // `managedRetirementOpId(uid)` operation, and a process must never execute it twice at once.
+    const retirementFlights = new Map();
     // The AUTH CONTROL RAIL (#29 piece 3, SPEC 13.2 CONTROL_AUTH_ADMIN): serve the generic
     // "retire a lifecycle" op over a dedicated minimal listener credential. Every executing right
     // stays with the plane's own registry + retirement deps (the drain rides the ONE sealed records
@@ -314,7 +325,7 @@ export async function openAuthAuthorityPlane(opts) {
     // the FRESH space-manager-lease holder check) and dispatches.
     let authAdmin;
     try {
-        authAdmin = await openAuthAdminListener({ server, space, dataAccount, reg: barrierReg, retirement, log });
+        authAdmin = await openAuthAdminListener({ server, space, dataAccount, reg: barrierReg, retirement, barrierFlight: retirementFlights, log });
     }
     catch (e) {
         closing = true;
@@ -328,6 +339,76 @@ export async function openAuthAuthorityPlane(opts) {
         throw e;
     }
     const fileArm = ledgerAuthorizeConnect(opts.dir);
+    const recordsJsm = await jetstreamManager(remoteIssuer.nc);
+    const root = findCotalRoot();
+    const managerGate = async (owner, instanceId) => {
+        const localManager = loadManagerInstanceIdentity(root, space);
+        const gate = await serveIssuanceGateKv(await new Kvm(remoteIssuer.nc).open(epAuthBucket(space)), space, { endpoint: "manager", instanceId }).observe();
+        if (!gate)
+            return "unknown";
+        if (gate.state !== "open")
+            return "not open";
+        const remotePrincipal = `${owner}.${remoteManagerActors(instanceId).serve}`;
+        const local = localManager?.instanceId === instanceId && gate.principal === `local.${localManager.serveIdentity.id}`;
+        const remote = gate.principal === remotePrincipal;
+        if (!local && !remote)
+            return "not this owner's";
+        const rec = await readSvcRecordLeader(recordsJsm, space, recordSpecKey(RECORD_KINDS.svc, ["manager", instanceId]));
+        if (!rec || "deleted" in rec)
+            return "not registered";
+        const spec = parseServiceSpec(rec.value, { endpoint: "manager" });
+        if (spec.owner !== (local ? "local" : owner) || rec.revision !== gate.registrationRevision)
+            return "not registered";
+        const statusRec = await readSvcRecordLeader(recordsJsm, space, recordStatusKey(RECORD_KINDS.svc, ["manager", instanceId]));
+        if (!statusRec || "deleted" in statusRec)
+            return "not registered";
+        const status = parseServiceStatus(statusRec.value);
+        if (status.observedSpecRevision < rec.revision || status.epoch !== gate.processEpoch)
+            return "not registered";
+        return "candidate";
+    };
+    const selectManagerInstance = async (owner, requested) => {
+        refuseIfFenced();
+        if (requested !== undefined) {
+            const instanceId = assertLifecycleToken(requested, "managerInstanceId");
+            const verdict = await managerGate(owner, instanceId);
+            if (verdict !== "candidate")
+                throw new Error(`manager instance ${instanceId} is ${verdict}`);
+            return instanceId;
+        }
+        const remoteInstances = [];
+        const remoteLive = [];
+        let localCandidate;
+        const localManager = loadManagerInstanceIdentity(root, space);
+        for (const raw of await scanner.scanManagerGates()) {
+            if (raw.op !== undefined)
+                continue;
+            const parts = raw.key.split(".");
+            if (parts.length !== 3 || parts[0] !== "epgate" || parts[1] !== "manager")
+                throw new EpEnvelopeError("internal", `the manager gate scan returned the malformed key ${raw.key}`);
+            const instanceId = assertLifecycleToken(parts[2], "managerInstanceId");
+            const row = parseEndpointGate(raw.data, raw.key);
+            if (row.principal === `${owner}.${remoteManagerActors(instanceId).serve}`) {
+                remoteInstances.push(instanceId);
+                if (await managerGate(owner, instanceId) === "candidate")
+                    remoteLive.push(instanceId);
+            }
+            else if (localManager?.instanceId === instanceId && row.principal === `local.${localManager.serveIdentity.id}`) {
+                if (await managerGate(owner, instanceId) === "candidate")
+                    localCandidate = instanceId;
+            }
+        }
+        remoteLive.sort();
+        if (remoteLive.length === 1)
+            return remoteLive[0];
+        if (remoteLive.length > 1)
+            throw new Error(`manager-caller selection found ${remoteLive.length} live remote manager candidates for owner ${owner}; exactly one is required or name --manager-instance`);
+        if (remoteInstances.length > 0)
+            throw new Error(`the remote manager for owner ${owner} is unavailable (${remoteInstances.length} gate${remoteInstances.length === 1 ? "" : "s"}, none live); pass managerInstanceId to select an instance explicitly rather than falling through to the local manager`);
+        if (localCandidate !== undefined)
+            return localCandidate;
+        throw new Error(`manager-caller selection found no manager candidate for owner ${owner}`);
+    };
     // Every authority operation refuses once the plane is fenced: a half-dead plane keeps NO face up.
     // AUDIENCE SPLIT (ux): these refusals reach a CONNECTING AGENT during the brief fence→exit
     // window, not the operator — the agent cannot "restart the auth service", so it gets a retryable
@@ -346,6 +427,13 @@ export async function openAuthAuthorityPlane(opts) {
             refuseIfFenced();
             return ensureRootCredential(registry, { ...args, managerInstance: `auth-service:${space}` });
         },
+        selectManagerInstance,
+        authorizeManagerCaller: async (owner, instanceId) => {
+            refuseIfFenced();
+            const verdict = await managerGate(owner, assertLifecycleToken(instanceId, "managerInstanceId"));
+            if (verdict !== "candidate")
+                throw new Error(`manager instance ${instanceId} is ${verdict} at the permission mint`);
+        },
         retireInteractiveLifecycle: async (args) => {
             refuseIfFenced();
             const owner = assertDerivedOwnerToken(args.owner);
@@ -374,6 +462,36 @@ export async function openAuthAuthorityPlane(opts) {
             }, retirement);
             return { retired: true, lifecycleUid };
         },
+        retireManagedLifecycle: async (args) => {
+            refuseIfFenced();
+            const owner = assertDerivedOwnerToken(args.owner);
+            const actor = assertValidOwnerToken(args.actor);
+            const lifecycleUid = assertLifecycleToken(args.lifecycleUid);
+            // The `prepareAgentRetirement` contract: the host revokes the managed grant FIRST. Only a
+            // grant still live AT THIS uid blocks; a row at another uid is a successor the head decides.
+            if (findManagedActor(opts.dir, owner, actor)?.lifecycleUid === lifecycleUid)
+                throw new EpEnvelopeError("conflict", `managed actor "${owner}/${actor}" is still granted at lifecycle ${lifecycleUid}; revoke the grant before retiring it`);
+            const head = await readLifecycleHeadForOperation(barrierReg, owner, actor);
+            if (head === undefined)
+                return { retired: false, lifecycleUid, notStarted: true };
+            if (head.mapping.lifecycleUid !== lifecycleUid) {
+                if (head.mapping.state === "retired")
+                    return { retired: false, lifecycleUid, notStarted: true };
+                throw new EpEnvelopeError("conflict", `managed lifecycle retirement for "${owner}/${actor}" names ${lifecycleUid}, but the authority head is ${head.mapping.state} at ${head.mapping.lifecycleUid}`);
+            }
+            if (head.mapping.state === "retired")
+                return { retired: true, lifecycleUid, alreadyRetired: true };
+            // The rail's opId, not the interactive digest: a host door call and a late participant rail call
+            // create or resume ONE barrier operation and join ONE in-process flight.
+            const opId = managedRetirementOpId(lifecycleUid);
+            const flight = joinOrStartRetirement(retirementFlights, barrierReg, {
+                owner, actor, lifecycleUid, opId, frontierStreams: retirementFrontierStreams(space),
+            }, retirement);
+            if (flight === undefined)
+                throw new EpEnvelopeError("conflict", `managed retirement operation ${opId} is already in flight for different coordinates`);
+            await flight;
+            return { retired: true, lifecycleUid };
+        },
         issueManagerServiceAuthority: async ({ owner, scope, request }) => {
             refuseIfFenced();
             return issueRemoteManagerAuthority({
@@ -569,6 +687,34 @@ export async function openAuthAuthorityPlane(opts) {
                 },
             });
         },
+        verifyManagedAgentEnrollment: async ({ owner, scope, request }) => {
+            refuseIfFenced();
+            return authorizeRemoteManagedAgentEnrollment({
+                owner,
+                scope,
+                proofSecret: dataAccount.signingSeed,
+                space,
+                request,
+                observeManagerGate: async (instanceId) => {
+                    const gate = serveIssuanceGateKv(await new Kvm(remoteIssuer.nc).open(epAuthBucket(space)), space, { endpoint: "manager", instanceId });
+                    return gate.observe();
+                },
+            });
+        },
+        verifyManagedAgentPrepareRetirement: async ({ owner, scope, request }) => {
+            refuseIfFenced();
+            return authorizeRemoteManagedAgentPrepareRetirement({
+                owner,
+                scope,
+                proofSecret: dataAccount.signingSeed,
+                space,
+                request,
+                observeManagerGate: async (instanceId) => {
+                    const gate = serveIssuanceGateKv(await new Kvm(remoteIssuer.nc).open(epAuthBucket(space)), space, { endpoint: "manager", instanceId });
+                    return gate.observe();
+                },
+            });
+        },
         scanManagerGoalIndex: async ({ owner, scope, request }) => {
             refuseIfFenced();
             const authorized = await authorizeRemoteManagerGoalIndexScan({
@@ -789,7 +935,7 @@ export async function runAuthService(args, store) {
         space,
         token: { key: issuer.localKeySet(), issuer: issuer.issuer },
         authorizeActor: plane.authorizeConnect,
-        permissionsFor: calloutPermissions(ledgerAclResolver(dir)),
+        permissionsFor: calloutPermissions(ledgerAclResolver(dir), plane.authorizeManagerCaller),
         log: (l) => console.error(l),
     });
     // The subscription must be ON the broker before readiness is signaled — an `up` that recorded a
@@ -816,16 +962,20 @@ export async function runAuthService(args, store) {
         managerServiceAuthority: plane.issueManagerServiceAuthority,
         maintainRemoteManager: plane.maintainRemoteManager,
         validateRetainedAgent: plane.validateRetainedAgent,
+        verifyManagedAgentEnrollment: plane.verifyManagedAgentEnrollment,
+        verifyManagedAgentPrepareRetirement: plane.verifyManagedAgentPrepareRetirement,
         scanManagerGoalIndex: plane.scanManagerGoalIndex,
         authorizeManagerAdmin: plane.authorizeManagerAdmin,
         secrets,
         retireInteractiveLifecycle: plane.retireInteractiveLifecycle,
+        retireManagedLifecycle: plane.retireManagedLifecycle,
         cap,
         failures,
         badCaps,
         space,
         dir,
         mintConnectCredential: plane.mintConnectCredential,
+        selectManagerInstance: plane.selectManagerInstance,
     };
     const http = createServer((req, res) => void handle(req, res, ctx));
     await new Promise((resolvePort, reject) => {
@@ -906,6 +1056,13 @@ export async function dispatchManagerAuthorityRequest(ctx, owner, body) {
     if (typeof request.actor !== "string")
         throw new Error("manager-service authority request requires an actor");
     const row = ledgerAuthorizeGrant(ctx.dir)(owner, request.actor);
+    // #1972: the managed-agent lifecycle operations mutate host storage (a database row, JetStream
+    // durables, a ledger grant), and stock holds none of that composition. A host platform intercepts
+    // these kinds on its own public route and calls the loopback verify-enrollment door for the
+    // decision. Refusing here keeps them from falling through to `managerServiceAuthority`, which
+    // would answer a manager-lifecycle phase for an agent-lifecycle request.
+    if (request.kind === "manager-managed-agent-enrollment" || request.kind === "manager-managed-agent-prepare-retirement")
+        throw new EpEnvelopeError("unimplemented", "managed agent enrollment and retirement preparation must be handled by host platform interception");
     if (request.kind === "manager-retained-agent-validation") {
         const retained = await ctx.validateRetainedAgent({
             owner,
@@ -1029,13 +1186,15 @@ const ROUTES = new Map([
     ["/exchange", (req, res, ctx) => handleExchange(req, res, ctx, LOOPBACK_POLICY)],
     ["/manager-service-authority", (req, res, ctx) => handleManagerServiceAuthority(req, res, ctx, LOOPBACK_POLICY)],
     [INTERACTIVE_RETIRE_PATH, handleInteractiveLifecycleRetirement],
+    [MANAGED_RETIRE_PATH, handleManagedLifecycleRetirement],
+    [VERIFY_ENROLLMENT_PATH, handleVerifyManagedAgentEnrollment],
 ]);
 /** Route one HTTP request against the loopback route table. Errors are JSON `{ error }`. */
 async function handle(req, res, ctx) {
     try {
         const route = ROUTES.get(req.url ?? "");
         if (!route)
-            return send(res, 404, { error: "unknown path - /health, /jwks, /exchange, /manager-service-authority, /interactive-lifecycle/retire" });
+            return send(res, 404, { error: "unknown path - /health, /jwks, /exchange, /manager-service-authority, /manager-service-authority/verify-enrollment, /interactive-lifecycle/retire, /managed-lifecycle/retire" });
         await route(req, res, ctx);
     }
     catch (e) {
@@ -1072,6 +1231,128 @@ async function handleInteractiveLifecycleRetirement(req, res, ctx) {
     const result = await ctx.retireInteractiveLifecycle({ owner, actor, lifecycleUid });
     return send(res, 200, result);
 }
+/** The host's terminal step for a managed lifecycle whose remote manager is gone: the same request
+ *  guards as the interactive door, but it requires the managed grant to be REVOKED first (the
+ *  `prepareAgentRetirement` contract) and runs the rail's `managedRetirementOpId(uid)` operation. */
+async function handleManagedLifecycleRetirement(req, res, ctx) {
+    if (req.method !== "POST")
+        return send(res, 405, { error: "POST only" });
+    if (req.headers.origin !== undefined)
+        return send(res, 403, { error: "browser-origin requests are not served here" });
+    if (!/^application\/json\b/.test(req.headers["content-type"] ?? ""))
+        return send(res, 415, { error: "content-type must be application/json" });
+    if (req.headers.authorization !== `Bearer ${ctx.cap}`)
+        return send(res, 401, { error: "missing/invalid exchange capability - managed lifecycle retirement is a loopback host action" });
+    const body = await readJsonBody(req);
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return send(res, 400, { error: "managed lifecycle retirement needs { owner, actor, lifecycleUid }" });
+    for (const key of Object.keys(body))
+        if (!INTERACTIVE_RETIRE_KEYS.has(key))
+            return send(res, 400, { error: `managed lifecycle retirement carries the unknown field "${key}"` });
+    const raw = body;
+    if (typeof raw.owner !== "string" || typeof raw.actor !== "string" || typeof raw.lifecycleUid !== "string")
+        return send(res, 400, { error: "managed lifecycle retirement needs string { owner, actor, lifecycleUid }" });
+    const owner = assertDerivedOwnerToken(raw.owner);
+    const actor = assertValidOwnerToken(raw.actor);
+    const lifecycleUid = assertLifecycleToken(raw.lifecycleUid);
+    try {
+        return send(res, 200, await ctx.retireManagedLifecycle({ owner, actor, lifecycleUid }));
+    }
+    catch (e) {
+        if (e instanceof EpEnvelopeError && e.code === "conflict")
+            return send(res, 409, { error: e.message });
+        throw e;
+    }
+}
+/** The envelope-error to HTTP mapping this door answers with. A code the catalog grows but this
+ *  table does not name becomes 403 rather than a 500: a refusal is a refusal, and a door that
+ *  answered 500 to a new permission code would read as a host fault to the platform calling it. */
+const VERIFY_ENROLLMENT_STATUS = {
+    "unauthenticated": 401,
+    "permission-denied": 403,
+    "conflict": 409,
+    "failed-precondition": 412,
+    "bad-request": 400,
+};
+const VERIFY_ENROLLMENT_KEYS = new Set(["owner", "request"]);
+/**
+ * #1972 §2.2 item 3: the host platform's decision door for a remote manager's managed-agent
+ * enrollment or terminal-release preparation.
+ *
+ * The platform that owns the database, the durables, and the ledger terminates its own public
+ * route, authenticates the human there, and POSTs the resulting owner token plus the participant's
+ * verbatim request here. This process answers because it is the only one holding the manager gate
+ * connection and the data-account signing seed: the proof check and the gate read happen inside it,
+ * and no secret crosses back.
+ *
+ * The caller supplies an OWNER and a REQUEST, and nothing else. The caller's scope is derived from
+ * this machine's ledger (`ledgerAuthorizeGrant`), never accepted from the body — a platform bug that
+ * forwarded a participant-supplied scope array could otherwise hand `supervise` to any caller.
+ */
+async function handleVerifyManagedAgentEnrollment(req, res, ctx) {
+    if (req.method !== "POST")
+        return send(res, 405, { error: "POST only" });
+    if (req.headers.origin !== undefined)
+        return send(res, 403, { error: "browser-origin requests are not served here" });
+    if (!/^application\/json\b/.test(req.headers["content-type"] ?? ""))
+        return send(res, 415, { error: "content-type must be application/json" });
+    if (req.headers.authorization !== `Bearer ${ctx.cap}`)
+        return send(res, 401, { error: "missing/invalid exchange capability - managed agent enrollment verification is a loopback host action" });
+    const body = await readJsonBody(req);
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return send(res, 400, { error: "managed agent enrollment verification needs { owner, request }" });
+    for (const key of Object.keys(body))
+        if (!VERIFY_ENROLLMENT_KEYS.has(key))
+            return send(res, 400, { error: `managed agent enrollment verification carries the unknown field "${key}"` });
+    const raw = body;
+    if (typeof raw.owner !== "string" || raw.request === null || typeof raw.request !== "object" || Array.isArray(raw.request))
+        return send(res, 400, { error: "managed agent enrollment verification needs a string owner and an object request" });
+    const request = raw.request;
+    if (request.kind !== "manager-managed-agent-enrollment" && request.kind !== "manager-managed-agent-prepare-retirement")
+        return send(res, 400, { error: 'managed agent enrollment verification serves only kind "manager-managed-agent-enrollment" or "manager-managed-agent-prepare-retirement"' });
+    if (typeof request.actor !== "string")
+        return send(res, 400, { error: "managed agent enrollment verification request requires an actor" });
+    try {
+        const owner = assertDerivedOwnerToken(raw.owner);
+        // The SCOPE DERIVATION, internal by construction: the interactive row for this exact
+        // (owner, actor) on this machine's ledger decides, so `supervise` cannot be asserted by the
+        // caller. An ungranted actor throws the ledger's own operator-exact sentence.
+        const row = ledgerAuthorizeGrant(ctx.dir)(owner, request.actor);
+        const scope = row.scope ?? [];
+        if (request.kind === "manager-managed-agent-enrollment") {
+            const verified = await ctx.verifyManagedAgentEnrollment({
+                owner,
+                scope,
+                request: raw.request,
+            });
+            return send(res, 200, {
+                authorized: true,
+                owner,
+                actor: verified.target.actor,
+                instanceId: verified.instanceId,
+                serveEpoch: verified.serveEpoch,
+            });
+        }
+        const verified = await ctx.verifyManagedAgentPrepareRetirement({
+            owner,
+            scope,
+            request: raw.request,
+        });
+        return send(res, 200, {
+            authorized: true,
+            owner,
+            actor: verified.target.actor,
+            instanceId: verified.instanceId,
+            serveEpoch: verified.serveEpoch,
+        });
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        console.error(`auth-service: refused managed agent enrollment verification: ${reason}`);
+        const status = e instanceof EpEnvelopeError ? (VERIFY_ENROLLMENT_STATUS[e.code] ?? 403) : 403;
+        return send(res, status, { error: reason });
+    }
+}
 /** The exchange body, shared by every face; `policy` says how this face proves and attributes the
  *  caller. Behavior on the loopback face is unchanged from the pre-route-table handler. */
 async function handleExchange(req, res, ctx, policy) {
@@ -1115,12 +1396,16 @@ async function handleExchange(req, res, ctx, policy) {
     const peer = policy.peerKey(req);
     const peerThrottled = policy.throttled(ctx, peer);
     const body = await readJsonBody(req);
-    const { idpToken, actor, actorToken, owner, ttlSec, view } = body;
+    const { idpToken, actor, actorToken, owner, ttlSec, view, managerInstanceId } = body;
     if (ttlSec !== undefined && typeof ttlSec !== "number")
         return send(res, 400, { error: "ttlSec must be a number" });
     if (view !== undefined && typeof view !== "string")
         return send(res, 400, { error: "view must be a string when present" });
-    // Public face: only channel-writer / channel-purger ride this listener (still ledger-gated).
+    if (managerInstanceId !== undefined && typeof managerInstanceId !== "string")
+        return send(res, 400, { error: "managerInstanceId must be a string when present" });
+    if (managerInstanceId !== undefined && view !== "manager-caller")
+        return send(res, 400, { error: 'managerInstanceId is valid only with view "manager-caller"' });
+    // Public face: channel-writer / channel-purger and the narrowing manager-caller view.
     // admin, purger, deployer, and manager-service stay loopback-only, whatever the credential.
     // A refused view is a refused exchange: record, audit, then 429 when the peer is already
     // throttled, same order as the neighbouring denial sites. A served view stays unthrottled.
@@ -1138,9 +1423,9 @@ async function handleExchange(req, res, ctx, policy) {
     if (idpToken !== undefined && actorToken !== undefined)
         return send(res, 400, { error: "exchange takes idpToken (human) OR owner+actorToken (agent), never both" });
     if (actorToken !== undefined) {
-        // Elevated views are for signed-in HUMANS only: an agent's secret exchange never mints one,
-        // whatever its ledger row carries (v1 — agents hold no god views).
-        if (view !== undefined)
+        // The actor-secret exception is manager-caller only: it adds no command capability.
+        // Elevated views still require a signed-in human, whatever this agent's row carries.
+        if (view !== undefined && view !== "manager-caller")
             return send(res, 400, { error: "the managed (agent-secret) exchange never mints elevated views - views ride a signed-in human exchange" });
         if (typeof owner !== "string" || !owner || typeof actor !== "string" || !actor || typeof actorToken !== "string" || !actorToken)
             return send(res, 400, { error: "agent exchange needs { owner: string, actor: string, actorToken: string, ttlSec?: number }" });
@@ -1152,6 +1437,9 @@ async function handleExchange(req, res, ctx, policy) {
             // ensured (minted release-last on first exchange) BEFORE the bearer bytes are signed,
             // and rides act.credentialId — the connect arm requires it against the LIVE cred row.
             const credentialId = await ctx.mintConnectCredential({ owner, actor, lifecycleUid: grant.lifecycleUid });
+            const selectedManagerInstanceId = view === "manager-caller"
+                ? await ctx.selectManagerInstance(owner, managerInstanceId)
+                : undefined;
             const token = await ctx.issuer.issue({
                 owner,
                 space: ctx.space,
@@ -1164,10 +1452,11 @@ async function handleExchange(req, res, ctx, policy) {
                 // successor's broker authority.
                 lifecycleUid: grant.lifecycleUid,
                 credentialId,
+                ...(view === "manager-caller" ? { view, managerInstanceId: selectedManagerInstanceId } : {}),
                 ttlSec: Math.min(ttlSec ?? AGENT_BEARER_TTL_SEC, AGENT_BEARER_TTL_SEC),
             });
             const { exp } = decodeJwt(token);
-            return send(res, 200, { token, owner, exp });
+            return send(res, 200, { token, owner, exp, ...(selectedManagerInstanceId ? { managerInstanceId: selectedManagerInstanceId } : {}) });
         }
         catch (e) {
             policy.recordFailure(ctx, peer);
@@ -1183,7 +1472,15 @@ async function handleExchange(req, res, ctx, policy) {
     try {
         // The bridge validates `view` against the closed enum and the fresh ledger grant — an
         // unknown or under-scoped view is a refused exchange (audited + throttled like any other).
-        const r = await ctx.bridge.exchange(idpToken, { actor, ttlSec, view: view });
+        const selectedManagerInstanceId = view === "manager-caller"
+            ? await ctx.selectManagerInstance(deriveOwnerForIdpSubject(ctx.ownerSecret, ctx.bridgeIdp.issuer, (await verifyIdpToken(idpToken, ctx.bridgeIdp)).sub), managerInstanceId)
+            : undefined;
+        const r = await ctx.bridge.exchange(idpToken, {
+            actor,
+            ttlSec,
+            view: view,
+            managerInstanceId: selectedManagerInstanceId,
+        });
         return send(res, 200, r);
     }
     catch (e) {