@agent-native/core 0.203.2-nightly-20261007213109 → 0.204.0

package/dist/mcp/actions/set-service-principal-lifecycle.js

@@ -0,0 +1,150 @@
+/**
+ * Suspend, retire, or resume an org service principal.
+ *
+ * The committed lifecycle write is what blocks new work (admission, tool
+ * dispatch, and run start read it). Suspended and retired also contain the
+ * principal: in-flight agent runs it owns are aborted, and retired additionally
+ * revokes every active token. The write commits before containment runs, and a
+ * containment failure is returned (`containmentErrors`, `contained: false`)
+ * rather than swallowed: a partial containment must not read as complete.
+ *
+ * Owner/admin only, and not callable by the agent tool loop.
+ */
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { containServicePrincipal, prepareServicePrincipalContainment, } from "../../agent/contain-principal.js";
+import { orgAdminAudit, recordOrgAdminAuditEvent, } from "../../audit/org-admin.js";
+import { SERVICE_PRINCIPAL_LIFECYCLES, ServicePrincipalRetiredError, getServicePrincipalPolicy, setServicePrincipalLifecycle, withServicePrincipalLifecycleLock, } from "../../org/service-principal-policy.js";
+import { ensureConnectTables, revokeServiceTokensByName, } from "../connect-store.js";
+import { describeServicePrincipal, parseServiceName, requireKnownServicePrincipal, } from "./service-principal-input.js";
+import { requireServiceTokenCaller, ServiceTokenError, } from "./service-token-access.js";
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+export default defineAction({
+    description: "Suspend, retire, or resume an org service principal. Suspended and retired principals are refused at MCP admission and run start, and their in-flight agent runs are aborted; retired also revokes every active token. The result reports abortedRuns, revokedTokens, and any containmentErrors (contained: false means containment is incomplete — retry). Org owner/admin only.",
+    schema: z.object({
+        serviceName: z
+            .string()
+            .min(1)
+            .max(64)
+            .describe("Service name from list-org-service-tokens"),
+        lifecycle: z.enum(SERVICE_PRINCIPAL_LIFECYCLES),
+        reason: z.string().trim().max(500).optional(),
+    }),
+    toolCallable: false,
+    audit: orgAdminAudit({
+        targetType: "service-principal",
+        targetId: (args) => String(args.serviceName ?? ""),
+        summary: (args, result) => {
+            const r = result;
+            const errors = r.containmentErrors?.length ?? 0;
+            return `Set ${r.serviceEmail ?? args.serviceName} to ${args.lifecycle}: ${r.abortedRuns ?? 0} runs aborted, ${r.revokedTokens ?? 0} tokens revoked${errors ? `, ${errors} containment errors` : ""}`;
+        },
+    }),
+    run: async (args, ctx) => {
+        const caller = await requireServiceTokenCaller({
+            userEmail: ctx?.userEmail,
+            orgId: ctx?.orgId,
+            level: "manage",
+        });
+        const serviceName = parseServiceName(args.serviceName);
+        await requireKnownServicePrincipal(caller.orgId, serviceName);
+        let policy;
+        let abortedRuns = 0;
+        let revokedTokens = 0;
+        let resumeBlocked = false;
+        let lifecycleCommitted = false;
+        const containmentErrors = [];
+        try {
+            if (args.lifecycle !== "active") {
+                await prepareServicePrincipalContainment();
+                if (args.lifecycle === "retired")
+                    await ensureConnectTables();
+                policy = await withServicePrincipalLifecycleLock(caller.orgId, serviceName, (db) => setServicePrincipalLifecycle(caller.orgId, serviceName, args.lifecycle, { actorEmail: caller.email, reason: args.reason || null }, db));
+                lifecycleCommitted = true;
+                policy = await withServicePrincipalLifecycleLock(caller.orgId, serviceName, async (db) => {
+                    const current = await getServicePrincipalPolicy(caller.orgId, serviceName, db);
+                    if (!current || current.lifecycle !== args.lifecycle) {
+                        throw new ServiceTokenError("The service principal lifecycle changed concurrently. Read its current state before retrying.", 409);
+                    }
+                    try {
+                        const contained = await containServicePrincipal(caller.orgId, serviceName);
+                        abortedRuns = contained.abortedRuns;
+                        containmentErrors.push(...contained.containmentErrors);
+                    }
+                    catch (error) {
+                        containmentErrors.push(`abort runs: ${errorMessage(error)}`);
+                    }
+                    if (args.lifecycle === "retired") {
+                        try {
+                            revokedTokens = await revokeServiceTokensByName(caller.orgId, serviceName);
+                        }
+                        catch (error) {
+                            containmentErrors.push(`revoke tokens: ${errorMessage(error)}`);
+                        }
+                    }
+                    return current;
+                });
+            }
+            else {
+                policy = await withServicePrincipalLifecycleLock(caller.orgId, serviceName, async (db) => {
+                    const current = await getServicePrincipalPolicy(caller.orgId, serviceName, db);
+                    if (current?.lifecycle === "retired") {
+                        throw new ServicePrincipalRetiredError();
+                    }
+                    if (current?.lifecycle === "suspended") {
+                        try {
+                            const contained = await containServicePrincipal(caller.orgId, serviceName);
+                            abortedRuns = contained.abortedRuns;
+                            containmentErrors.push(...contained.containmentErrors);
+                        }
+                        catch (error) {
+                            containmentErrors.push(`abort runs: ${errorMessage(error)}`);
+                        }
+                        if (containmentErrors.length > 0) {
+                            resumeBlocked = true;
+                            return current;
+                        }
+                    }
+                    return setServicePrincipalLifecycle(caller.orgId, serviceName, "active", { actorEmail: caller.email, reason: args.reason || null }, db);
+                });
+                if (resumeBlocked) {
+                    throw new ServiceTokenError("The service principal could not be resumed because containment is incomplete. Retry after its in-flight runs stop.", 503);
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof ServicePrincipalRetiredError) {
+                throw new ServiceTokenError(error.message, error.statusCode);
+            }
+            if (error instanceof ServiceTokenError)
+                throw error;
+            console.error("[service-principal] Lifecycle write failed:", error);
+            throw new ServiceTokenError(lifecycleCommitted
+                ? "The lifecycle changed, but containment could not be confirmed. Retry the lifecycle request to finish containment."
+                : "Could not change the service principal lifecycle. Nothing was changed; try again.", 503);
+        }
+        const principal = describeServicePrincipal(caller.orgId, serviceName, policy);
+        if (args.lifecycle !== "active") {
+            await recordOrgAdminAuditEvent({
+                action: "contain-service-principal",
+                targetType: "service-principal",
+                targetId: serviceName,
+                summary: `Contained ${principal.serviceEmail}: ${abortedRuns} runs aborted, ${revokedTokens} tokens revoked${containmentErrors.length ? `, ${containmentErrors.length} errors` : ""}`,
+                userEmail: caller.email,
+                orgId: caller.orgId,
+                status: containmentErrors.length ? "error" : "success",
+                caller: ctx?.caller,
+            });
+        }
+        return {
+            orgId: caller.orgId,
+            serviceEmail: principal.serviceEmail,
+            lifecycle: args.lifecycle,
+            principal,
+            abortedRuns,
+            revokedTokens,
+            contained: containmentErrors.length === 0,
+            containmentErrors,
+        };
+    },
+});

package/dist/mcp/actions/set-service-principal-policy.d.ts

@@ -0,0 +1,14 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    serviceName: string;
+    ownerEmail?: string;
+    team?: string;
+    riskTier?: "high" | "low" | "medium";
+    purpose?: string;
+    allowedActions?: string[];
+}, {
+    orgId: string;
+    serviceEmail: string;
+    principal: import("./service-principal-input.js").ServicePrincipalView;
+    changedFields: ("allowedActions" | "ownerEmail" | "purpose" | "riskTier" | "team")[];
+}>;
+export default _default;

