@cotal-ai/auth 0.85.0 → 0.87.0

package/dist/service.js

@@ -68,7 +68,7 @@ import { makePlatformControlAuthority, makePlatformControlReadiness, requireMana
 import { OwnedConnections } from "./owned-connections.js";
 import { makePlatformSupervisorAuthority, makePlatformSupervisorEnd, platformSupervisorEnded, requirePlatformSupervisorAdmin } from "./platform-supervisor.js";
 import { startAuthCallout } from "./callout.js";
-import { createIdpBridge, verifyIdpToken } from "./idp.js";
+import { createIdpBridge, verifyIdpToken, verifyToolResultHumanProof } from "./idp.js";
 import { PUBLIC_EXCHANGE_VIEWS, assertTransferWriterClaim } from "./token.js";
 import { grantCoordinates, verifySessionRedemption } from "./session-redemption.js";
 import { pinnedJwksResolver } from "./issuer.js";
@@ -83,6 +83,7 @@ import { validateRetainedManagedAgent } from "./continuity.js";
 import { reconstructRemoteManagerServeGrant, remoteManagerServeGrantFromCluster, remoteManagerSurface } from "./manager-contract.js";
 import { authorityBarrierGrants, authorityWriterGrants, openAuthorityClient, openSupervisedConnectReader, platformReadinessGrants, remoteManagerIssuerGrants, remoteManagerRegistrationProof, registrationExecutorGrants, servedRunRequestSubjects } from "./authority-client.js";
 import { authorizeConnectCredential } from "./connect-reader.js";
+import { makeNativeIssuanceRecorder, pruneNativeIssuance } from "./native-issuance.js";
 import { ensureRootCredential } from "./root-credential.js";
 import { activateLifecycleAtUid, observeGate, openLifecycleRegistry, readLifecycleHeadForOperation } from "./lifecycle-registry.js";
 import { openAuthLedgerScannerCandidate } from "./ledger-scanner.js";
@@ -111,6 +112,8 @@ export const MANAGED_RETIRE_PATH = "/managed-lifecycle/retire";
  *  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";
+/** Host-only, capability-gated proof decision. It neither signs consent nor serves results. */
+export const TOOL_RESULT_HUMAN_PROOF_PATH = "/tool-result-human-proof/verify";
 /** 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;
@@ -132,6 +135,14 @@ const OBSERVED_RUN_REQUEST_WINDOW_MS = 5 * 60_000; // how long an observed serve
  *  ledger directory, so two plane instances over one ledger share it. */
 const MANAGED_ALIAS_CHAINS = new Map();
 const serializedForAlias = (dir, owner, actor, fn) => serializedFor(MANAGED_ALIAS_CHAINS, `${resolve(dir)}:${principalKey(owner, actor).key}`, fn);
+/** How each caller names one manager instance, for the refusal that needs it to. The agent arm's
+ *  one client is `cotal agent-bearer`; a connector that runs it for a tool renames the flag to the
+ *  tool's `instance` argument. */
+const MANAGER_PIN_REMEDY = {
+    human: "name one with --on <instanceId>",
+    agent: "name one with --manager-instance <instanceId>",
+    wire: "name one as managerInstanceId",
+};
 /** Package-internal policy step for the hosted retirement requester. The HTTP production door calls
  * this after deriving the owner and manager actors; broker-free smokes exercise the same decision. */
 export function authorizeRemoteManagerRetirement(args) {
@@ -414,6 +425,39 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
     const authAdmin = await openAuthAdminListener({ onConnection, server, space, dataAccount, reg: barrierReg, retirement, barrierFlight: retirementFlights, instanceId: authServeInstanceId, epoch: authServeGrant.epoch, grant: authServeGrant, log });
     unwind.push(() => authAdmin.close());
     const fileArm = ledgerAuthorizeConnect(opts.dir);
+    // The callout's issuance evidence: create-only natkey row, then the connect authority re-read
+    // in the same stream before the minted JWT may leave.
+    const recordIssuance = makeNativeIssuanceRecorder(registry, async (t) => {
+        refuseIfFenced();
+        fileArm(t);
+        await authorizeConnectCredential(reader.current(), t, Date.now);
+    });
+    // Expired evidence goes at boot (a failure refuses the open) and then on the plane's own timer;
+    // a failed pass fences the plane like a scanner death, never a silently unbounded recorder.
+    const pruneMs = opts.nativeIssuancePruneMs ?? 60_000;
+    if (!Number.isSafeInteger(pruneMs) || pruneMs < 100 || pruneMs > 3_600_000)
+        throw new Error(`nativeIssuancePruneMs must be an integer between 100 and 3600000 (got ${pruneMs})`);
+    await pruneNativeIssuance(registry, Math.floor(Date.now() / 1000));
+    let pruneTimer;
+    let pruneFlight = Promise.resolve();
+    const schedulePrune = () => {
+        if (closing || fatalReason !== undefined)
+            return;
+        pruneTimer = setTimeout(() => {
+            pruneFlight = pruneNativeIssuance(registry, Math.floor(Date.now() / 1000)).then(schedulePrune, (e) => {
+                if (closing)
+                    return;
+                const copy = `native-issuance cleanup failed: ${e instanceof Error ? e.message : String(e)}`;
+                hold?.fence(copy);
+                fatalReason = fatalReason ?? copy;
+                fireFatal(copy);
+                log(`auth-plane: ${copy}`);
+            });
+        }, pruneMs);
+    };
+    const stopPrune = async () => { clearTimeout(pruneTimer); await pruneFlight; };
+    unwind.push(async () => { closing = true; await stopPrune(); });
+    schedulePrune();
     const recordsJsm = await jetstreamManager(remoteIssuer.nc);
     const authKv = await new Kvm(remoteIssuer.nc).open(epAuthBucket(space));
     const managerIssuanceGate = (instanceId) => serveIssuanceGateKv(authKv, space, { endpoint: "manager", instanceId });
@@ -477,18 +521,9 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
             return "not registered";
         return "candidate";
     };
-    const selectManagerInstance = async (owner, requested) => {
+    const listManagerInstances = async (owner) => {
         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 instances = [];
         const localManager = loadLocalManager();
         for (const raw of await scanner.scanManagerGates()) {
             if (raw.op !== undefined)
@@ -500,23 +535,33 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
             const row = parseEndpointGate(raw.data, raw.key);
             if (row.authorityFamily === "environment-manager")
                 continue;
-            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;
-            }
+            if (row.principal === `${owner}.${remoteManagerActors(instanceId).serve}`)
+                instances.push({ instanceId, placement: "remote", state: await managerGate(owner, instanceId) });
+            else if (localManager?.instanceId === instanceId && row.principal === `local.${localManager.serveIdentity.id}`)
+                instances.push({ instanceId, placement: "local", state: await managerGate(owner, instanceId) });
         }
+        return { v: 1, owner, complete: true, instances };
+    };
+    const selectManagerInstance = async (owner, requested, caller) => {
+        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 { instances } = await listManagerInstances(owner);
+        const remoteInstances = instances.filter((i) => i.placement === "remote").map((i) => i.instanceId);
+        const remoteLive = instances.filter((i) => i.placement === "remote" && i.state === "candidate").map((i) => i.instanceId);
+        const localCandidate = instances.findLast((i) => i.placement === "local" && i.state === "candidate")?.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`);
+            throw new Error(`manager-caller selection found ${remoteLive.length} live remote manager candidates for owner ${owner} (${remoteLive.join(", ")}); exactly one is required, so ${MANAGER_PIN_REMEDY[caller ?? "wire"]}`);
         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`);
+            throw new Error(`the remote manager for owner ${owner} is unavailable (${remoteInstances.length} gate${remoteInstances.length === 1 ? "" : "s"}, none live); start one with \`cotal supervise\` and retry, as this call is never routed to the local manager`);
         if (localCandidate !== undefined)
             return localCandidate;
         throw new Error(`manager-caller selection found no manager candidate for owner ${owner}`);
@@ -577,11 +622,16 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
             fileArm(t);
             await authorizeConnectCredential(reader.current(), t, Date.now);
         },