package/dist/mcp/actions/set-service-principal-policy.js

@@ -0,0 +1,105 @@
+/**
+ * Set who is accountable for an org service principal and which actions it may
+ * call. Fields left out keep their stored value; `null` clears one (and for
+ * `allowedActions`, `null` means unrestricted). Lifecycle (suspend/resume) is a
+ * separate action because it also contains in-flight work.
+ *
+ * Owner/admin only, and not callable by the agent tool loop: a prompt-injected
+ * agent must not be able to widen a grant.
+ */
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { orgAdminAudit } from "../../audit/org-admin.js";
+import { upsertServicePrincipalPolicy, } from "../../org/service-principal-policy.js";
+import { allowedActionsSchema, assertOwnerIsOrgMember, describeServicePrincipal, normalizeAllowedActions, ownerEmailSchema, parseServiceName, purposeSchema, requireKnownServicePrincipal, riskTierSchema, teamSchema, } from "./service-principal-input.js";
+import { requireServiceTokenCaller, ServiceTokenError, } from "./service-token-access.js";
+const FIELDS = [
+    "ownerEmail",
+    "team",
+    "riskTier",
+    "purpose",
+    "allowedActions",
+];
+export default defineAction({
+    description: "Set the governance record of an org service principal: accountable owner (an org member), team, risk tier, purpose, and the action allow-list (null = unrestricted, [] = nothing, a trailing * matches a prefix). Omitted fields are unchanged; null clears a field. Org owner/admin only.",
+    schema: z.object({
+        serviceName: z
+            .string()
+            .min(1)
+            .max(64)
+            .describe("Service name from list-org-service-tokens"),
+        ownerEmail: ownerEmailSchema.nullable().optional(),
+        team: teamSchema.nullable().optional(),
+        riskTier: riskTierSchema.optional(),
+        purpose: purposeSchema.nullable().optional(),
+        allowedActions: allowedActionsSchema.nullable().optional(),
+    }),
+    toolCallable: false,
+    audit: orgAdminAudit({
+        targetType: "service-principal",
+        targetId: (args) => String(args.serviceName ?? ""),
+        // The grant list is only ever counted, never echoed, into the event.
+        recordInputs: false,
+        summary: (args, result) => {
+            const r = result;
+            const changed = r.changedFields ?? [];
+            const detail = changed.map((f) => f === "allowedActions"
+                ? args.allowedActions == null
+                    ? "allowedActions: unrestricted"
+                    : `allowedActions: ${args.allowedActions.length} entries`
+                : f);
+            return `Updated governance of ${r.serviceEmail ?? args.serviceName}: ${detail.length ? detail.join(", ") : "no changes"}`;
+        },
+    }),
+    run: async (args, ctx) => {
+        const caller = await requireServiceTokenCaller({
+            userEmail: ctx?.userEmail,
+            orgId: ctx?.orgId,
+            level: "manage",
+        });
+        const serviceName = parseServiceName(args.serviceName);
+        const existing = await requireKnownServicePrincipal(caller.orgId, serviceName);
+        const input = {};
+        if (args.ownerEmail !== undefined) {
+            input.ownerEmail =
+                args.ownerEmail === null
+                    ? null
+                    : await assertOwnerIsOrgMember(caller.orgId, args.ownerEmail);
+        }
+        if (args.team !== undefined)
+            input.team = args.team;
+        if (args.riskTier !== undefined)
+            input.riskTier = args.riskTier;
+        if (args.purpose !== undefined)
+            input.purpose = args.purpose;
+        if (args.allowedActions !== undefined) {
+            input.allowedActions = normalizeAllowedActions(args.allowedActions);
+        }
+        const before = {
+            ownerEmail: existing?.ownerEmail ?? null,
+            team: existing?.team ?? null,
+            riskTier: existing?.riskTier ?? "medium",
+            purpose: existing?.purpose ?? null,
+            allowedActions: existing?.allowedActions ?? null,
+        };
+        const changedFields = FIELDS.filter((field) => input[field] !== undefined &&
+            JSON.stringify(input[field]) !== JSON.stringify(before[field]));
+        let saved = existing;
+        if (Object.keys(input).length > 0) {
+            try {
+                saved = await upsertServicePrincipalPolicy(caller.orgId, serviceName, input);
+            }
+            catch (error) {
+                console.error("[service-principal] Policy write failed:", error);
+                throw new ServiceTokenError("Could not save the service principal policy. Nothing was changed; try again.", 503);
+            }
+        }
+        const principal = describeServicePrincipal(caller.orgId, serviceName, saved);
+        return {
+            orgId: caller.orgId,
+            serviceEmail: principal.serviceEmail,
+            principal,
+            changedFields,
+        };
+    },
+});

package/dist/mcp/build-server.js

@@ -6,6 +6,8 @@ import { isActionContractError, isActionExposedToExternalAgents, isActionHiddenF
 import { describeToolResultImages, extractAgentImagesFromActionResult, } from "../agent/tool-result-images.js";
 import { getAppConfig } from "../app-config/store.js";
 import { isMcpActionResult } from "../mcp-client/app-result.js";
+import { assertServicePrincipalMayCall, assertServicePrincipalMayRun, recordServicePrincipalDenial, ServicePrincipalRefusedError, } from "../org/service-principal-guard.js";
+import { isActionGranted } from "../org/service-principal-policy.js";
 import { writeActionChangeMarker } from "../server/action-change-marker-write.js";
 import { getConfiguredAppBasePath } from "../server/app-base-path.js";
 import { readDeployCredentialEnv } from "../server/credential-provider.js";
@@ -1843,10 +1845,44 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
             requestState,
         });
     }
+    // Read per request, never cached: a principal suspended or re-scoped after
+    // admission is stopped by the next list or call.
+    async function resolveServiceGrant(actionName) {
+        try {
+            return await assertServicePrincipalMayRun(effectiveIdentity?.userEmail, typeof effectiveIdentity?.orgId === "string"
+                ? effectiveIdentity.orgId
+                : undefined);
+        }
+        catch (error) {
+            if (actionName && error instanceof ServicePrincipalRefusedError) {
+                await recordServicePrincipalDenial({
+                    email: effectiveIdentity?.userEmail,
+                    orgId: effectiveIdentity?.orgId,
+                    actionName,
+                    caller: "mcp",
+                    error,
+                });
+            }
+            throw error;
+        }
+    }
+    // MCP App widgets belong to their action: outside the grant, the resource is
+    // as invisible as the tool.
+    async function grantedAdvertisedActions(actionName) {
+        const { allowedActions } = await resolveServiceGrant(actionName);
+        return allowedActions === null
+            ? advertisedActions
+            : Object.fromEntries(Object.entries(advertisedActions).filter(([name]) => isActionGranted(allowedActions, name)));
+    }
+    async function grantedResourceActions(actionName) {
+        return grantedAdvertisedActions(actionName);
+    }
     server.setRequestHandler("tools/list", async (request, ctx) => {
         const startedAt = Date.now();
+        const { allowedActions } = await resolveServiceGrant("mcp:tools/list");
         const result = await withCallerContext(async () => {
             const tools = await Promise.all(Object.entries(advertisedActions)
+                .filter(([name]) => isActionGranted(allowedActions, name))
                 .sort(([a], [b]) => compareMcpCatalogValues(a, b))
                 .map(async ([name, entry]) => {
                 const hasLink = typeof entry.link === "function";
@@ -1901,15 +1937,18 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                     entry.tool.description ??
                     name;
                 const title = agentNativeToolTitle(name, entry.tool.title);
-                const annotations = directoryCatalog
-                    ? { title, ...entry.mcpAnnotations }
-                    : {
-                        title,
-                        readOnlyHint: entry.readOnly === true,
-                        destructiveHint: entry.publicAgent?.isConsequential === true ||
-                            entry.needsApproval !== undefined,
-                        openWorldHint: false,
-                    };
+                const annotations = {
+                    title,
+                    ...(entry.mcpAnnotations ??
+                        (directoryCatalog
+                            ? undefined
+                            : {
+                                readOnlyHint: entry.readOnly === true,
+                                destructiveHint: entry.publicAgent?.isConsequential === true ||
+                                    entry.needsApproval !== undefined,
+                                openWorldHint: false,
+                            })),
+                };
                 if (directoryCatalog) {
                     delete annotations["agent-native/producesOpenLink"];
                 }
@@ -1942,6 +1981,7 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                 tools.push(widgetSessionTool);
             if (fullCatalogRequested &&
                 config.askAgent &&
+                isActionGranted(allowedActions, "ask-agent") &&
                 hasMcpOAuthScope(effectiveIdentity?.oauthScopes, "mcp:write")) {
                 tools.push({
                     name: "ask-agent",
@@ -2004,6 +2044,31 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                     : undefined;
         const result = await withCallerContext(async () => {
             const { name, arguments: args } = request.params;
+            try {
+                const { allowedActions } = await resolveServiceGrant();
+                assertServicePrincipalMayCall(allowedActions, name);
+            }
+            catch (error) {
+                if (!(error instanceof ServicePrincipalRefusedError))
+                    throw error;
+                if (error.statusCode !== 403)
+                    throw error;
+                failure = {
+                    errorType: error.errorCode,
+                    errorMessage: error.message,
+                };
+                await recordServicePrincipalDenial({
+                    email: effectiveIdentity?.userEmail,
+                    orgId: getRequestOrgId(),
+                    actionName: name,
+                    caller: "mcp",
+                    error,
+                });
+                return {
+                    content: [{ type: "text", text: error.message }],
+                    isError: true,
+                };
+            }
             if (name === "ask-agent" && config.askAgent) {
                 if (!fullCatalogRequested) {
                     failure = {
@@ -2299,8 +2364,9 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
     if (supportsMcpApps) {
         server.setRequestHandler("resources/list", async (request, ctx) => {
             const startedAt = Date.now();
+            const grantedActions = await grantedResourceActions("mcp:resources/list");
             const result = await withCallerContext(async () => {
-                const mcpAppResources = await getMcpAppResources(config, advertisedActions, effectiveIdentity, requestMeta);
+                const mcpAppResources = await getMcpAppResources(config, grantedActions, effectiveIdentity, requestMeta);
                 return {
                     resources: mcpAppResources
                         .sort((a, b) => compareMcpCatalogValues(a.uri, b.uri))
@@ -2323,11 +2389,12 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
             return result;
         });
         server.setRequestHandler("resources/templates/list", async () => {
+            const grantedActions = await grantedResourceActions("mcp:resources/templates/list");
             if (config.catalogMode === "directory") {
                 return withCallerContext(async () => ({ resourceTemplates: [] }));
             }
             return withCallerContext(async () => {
-                const mcpAppResources = await getMcpAppResources(config, advertisedActions, effectiveIdentity, requestMeta);
+                const mcpAppResources = await getMcpAppResources(config, grantedActions, effectiveIdentity, requestMeta);
                 return {
                     resourceTemplates: mcpAppResources
                         .sort((a, b) => compareMcpCatalogValues(a.uri, b.uri))
@@ -2359,11 +2426,12 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                 });
             };
             try {
+                const grantedActions = await grantedResourceActions("mcp:resources/read");
                 return await withCallerContext(async () => {
                     const uri = request.params?.uri;
                     let found = null;
                     const resourceActions = mcpAppWidgetsEnabledForIdentity(config, effectiveIdentity)
-                        ? Object.entries(advertisedActions)
+                        ? Object.entries(grantedActions)
                         : [];
                     const orderedResourceActions = config.catalogMode === "directory"
                         ? resourceActions.sort(([a], [b]) => compareMcpCatalogValues(a, b))
@@ -2671,6 +2739,42 @@ function matchesStoredConnectTokenIdentity(resolution, input) {
  * organization.
  */
 async function admitIssuedCredential(result, requestOrigin, orgResolution, issuedAt) {
+    const admitted = await checkIssuedCredential(result, requestOrigin, orgResolution, issuedAt);
+    return admitted.authed ? admitServicePrincipal(admitted) : admitted;
+}
+/**
+ * A service identity is admitted only while its governance record says it may
+ * run. Every credential branch that can yield one ends here; a caller whose
+ * email is not service-shaped returns before any database read.
+ */
+async function admitServicePrincipal(result) {
+    const email = result.identity?.userEmail;
+    try {
+        await assertServicePrincipalMayRun(email, typeof result.identity?.orgId === "string"
+            ? result.identity.orgId
+            : undefined);
+        return result;
+    }
+    catch (error) {
+        if (!(error instanceof ServicePrincipalRefusedError))
+            throw error;
+        if (error.statusCode === 403) {
+            await recordServicePrincipalDenial({
+                email,
+                orgId: typeof result.identity?.orgId === "string"
+                    ? result.identity.orgId
+                    : undefined,
+                actionName: "mcp:admission",
+                caller: "mcp",
+                error,
+            });
+        }
+        return error.statusCode === 503
+            ? { authed: false, unavailable: true }
+            : { authed: false };
+    }
+}
+async function checkIssuedCredential(result, requestOrigin, orgResolution, issuedAt) {
     const { checkCredentialEmailRetirement, checkCredentialOrgMembership } = await import("./credential-membership.js");
     if (result.identity.userEmail) {
         const retirement = await checkCredentialEmailRetirement({
@@ -2862,7 +2966,7 @@ export async function verifyAuth(authHeader, ownerEmailHeader, options = {}) {
         // sibling app per call, so they are cross-app A2A tokens.
         const admitted = tokenScope === MCP_CONNECT_SCOPE && !firstPartyMcp
             ? await admitIssuedCredential(verified, options.requestOrigin, orgResolution, typeof payload.iat === "number" ? payload.iat : undefined)
-            : verified;
+            : await admitServicePrincipal(verified);
         if (admitted.authed && tokenScope === MCP_CONNECT_SCOPE) {
             await markConnectTokenUsed(payload.jti);
         }

package/dist/mcp/connect-route.js

@@ -9,9 +9,11 @@ import { getOrgDomain } from "../org/context.js";
 import { getSession, getConfiguredLoginHtml, isLoopbackRequest, } from "../server/auth.js";
 import { CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE } from "../server/credential-membership-unavailable.js";
 import { readDeployCredentialEnv } from "../server/credential-provider.js";
+import { publicFrameworkPath } from "../server/framework-route-prefix.js";
 import { readBody } from "../server/h3-helpers.js";
+import { FRAMEWORK_INTERNAL_ROUTE_PREFIX } from "../shared/framework-route-prefix.js";
 import { MCP_CONNECT_MCP_URL_TEMPLATE, getMcpConnectGuides, getMcpStaticTokenFallback, interpolateMcpConnectTemplate, resolveMcpConnectGuideId, } from "../shared/mcp-connect-content.js";
-import { ensureConnectTables, recordMintedToken, listTokens, revokeToken, normalizeServiceName, serviceIdentityEmail, createDeviceCode, getDeviceCode, getDeviceCodeByUserCode, approveDeviceCode, consumeDeviceCode, claimDeviceCodeForMint, finishDeviceCodeMint, expireDeviceCode, MCP_CONNECT_OAUTH_CLIENT_ID, MCP_CONNECT_SCOPE, DEFAULT_TOKEN_TTL_DAYS, MIN_TOKEN_TTL_DAYS, MAX_TOKEN_TTL_DAYS, DEVICE_CODE_TTL_MS, } from "./connect-store.js";
+import { ensureConnectTables, recordMintedToken, listTokens, revokeToken, normalizeServiceName, serviceIdentityEmail, createDeviceCode, getDeviceCode, getDeviceCodeByUserCode, approveDeviceCode, consumeDeviceCode, claimDeviceCodeForMint, finishDeviceCodeMint, expireDeviceCode, MCP_CONNECT_OAUTH_CLIENT_ID, MCP_CONNECT_SCOPE, DEFAULT_TOKEN_TTL_DAYS, MIN_TOKEN_TTL_DAYS, MAX_TOKEN_TTL_DAYS, MAX_SERVICE_TOKEN_TTL_DAYS, DEVICE_CODE_TTL_MS, } from "./connect-store.js";
 import { McpCredentialIssuanceError, withMcpCredentialIssuance, } from "./credential-issuance.js";
 import { MCP_OAUTH_DEFAULT_SCOPE, signMcpOAuthAccessToken, } from "./oauth-token.js";
 import { resolveMcpOrgChoices } from "./org-choice.js";
@@ -131,11 +133,11 @@ async function resolveOrgDomain(orgId) {
         return undefined;
     }
 }
-function clampTtlDays(input) {
+function clampTtlDays(input, maxDays = MAX_TOKEN_TTL_DAYS) {
     const n = Number(input);
     if (!Number.isFinite(n))
         return DEFAULT_TOKEN_TTL_DAYS;
-    return Math.min(MAX_TOKEN_TTL_DAYS, Math.max(MIN_TOKEN_TTL_DAYS, Math.floor(n)));
+    return Math.min(maxDays, Math.max(MIN_TOKEN_TTL_DAYS, Math.floor(n)));
 }
 /**
  * Mint a connect-scoped JWT and record it. The token value is returned to the
@@ -218,7 +220,7 @@ export async function mintOrgServiceToken(params) {
     const serviceName = normalizeServiceName(params.serviceName);
     const serviceEmail = serviceIdentityEmail(serviceName, params.orgId);
     const orgDomain = await resolveOrgDomain(params.orgId);
-    const ttlDays = clampTtlDays(params.ttlDays ?? DEFAULT_TOKEN_TTL_DAYS);
+    const ttlDays = clampTtlDays(params.ttlDays ?? DEFAULT_TOKEN_TTL_DAYS, MAX_SERVICE_TOKEN_TTL_DAYS);
     await prepareConnectIssuance();
     return withMcpCredentialIssuance({
         email: params.createdBy,
@@ -605,6 +607,10 @@ function renderConnectPage(params) {
   .tok:last-child { border-bottom: none; }
   .tok .meta { color: var(--subtle); font-size: 0.74rem; margin-top: 0.1rem; }
   .tok.revoked { opacity: 0.45; }
+  .pstate { font-size: 0.68rem; padding: 0.05rem 0.4rem; margin-inline-start: 0.4rem;
+    border: 1px solid var(--border); border-radius: 999px; color: var(--subtle); }
+  .pstate.active { color: var(--ok); }
+  .pstate.suspended { color: var(--error); }
   .empty-state {
     color: var(--subtle); font-size: 0.78rem; line-height: 1.45;
     padding: 0.3rem 0 0.45rem;
@@ -821,11 +827,22 @@ function renderConnectPage(params) {
     </summary>
     <div id="tokenList" class="token-list"><div class="empty-state">${localize(connectMessages.checkingConnections)}</div></div>
   </details>
+
+  <details id="principals" class="connections hidden">
+    <summary>
+      <span class="connections-title">${localize(connectMessages.servicePrincipals)}</span>
+      <span id="principalsState" class="connections-state hidden" aria-live="polite"></span>
+      <span class="chev" aria-hidden="true"></span>
+    </summary>
+    <div id="principalMsg" class="empty-state hidden" role="status"></div>
+    <div id="principalList" class="token-list"></div>
+  </details>
 </div>
 <script>
 (function () {
   var BASE = ${JSON.stringify(joinAppPath(connectBasePath, MCP_PUBLIC_ROUTE_PREFIX + "/connect"))};
   var USER_CODE = ${JSON.stringify(safeUserCode || null)};
+  var ACTIONS = ${JSON.stringify(joinAppPath(connectBasePath, publicFrameworkPath(`${FRAMEWORK_INTERNAL_ROUTE_PREFIX}/actions`)))};
   var COPY = ${JSON.stringify(connectMessages)};
   var msgEl = document.getElementById("msg");
   var connectionsEl = document.getElementById("connections");
@@ -988,6 +1005,100 @@ function renderConnectPage(params) {
     }
   }
 
+   // Governance view over the org's service principals. Hidden when the caller
+   // has no org (400/401/403); route failures are shown, never read as "none".
+  var principalsEl = document.getElementById("principals");
+  var principalsStateEl = document.getElementById("principalsState");
+  var principalListEl = document.getElementById("principalList");
+  var principalMsgEl = document.getElementById("principalMsg");
+  var PRINCIPAL_STATES = {
+    ungoverned: "principalUngoverned", active: "principalActive",
+    suspended: "principalSuspended", retired: "principalRetired"
+  };
+  var RISK_TIERS = { low: "riskLow", medium: "riskMedium", high: "riskHigh" };
+
+  function principalNote(text) {
+    principalMsgEl.textContent = text;
+    principalMsgEl.classList.toggle("hidden", !text);
+  }
+
+  async function setLifecycle(name, lifecycle, btn) {
+    btn.disabled = true;
+    var r = await postActionJson("set-service-principal-lifecycle", { serviceName: name, lifecycle: lifecycle });
+    await loadPrincipals();
+    if (!r.ok) principalNote(COPY.couldNotUpdatePrincipal);
+    else if (r.data && r.data.contained === false) principalNote(COPY.containmentIncomplete);
+  }
+
+  async function postActionJson(name, body) {
+    var res = await fetch(ACTIONS + "/" + name, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      credentials: "same-origin",
+      body: JSON.stringify(body)
+    });
+    var data = null;
+    var unreadable = false;
+    try { data = await res.json(); } catch (e) { unreadable = true; }
+    return { ok: res.ok && !unreadable, status: res.status, data: data };
+  }
+
+  async function loadPrincipals() {
+    principalNote("");
+    try {
+      var res = await fetch(ACTIONS + "/list-org-service-tokens", { credentials: "same-origin" });
+       if (res.status === 400 || res.status === 401 || res.status === 403) {
+        principalsEl.classList.add("hidden");
+        return;
+      }
+      if (!res.ok) throw new Error("HTTP " + res.status);
+      var data = await res.json();
+      var principals = (data && data.principals) || [];
+      if (!principals.length) {
+        principalsEl.classList.add("hidden");
+        return;
+      }
+      principalsEl.classList.remove("hidden");
+      var needAction = principals.filter(function (p) { return p.state === "ungoverned"; }).length;
+      principalsStateEl.textContent = needAction ? String(needAction) : "";
+      principalsStateEl.classList.toggle("hidden", needAction === 0);
+      principalListEl.innerHTML = "";
+      principals.forEach(function (p) {
+        var div = document.createElement("div");
+        div.className = "tok" + (p.state === "retired" ? " revoked" : "");
+        var left = document.createElement("div");
+        var title = document.createElement("div");
+        title.textContent = p.serviceName;
+        var badge = document.createElement("span");
+        badge.className = "pstate " + p.state;
+        badge.textContent = COPY[PRINCIPAL_STATES[p.state]] || p.state;
+        title.appendChild(badge);
+        var meta = document.createElement("div");
+        meta.className = "meta";
+        meta.textContent = p.state === "ungoverned"
+          ? COPY.principalUngovernedHint
+          : (p.ownerEmail ? COPY.principalOwner + ": " + p.ownerEmail + " · " : "") +
+            COPY.principalRisk + ": " + (COPY[RISK_TIERS[p.riskTier]] || p.riskTier);
+        left.appendChild(title); left.appendChild(meta);
+        div.appendChild(left);
+        var next = p.state === "suspended" ? "active" : p.state === "retired" ? null : "suspended";
+        if (data.canManage && next) {
+          var btn = document.createElement("button");
+          btn.className = "ghost";
+          btn.textContent = next === "active" ? COPY.resume : COPY.suspend;
+          btn.onclick = function () { setLifecycle(p.serviceName, next, btn).catch(function () { btn.disabled = false; principalNote(COPY.couldNotUpdatePrincipal); }); };
+          div.appendChild(btn);
+        }
+        principalListEl.appendChild(div);
+      });
+    } catch (e) {
+      principalsEl.classList.remove("hidden");
+      principalsStateEl.textContent = COPY.unavailable;
+      principalsStateEl.classList.remove("hidden");
+      principalNote(COPY.couldNotLoadConnections);
+    }
+  }
+
   document.getElementById("authorizeBtn").onclick = async function () {
     var btn = this;
     setButtonLoading(btn, USER_CODE ? COPY.authorizingDevice : COPY.creatingToken);
@@ -1078,6 +1189,7 @@ function renderConnectPage(params) {
   };
 
   loadTokens();
+  if (!USER_CODE) loadPrincipals();
 })();
 </script>
 </body>