+        recordIssuance: (i) => {
+            refuseIfFenced();
+            return recordIssuance(i);
+        },
         mintConnectCredential: (args) => {
             refuseIfFenced();
             return ensureRootCredential(registry, { ...args, managerInstance: `auth-service:${space}` });
         },
         selectManagerInstance,
+        listManagerInstances,
         authorizeManagerCaller: async (owner, instanceId) => {
             refuseIfFenced();
             const verdict = await managerGate(owner, assertLifecycleToken(instanceId, "managerInstanceId"));
@@ -607,7 +657,7 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
                     const perms = mint({ generation, acceptedToken });
                     const ref = { space, owner, actor, uid, generation };
                     const prepared = await session.store.stage({
-                        version: 1, ref, sources: [actorLedgerSource(space, owner, actor, uid)], permissions: importNativeSubjectPermissions(perms),
+                        version: 1, ref, sources: [actorLedgerSource(space, owner, actor, uid)], permissions: importNativeSubjectPermissions(perms), expiresAt: t.exp,
                     });
                     await session.store.release(prepared, async () => { });
                     await writeAcceptedRow(session.accepted, acceptedToken, ref);
@@ -1447,6 +1497,7 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
             // act), then the barrier that wrote it. An unreachable release keeps the barrier alive
             // for a later close retry; successful scanner teardown is not run a second time.
             closing = true;
+            await stopPrune();
             const scannerFlight = closeScanners ??= (async () => {
                 await authAdmin?.close();
                 const results = await Promise.allSettled([reader.close(), recordsScanner.close(), scanner.close()]);
@@ -1776,6 +1827,7 @@ async function startAuthContext(o) {
             space,
             token: { key: issuer.localKeySet(), issuer: issuer.issuer },
             authorizeActor: plane.authorizeConnect,
+            recordIssuance: plane.recordIssuance,
             permissionsFor: calloutPermissions(ledgerAclResolver(dir), plane.authorizeManagerCaller, plane.verifySession, plane.issueUserCaller),
             log: (l) => console.error(l),
         });
@@ -1830,6 +1882,7 @@ async function startAuthContext(o) {
             dir,
             mintConnectCredential: plane.mintConnectCredential,
             selectManagerInstance: plane.selectManagerInstance,
+            listManagerInstances: plane.listManagerInstances,
             verifySession: plane.verifySession,
         };
         const loopback = createServer((req, res) => void handle(req, res, ctx));
@@ -2231,16 +2284,18 @@ 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)],
+    ["/manager-instances", (req, res, ctx) => handleManagerInstances(req, res, ctx, LOOPBACK_POLICY)],
     [INTERACTIVE_RETIRE_PATH, handleInteractiveLifecycleRetirement],
     [MANAGED_RETIRE_PATH, handleManagedLifecycleRetirement],
     [VERIFY_ENROLLMENT_PATH, handleVerifyManagedAgentEnrollment],
+    [TOOL_RESULT_HUMAN_PROOF_PATH, handleToolResultHumanProof],
 ]);
 /** 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, /manager-service-authority/verify-enrollment, /interactive-lifecycle/retire, /managed-lifecycle/retire" });
+            return send(res, 404, { error: "unknown path - /health, /jwks, /exchange, /manager-service-authority, /manager-instances, /manager-service-authority/verify-enrollment, /interactive-lifecycle/retire, /managed-lifecycle/retire" });
         await route(req, res, ctx);
     }
     catch (e) {
@@ -2501,7 +2556,7 @@ async function handleExchange(req, res, ctx, policy) {
             // 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)
+                ? await ctx.selectManagerInstance(owner, managerInstanceId, "agent")
                 : undefined;
             const token = await ctx.issuer.issue({
                 owner,
@@ -2536,7 +2591,7 @@ async function handleExchange(req, res, ctx, policy) {
         // 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 selectedManagerInstanceId = view === "manager-caller"
-            ? await ctx.selectManagerInstance(deriveOwnerForIdpSubject(ctx.ownerSecret, ctx.bridgeIdp.issuer, (await verifyIdpToken(idpToken, ctx.bridgeIdp)).sub), managerInstanceId)
+            ? await ctx.selectManagerInstance(deriveOwnerForIdpSubject(ctx.ownerSecret, ctx.bridgeIdp.issuer, (await verifyIdpToken(idpToken, ctx.bridgeIdp)).sub), managerInstanceId, "human")
             : undefined;
         // #2312: a session-caller bearer is signed only once the identity plane has decided that THIS
         // principal holds THAT redeemed session. The bridge's `verifySession` hook runs the decision on
@@ -2565,6 +2620,45 @@ async function handleExchange(req, res, ctx, policy) {
         return send(res, 401, { error: reason });
     }
 }
+/** The signed-in person's own Manager instances, read-only, on both faces. The proof is the IdP JWT
+ *  the human exchange verifies, and the owner is derived from it the same way, so a caller lists only
+ *  its own owner's gates. A browser-origin request is refused as on every exchange route; an
+ *  embedding's server-side bridge forwards the person's proof. Issuance still re-checks the chosen
+ *  instance. */
+async function handleManagerInstances(req, res, ctx, policy) {
+    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 (policy.requireCapability && req.headers.authorization !== `Bearer ${ctx.cap}`)
+        return refuseCapability(res, ctx, "missing/invalid exchange capability - read it from the space's auth-service.json");
+    const peer = policy.peerKey(req);
+    const peerThrottled = policy.throttled(ctx, peer);
+    const body = await readJsonBody(req);
+    if (typeof body?.idpToken !== "string" || !body.idpToken)
+        return send(res, 400, { error: "the manager instance list needs { idpToken: string }" });
+    let owner;
+    try {
+        owner = deriveOwnerForIdpSubject(ctx.ownerSecret, ctx.bridgeIdp.issuer, (await verifyIdpToken(body.idpToken, ctx.bridgeIdp)).sub);
+    }
+    catch (e) {
+        policy.recordFailure(ctx, peer);
+        const reason = e instanceof Error ? e.message : String(e);
+        console.error(`auth-service: refused a manager instance list: ${reason}`);
+        if (peerThrottled)
+            return send(res, 429, { error: "too many refused exchanges - wait a minute and retry" });
+        return send(res, 401, { error: reason });
+    }
+    try {
+        return send(res, 200, await ctx.listManagerInstances(owner));
+    }
+    catch (e) {
+        // The proof was good and the gate read was not: unavailable, never an empty list.
+        return send(res, 503, { error: `the manager instance list is unavailable: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}
 /** The typed manager authority exchange, served on both faces. The face's policy decides whether the
  *  loopback capability is demanded; on the public face the verified IdP JWT is the proof, and the
  *  dispatcher reads the caller's scope from the ledger either way. */
@@ -2606,6 +2700,40 @@ export async function handleManagerServiceAuthority(req, res, ctx, policy) {
         return send(res, 403, { error: reason });
     }
 }
+/** Decide one signed password proof against the host's authenticated session subject.
+ * The subject is an equality constraint, never the source of the derived owner. */
+export async function handleToolResultHumanProof(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 refuseCapability(res, ctx, "missing/invalid exchange capability - human proof verification is a loopback host action");
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch (error) {
+        return send(res, error instanceof RequestBodyError ? error.status : 400, { error: "invalid human proof request" });
+    }
+    if (!body || typeof body !== "object" || Array.isArray(body) ||
+        Object.keys(body).some(key => key !== "idpToken" && key !== "subject") ||
+        !("idpToken" in body) || typeof body.idpToken !== "string" || !body.idpToken ||
+        !("subject" in body) || typeof body.subject !== "string" || !body.subject)
+        return send(res, 400, { error: "human proof verification needs only { idpToken, subject }" });
+    try {
+        const proof = await verifyToolResultHumanProof(body.idpToken, ctx.bridgeIdp);
+        if (proof.sub !== body.subject)
+            return send(res, 403, { error: "human proof subject does not match the session" });
+        const owner = deriveOwnerForIdpSubject(ctx.ownerSecret, ctx.bridgeIdp.issuer, proof.sub);
+        return send(res, 200, { authorized: true, owner, ...proof });
+    }
+    catch {
+        return send(res, 403, { error: "fresh signed password proof required" });
+    }
+}
 /** The advertised broker address the public bundle carries — the URL participants will dial, so
  *  the same scheme family `cotal meshes add` accepts. Exported for the producer/consumer contract
  *  smoke; returns the refusal sentence, or undefined when the address is usable. */
@@ -2708,6 +2836,7 @@ function makePublicHandler(ctx, policy, bundle) {
         ],
         ["/exchange", (req, res, c) => handleExchange(req, res, c, policy)],
         ["/manager-service-authority", (req, res, c) => handleManagerServiceAuthority(req, res, c, policy)],
+        ["/manager-instances", (req, res, c) => handleManagerInstances(req, res, c, policy)],
         [
             "/.well-known/cotal-mesh",
             (req, res) => {
@@ -2740,7 +2869,7 @@ function makePublicHandler(ctx, policy, bundle) {
             try {
                 const route = routes.get(req.url ?? "");
                 if (!route)
-                    return send(res, 404, { error: "unknown path - /health, /jwks, /exchange, /manager-service-authority, /.well-known/cotal-mesh" });
+                    return send(res, 404, { error: "unknown path - /health, /jwks, /exchange, /manager-service-authority, /manager-instances, /.well-known/cotal-mesh" });
                 await route(req, res, ctx);
             }
             catch (e) {