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

package/dist/localization/core-messages/supplemental/en-US.js

@@ -54,6 +54,21 @@ export const mcpConnectMessages = {
     couldNotCreate: "Could not create token.",
     networkError: "Network error. Please try again.",
     urlTitle: "Your MCP URL",
+    servicePrincipals: "Service principals",
+    principalUngoverned: "Ungoverned",
+    principalActive: "Active",
+    principalSuspended: "Suspended",
+    principalRetired: "Retired",
+    principalUngovernedHint: "No owner or action grant is set.",
+    principalOwner: "Owner",
+    principalRisk: "Risk",
+    riskLow: "low",
+    riskMedium: "medium",
+    riskHigh: "high",
+    suspend: "Suspend",
+    resume: "Resume",
+    couldNotUpdatePrincipal: "Could not update the service principal.",
+    containmentIncomplete: "Updated, but some runs or tokens could not be stopped. Try again.",
 };
 export const mcpSettingsMessages = {
     mcpTitle: "MCP",

package/dist/localization/core-messages/supplemental/es-ES.js

@@ -54,6 +54,21 @@ export const mcpConnectMessages = {
     couldNotCreate: "No se pudo crear el token.",
     networkError: "Error de red. Inténtalo de nuevo.",
     urlTitle: "Tu URL de MCP",
+    servicePrincipals: "Principales de servicio",
+    principalUngoverned: "Sin gobernanza",
+    principalActive: "Activo",
+    principalSuspended: "Suspendido",
+    principalRetired: "Retirado",
+    principalUngovernedHint: "No hay propietario ni permisos de acciones definidos.",
+    principalOwner: "Propietario",
+    principalRisk: "Riesgo",
+    riskLow: "bajo",
+    riskMedium: "medio",
+    riskHigh: "alto",
+    suspend: "Suspender",
+    resume: "Reanudar",
+    couldNotUpdatePrincipal: "No se pudo actualizar el principal de servicio.",
+    containmentIncomplete: "Actualizado, pero no se pudieron detener algunas ejecuciones o tokens. Inténtalo de nuevo.",
 };
 export const mcpSettingsMessages = {
     mcpTitle: "MCP",

package/dist/localization/core-messages/supplemental/fr-FR.js

@@ -54,6 +54,21 @@ export const mcpConnectMessages = {
     couldNotCreate: "Impossible de créer le jeton.",
     networkError: "Erreur réseau. Réessayez.",
     urlTitle: "Votre URL MCP",
+    servicePrincipals: "Principaux de service",
+    principalUngoverned: "Non gouverné",
+    principalActive: "Actif",
+    principalSuspended: "Suspendu",
+    principalRetired: "Retiré",
+    principalUngovernedHint: "Aucun propriétaire ni autorisation d'actions n'est défini.",
+    principalOwner: "Propriétaire",
+    principalRisk: "Risque",
+    riskLow: "faible",
+    riskMedium: "moyen",
+    riskHigh: "élevé",
+    suspend: "Suspendre",
+    resume: "Reprendre",
+    couldNotUpdatePrincipal: "Impossible de mettre à jour le principal de service.",
+    containmentIncomplete: "Mis à jour, mais certaines exécutions ou certains jetons n'ont pas pu être arrêtés. Réessayez.",
 };
 export const mcpSettingsMessages = {
     mcpTitle: "MCP",

package/dist/localization/core-messages/supplemental/hi-IN.js

@@ -54,6 +54,21 @@ export const mcpConnectMessages = {
     couldNotCreate: "Token बनाया नहीं जा सका।",
     networkError: "Network error. फिर से कोशिश करें।",
     urlTitle: "आपका MCP URL",
+    servicePrincipals: "सर्विस प्रिंसिपल",
+    principalUngoverned: "अनियंत्रित",
+    principalActive: "सक्रिय",
+    principalSuspended: "निलंबित",
+    principalRetired: "सेवानिवृत्त",
+    principalUngovernedHint: "कोई स्वामी या कार्रवाई अनुमति सेट नहीं है।",
+    principalOwner: "स्वामी",
+    principalRisk: "जोखिम",
+    riskLow: "कम",
+    riskMedium: "मध्यम",
+    riskHigh: "उच्च",
+    suspend: "निलंबित करें",
+    resume: "फिर शुरू करें",
+    couldNotUpdatePrincipal: "सर्विस प्रिंसिपल अपडेट नहीं किया जा सका।",
+    containmentIncomplete: "अपडेट हो गया, लेकिन कुछ रन या टोकन रोके नहीं जा सके। फिर से प्रयास करें।",
 };
 export const mcpSettingsMessages = {
     mcpTitle: "MCP",

package/dist/localization/core-messages/supplemental/ja-JP.js

@@ -54,6 +54,21 @@ export const mcpConnectMessages = {
     couldNotCreate: "トークンを作成できませんでした。",
     networkError: "ネットワークエラーです。もう一度お試しください。",
     urlTitle: "MCP URL",
+    servicePrincipals: "サービスプリンシパル",
+    principalUngoverned: "未管理",
+    principalActive: "有効",
+    principalSuspended: "一時停止中",
+    principalRetired: "廃止済み",
+    principalUngovernedHint: "オーナーも操作の許可も設定されていません。",
+    principalOwner: "オーナー",
+    principalRisk: "リスク",
+    riskLow: "低",
+    riskMedium: "中",
+    riskHigh: "高",
+    suspend: "一時停止",
+    resume: "再開",
+    couldNotUpdatePrincipal: "サービスプリンシパルを更新できませんでした。",
+    containmentIncomplete: "更新しましたが、停止できない実行またはトークンがあります。もう一度お試しください。",
 };
 export const mcpSettingsMessages = {
     mcpTitle: "MCP",

package/dist/localization/core-messages/supplemental/ko-KR.js

@@ -54,6 +54,21 @@ export const mcpConnectMessages = {
     couldNotCreate: "토큰을 생성할 수 없습니다.",
     networkError: "네트워크 오류입니다. 다시 시도하세요.",
     urlTitle: "MCP URL",
+    servicePrincipals: "서비스 주체",
+    principalUngoverned: "미관리",
+    principalActive: "활성",
+    principalSuspended: "일시 중지됨",
+    principalRetired: "폐기됨",
+    principalUngovernedHint: "소유자 또는 작업 권한이 설정되지 않았습니다.",
+    principalOwner: "소유자",
+    principalRisk: "위험",
+    riskLow: "낮음",
+    riskMedium: "보통",
+    riskHigh: "높음",
+    suspend: "일시 중지",
+    resume: "재개",
+    couldNotUpdatePrincipal: "서비스 주체를 업데이트할 수 없습니다.",
+    containmentIncomplete: "업데이트했지만 일부 실행 또는 토큰을 중지하지 못했습니다. 다시 시도하세요.",
 };
 export const mcpSettingsMessages = {
     mcpTitle: "MCP",

package/dist/localization/core-messages/supplemental/pt-BR.js

@@ -54,6 +54,21 @@ export const mcpConnectMessages = {
     couldNotCreate: "Não foi possível criar o token.",
     networkError: "Erro de rede. Tente novamente.",
     urlTitle: "Sua URL MCP",
+    servicePrincipals: "Principais de serviço",
+    principalUngoverned: "Sem governança",
+    principalActive: "Ativo",
+    principalSuspended: "Suspenso",
+    principalRetired: "Desativado",
+    principalUngovernedHint: "Nenhum proprietário ou permissão de ações definido.",
+    principalOwner: "Proprietário",
+    principalRisk: "Risco",
+    riskLow: "baixo",
+    riskMedium: "médio",
+    riskHigh: "alto",
+    suspend: "Suspender",
+    resume: "Retomar",
+    couldNotUpdatePrincipal: "Não foi possível atualizar o principal de serviço.",
+    containmentIncomplete: "Atualizado, mas algumas execuções ou tokens não puderam ser interrompidos. Tente novamente.",
 };
 export const mcpSettingsMessages = {
     mcpTitle: "MCP",

package/dist/localization/core-messages/supplemental/zh-CN.js

@@ -54,6 +54,21 @@ export const mcpConnectMessages = {
     couldNotCreate: "无法创建令牌。",
     networkError: "网络错误。请重试。",
     urlTitle: "你的 MCP URL",
+    servicePrincipals: "服务主体",
+    principalUngoverned: "未治理",
+    principalActive: "活动",
+    principalSuspended: "已暂停",
+    principalRetired: "已停用",
+    principalUngovernedHint: "未设置所有者或操作授权。",
+    principalOwner: "所有者",
+    principalRisk: "风险",
+    riskLow: "低",
+    riskMedium: "中",
+    riskHigh: "高",
+    suspend: "暂停",
+    resume: "恢复",
+    couldNotUpdatePrincipal: "无法更新服务主体。",
+    containmentIncomplete: "已更新，但部分运行或令牌无法停止。请重试。",
 };
 export const mcpSettingsMessages = {
     mcpTitle: "MCP",

package/dist/localization/core-messages/supplemental/zh-TW.js

@@ -54,6 +54,21 @@ export const mcpConnectMessages = {
     couldNotCreate: "無法建立權杖。",
     networkError: "網路錯誤。請再試一次。",
     urlTitle: "你的 MCP URL",
+    servicePrincipals: "服務主體",
+    principalUngoverned: "未治理",
+    principalActive: "啟用中",
+    principalSuspended: "已暫停",
+    principalRetired: "已停用",
+    principalUngovernedHint: "尚未設定擁有者或動作授權。",
+    principalOwner: "擁有者",
+    principalRisk: "風險",
+    riskLow: "低",
+    riskMedium: "中",
+    riskHigh: "高",
+    suspend: "暫停",
+    resume: "恢復",
+    couldNotUpdatePrincipal: "無法更新服務主體。",
+    containmentIncomplete: "已更新，但部分執行或權杖無法停止。請重試。",
 };
 export const mcpSettingsMessages = {
     mcpTitle: "MCP",

package/dist/localization/mcp-settings-messages.d.ts

@@ -41,6 +41,21 @@ export interface McpConnectMessages {
     couldNotCreate: string;
     networkError: string;
     urlTitle: string;
+    servicePrincipals: string;
+    principalUngoverned: string;
+    principalActive: string;
+    principalSuspended: string;
+    principalRetired: string;
+    principalUngovernedHint: string;
+    principalOwner: string;
+    principalRisk: string;
+    riskLow: string;
+    riskMedium: string;
+    riskHigh: string;
+    suspend: string;
+    resume: string;
+    couldNotUpdatePrincipal: string;
+    containmentIncomplete: string;
 }
 export declare const MCP_CONNECT_MESSAGES: Record<BuiltinLocaleCode, McpConnectMessages>;
 export interface McpSettingsMessages {

package/dist/mcp/actions/create-org-service-token.d.ts

@@ -1,6 +1,11 @@
 declare const _default: import("../../action.js").ActionDefinition<{
     name: string;
     ttlDays?: number;
+    ownerEmail?: string;
+    team?: string;
+    riskTier?: "high" | "low" | "medium";
+    purpose?: string;
+    allowedActions?: string[];
 }, {
     token: string;
     id: string;
@@ -8,6 +13,9 @@ declare const _default: import("../../action.js").ActionDefinition<{
     serviceEmail: string;
     orgId: string;
     ttlDays: number;
+    ownerEmail: string;
+    riskTier: "high" | "low" | "medium";
+    allowedActions: string[];
     note: string;
 }>;
 export default _default;

package/dist/mcp/actions/create-org-service-token.js

@@ -14,17 +14,27 @@
  *     never a prompt-injection target.
  *   - Revocable via `revoke-org-service-token` — same `revoked_at` gate the
  *     personal-token revocation path uses.
+ *
+ * GOVERNANCE: every mint leaves the principal governed. A name with no policy
+ * row gets one (owner defaults to the creating admin, riskTier medium,
+ * allowedActions null = unrestricted); an existing policy only changes the
+ * fields passed explicitly. A suspended or retired name is refused, since a
+ * token minted for it could never authenticate.
  */
 import { z } from "zod";
 import { defineAction } from "../../action.js";
+import { orgAdminAudit } from "../../audit/org-admin.js";
+import { getServicePrincipalPolicy, upsertServicePrincipalPolicy, } from "../../org/service-principal-policy.js";
 import { getAppProductionUrl } from "../../server/app-url.js";
 import { CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE } from "../../server/credential-membership-unavailable.js";
 import { getRequestContext } from "../../server/request-context.js";
 import { mintOrgServiceToken } from "../connect-route.js";
+import { MAX_SERVICE_TOKEN_TTL_DAYS, revokeOrgServiceToken, } from "../connect-store.js";
 import { McpCredentialIssuanceError } from "../credential-issuance.js";
+import { allowedActionsSchema, assertOwnerIsOrgMember, normalizeAllowedActions, ownerEmailSchema, parseServiceName, purposeSchema, riskTierSchema, teamSchema, } from "./service-principal-input.js";
 import { requireServiceTokenCaller, SERVICE_TOKEN_MANAGE_FORBIDDEN_MESSAGE, ServiceTokenError, } from "./service-token-access.js";
 export default defineAction({
-    description: "Create a named, org-scoped service token (for CI like PR Visual Recap's PLAN_RECAP_TOKEN). The token acts as a service principal owned by the organization, not a person. Org owner/admin only. The token value is returned ONCE and never stored — copy it immediately.",
+    description: "Create a named, org-scoped service token (for CI like PR Visual Recap's PLAN_RECAP_TOKEN). The token acts as a service principal owned by the organization, not a person. Org owner/admin only. The token value is returned ONCE and never stored — copy it immediately. The principal is created governed: owner defaults to you, risk tier to medium, allowedActions to null (unrestricted); pass ownerEmail/team/riskTier/purpose/allowedActions to set them at birth. Refused when the name is suspended or retired.",
     schema: z.object({
         name: z
             .string()
@@ -35,17 +45,57 @@ export default defineAction({
             .number()
             .int()
             .min(1)
-            .max(365)
+            .max(MAX_SERVICE_TOKEN_TTL_DAYS)
             .optional()
-            .describe("Token lifetime in days (1-365, default 365)"),
+            .describe("Token lifetime in days (1-3650, default 365)"),
+        ownerEmail: ownerEmailSchema.optional(),
+        team: teamSchema.optional(),
+        riskTier: riskTierSchema.optional(),
+        purpose: purposeSchema.optional(),
+        allowedActions: allowedActionsSchema.nullable().optional(),
     }),
+    requiresAuth: true,
     toolCallable: false,
+    audit: orgAdminAudit({
+        targetType: "service-principal",
+        targetId: (_args, result) => result?.serviceName,
+        recordInputs: false,
+        summary: () => "Created or re-minted an organization service token.",
+    }),
     run: async (args, ctx) => {
         const caller = await requireServiceTokenCaller({
             userEmail: ctx?.userEmail,
             orgId: ctx?.orgId,
             level: "manage",
         });
+        const serviceName = parseServiceName(args.name);
+        let existing;
+        try {
+            existing = await getServicePrincipalPolicy(caller.orgId, serviceName);
+        }
+        catch (error) {
+            console.error("[service-principal] Policy lookup failed:", error);
+            throw new ServiceTokenError("Could not read service principal governance. Try again.", 503);
+        }
+        if (existing && existing.lifecycle !== "active") {
+            throw new ServiceTokenError(`Service principal "${serviceName}" is ${existing.lifecycle}. Resume it with set-service-principal-lifecycle before minting a token.`, 409);
+        }
+        const policyInput = {};
+        if (args.ownerEmail !== undefined) {
+            policyInput.ownerEmail = await assertOwnerIsOrgMember(caller.orgId, args.ownerEmail);
+        }
+        else if (!existing?.ownerEmail) {
+            policyInput.ownerEmail = caller.email.toLowerCase();
+        }
+        if (args.team !== undefined)
+            policyInput.team = args.team;
+        if (args.riskTier !== undefined)
+            policyInput.riskTier = args.riskTier;
+        if (args.purpose !== undefined)
+            policyInput.purpose = args.purpose;
+        if (args.allowedActions !== undefined) {
+            policyInput.allowedActions = normalizeAllowedActions(args.allowedActions);
+        }
         const appUrl = (getRequestContext()?.requestOrigin || getAppProductionUrl()).replace(/\/+$/, "");
         if (!appUrl && !process.env.A2A_SECRET?.trim()) {
             throw new ServiceTokenError("Could not determine the app URL needed to mint a token. Set APP_URL on the deployment.", 500);
@@ -53,7 +103,7 @@ export default defineAction({
         let minted;
         try {
             minted = await mintOrgServiceToken({
-                serviceName: args.name,
+                serviceName,
                 orgId: caller.orgId,
                 createdBy: caller.email,
                 ttlDays: args.ttlDays,
@@ -67,6 +117,42 @@ export default defineAction({
                 ? new ServiceTokenError(SERVICE_TOKEN_MANAGE_FORBIDDEN_MESSAGE, 403)
                 : new ServiceTokenError(CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE, 503);
         }
+        // Governance is written after the mint so a rejected mint leaves no orphan
+        // policy; a failed write revokes the token rather than leaving a live
+        // credential that nobody is accountable for.
+        let policy;
+        try {
+            policy = await upsertServicePrincipalPolicy(caller.orgId, minted.serviceName, policyInput);
+        }
+        catch (error) {
+            console.error("[service-principal] Policy write failed:", error);
+            let revoked = false;
+            try {
+                revoked = await revokeOrgServiceToken(caller.orgId, minted.id);
+            }
+            catch (revokeError) {
+                console.error("[service-principal] Revoke after failure:", revokeError);
+            }
+            throw new ServiceTokenError(revoked
+                ? "Could not record the service principal's governance, so the new token was revoked. Try again."
+                : `Could not record the service principal's governance AND could not revoke token ${minted.id}. Revoke it with revoke-org-service-token.`, 503);
+        }
+        // Retirement can finish revoking existing tokens after the initial
+        // lifecycle check but before this mint is recorded. The upsert returns the
+        // persisted lifecycle; contain this token before ever returning its secret.
+        if (policy.lifecycle !== "active") {
+            let revoked = false;
+            try {
+                revoked = await revokeOrgServiceToken(caller.orgId, minted.id);
+            }
+            catch (error) {
+                console.error("[service-principal] Revoke after lifecycle change:", error);
+            }
+            if (!revoked) {
+                throw new ServiceTokenError(`Service principal "${serviceName}" became ${policy.lifecycle} while minting, and token ${minted.id} could not be revoked. Revoke it with revoke-org-service-token.`, 503);
+            }
+            throw new ServiceTokenError(`Service principal "${serviceName}" became ${policy.lifecycle} while minting. The new token was revoked; resume it before minting again.`, 409);
+        }
         return {
             // The ONLY place the secret ever appears. Never stored, never logged.
             token: minted.token,
@@ -75,6 +161,9 @@ export default defineAction({
             serviceEmail: minted.serviceEmail,
             orgId: caller.orgId,
             ttlDays: minted.ttlDays,
+            ownerEmail: policy.ownerEmail,
+            riskTier: policy.riskTier,
+            allowedActions: policy.allowedActions,
             note: "Store this token now (e.g. as the PLAN_RECAP_TOKEN GitHub Actions secret). It will not be shown again. Revoke it any time with revoke-org-service-token.",
         };
     },

package/dist/mcp/actions/list-org-service-tokens.d.ts

@@ -2,6 +2,7 @@ declare const _default: import("../../action.js").ActionDefinition<{
     includeRevoked?: boolean;
 }, {
     orgId: string;
+    canManage: boolean;
     tokens: {
         id: string;
         serviceName: string;
@@ -12,5 +13,6 @@ declare const _default: import("../../action.js").ActionDefinition<{
         lastUsedAt: number;
         revokedAt: number;
     }[];
+    principals: import("./service-principal-input.js").ServicePrincipalView[];
 }>;
 export default _default;

package/dist/mcp/actions/list-org-service-tokens.js

@@ -1,15 +1,18 @@
 /**
- * List the active org service tokens — metadata only (name, who minted it,
- * created/last-used/revoked timestamps). Token values are never stored, so
- * they can never appear here. Any org member may list; minting and revoking
- * are owner/admin-gated.
+ * List the org service tokens — metadata only (name, who minted it,
+ * created/last-used/revoked timestamps) — and the governed principals they
+ * belong to (state, owner, risk tier, grant). Token values are never stored, so
+ * they can never appear here. Any org member may list; minting, revoking and
+ * governance changes are owner/admin-gated.
  */
 import { z } from "zod";
 import { defineAction } from "../../action.js";
+import { listServicePrincipalPolicies } from "../../org/service-principal-policy.js";
 import { listOrgServiceTokens } from "../connect-store.js";
-import { requireServiceTokenCaller } from "./service-token-access.js";
+import { describeServicePrincipal } from "./service-principal-input.js";
+import { requireServiceTokenCaller, ServiceTokenError, } from "./service-token-access.js";
 export default defineAction({
-    description: "List your organization's service tokens (CI credentials such as PLAN_RECAP_TOKEN): name, who created them, created/last-used times, and revocation state. Token values are never stored and never shown. Any org member can list.",
+    description: "List your organization's service tokens (CI credentials such as PLAN_RECAP_TOKEN): name, who created them, created/last-used times, and revocation state. Also returns `principals`: one row per service name (from tokens and governance records) with state (ungoverned = no owner/grant set, active, suspended, retired), owner, team, risk tier, purpose, allowedActions (null = unrestricted) and lifecycle history. Token values are never stored and never shown. Any org member can list.",
     schema: z.object({
         includeRevoked: z
             .boolean()
@@ -23,7 +26,19 @@ export default defineAction({
             orgId: ctx?.orgId,
             level: "read",
         });
-        const rows = await listOrgServiceTokens(caller.orgId);
+        let rows;
+        let policies;
+        try {
+            [rows, policies] = await Promise.all([
+                listOrgServiceTokens(caller.orgId),
+                listServicePrincipalPolicies(caller.orgId),
+            ]);
+        }
+        catch (error) {
+            // An unreadable policy table must not render every principal "ungoverned".
+            console.error("[service-principal] Listing failed:", error);
+            throw new ServiceTokenError("Could not read service principal governance. Try again.", 503);
+        }
         const tokens = rows
             .filter((row) => args.includeRevoked || row.revokedAt == null)
             .map((row) => ({
@@ -36,6 +51,19 @@ export default defineAction({
             lastUsedAt: row.lastUsedAt,
             revokedAt: row.revokedAt,
         }));
-        return { orgId: caller.orgId, tokens };
+        const policyByName = new Map(policies.map((p) => [p.serviceName, p]));
+        const names = new Set(policyByName.keys());
+        for (const row of rows)
+            if (row.serviceName)
+                names.add(row.serviceName);
+        const principals = [...names]
+            .sort()
+            .map((name) => describeServicePrincipal(caller.orgId, name, policyByName.get(name)));
+        return {
+            orgId: caller.orgId,
+            canManage: caller.role !== "member",
+            tokens,
+            principals,
+        };
     },
 });

package/dist/mcp/actions/service-principal-input.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Governance input shared by `create-org-service-token` and
+ * `set-service-principal-policy`, so a principal is validated the same way
+ * whether it is born governed or tightened later.
+ */
+import { z } from "zod";
+import { type ServicePrincipalLifecycle, type ServicePrincipalPolicy, type ServicePrincipalRiskTier } from "../../org/service-principal-policy.js";
+export declare const MAX_ALLOWED_ACTIONS = 200;
+export declare const riskTierSchema: z.ZodEnum<{
+    high: "high";
+    low: "low";
+    medium: "medium";
+}>;
+export declare const allowedActionsSchema: z.ZodArray<z.ZodString>;
+export declare const ownerEmailSchema: z.ZodString;
+export declare const teamSchema: z.ZodString;
+export declare const purposeSchema: z.ZodString;
+/** Dedupe so the stored grant (and its audited count) has no repeats. */
+export declare function normalizeAllowedActions(allowed: string[] | null | undefined): string[] | null | undefined;
+/**
+ * The owner must be a person in this org. A service identity is refused by
+ * name so the answer is a clear 400 rather than a membership miss, and an
+ * unreadable membership store is a 503, never "not a member".
+ */
+export declare function assertOwnerIsOrgMember(orgId: string, ownerEmail: string): Promise<string>;
+export interface ServicePrincipalView {
+    serviceName: string;
+    serviceEmail: string;
+    state: "ungoverned" | ServicePrincipalLifecycle;
+    ownerEmail: string | null;
+    team: string | null;
+    riskTier: ServicePrincipalRiskTier | null;
+    purpose: string | null;
+    /** `null` is unrestricted. */
+    allowedActions: string[] | null;
+    lifecycleReason: string | null;
+    lifecycleChangedBy: string | null;
+    lifecycleChangedAt: number | null;
+}
+/** No policy row is "ungoverned": a legacy principal that is active and unrestricted. */
+export declare function describeServicePrincipal(orgId: string, serviceName: string, policy: ServicePrincipalPolicy | null | undefined): ServicePrincipalView;
+/**
+ * A name with neither a token nor a policy is a typo, not a principal; refusing
+ * it keeps governance rows from accumulating for names that can never act.
+ */
+export declare function requireKnownServicePrincipal(orgId: string, serviceName: string): Promise<ServicePrincipalPolicy | null>;
+/** Normalize a user-supplied name; a name with no usable characters is a 400. */
+export declare function parseServiceName(raw: string): string;

package/dist/mcp/actions/service-principal-input.js

@@ -0,0 +1,102 @@
+/**
+ * Governance input shared by `create-org-service-token` and
+ * `set-service-principal-policy`, so a principal is validated the same way
+ * whether it is born governed or tightened later.
+ */
+import { z } from "zod";
+import { isOrgMember } from "../../org/membership.js";
+import { parseServiceIdentityEmail } from "../../org/service-identity.js";
+import { getServicePrincipalPolicy, isServicePrincipalActionPattern, MAX_SERVICE_PRINCIPAL_ACTIONS, SERVICE_PRINCIPAL_RISK_TIERS, } from "../../org/service-principal-policy.js";
+import { CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE } from "../../server/credential-membership-unavailable.js";
+import { listOrgServiceTokens, normalizeServiceName, serviceIdentityEmail, } from "../connect-store.js";
+import { ServiceTokenError } from "./service-token-access.js";
+export const MAX_ALLOWED_ACTIONS = MAX_SERVICE_PRINCIPAL_ACTIONS;
+export const riskTierSchema = z
+    .enum(SERVICE_PRINCIPAL_RISK_TIERS)
+    .describe("Risk tier: low, medium (default) or high");
+export const allowedActionsSchema = z
+    .array(z.string().refine(isServicePrincipalActionPattern))
+    .max(MAX_ALLOWED_ACTIONS)
+    .describe("Action names the principal may call; a trailing * matches a prefix (e.g. 'list-*'). An empty list grants nothing. Use null for unrestricted.");
+export const ownerEmailSchema = z
+    .string()
+    .trim()
+    .email()
+    .max(320)
+    .describe("Accountable org member (email)");
+export const teamSchema = z.string().trim().min(1).max(120);
+export const purposeSchema = z.string().trim().min(1).max(500);
+/** Dedupe so the stored grant (and its audited count) has no repeats. */
+export function normalizeAllowedActions(allowed) {
+    return allowed ? [...new Set(allowed)] : allowed;
+}
+/**
+ * The owner must be a person in this org. A service identity is refused by
+ * name so the answer is a clear 400 rather than a membership miss, and an
+ * unreadable membership store is a 503, never "not a member".
+ */
+export async function assertOwnerIsOrgMember(orgId, ownerEmail) {
+    const email = ownerEmail.trim().toLowerCase();
+    if (parseServiceIdentityEmail(email)) {
+        throw new ServiceTokenError("A service principal cannot own another service principal. Choose an org member.", 400);
+    }
+    let member;
+    try {
+        member = await isOrgMember(orgId, email);
+    }
+    catch (error) {
+        console.error("[service-principal] Owner membership lookup failed:", error);
+        throw new ServiceTokenError(CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE, 503);
+    }
+    if (!member) {
+        throw new ServiceTokenError(`${email} is not a member of this organization.`, 400);
+    }
+    return email;
+}
+/** No policy row is "ungoverned": a legacy principal that is active and unrestricted. */
+export function describeServicePrincipal(orgId, serviceName, policy) {
+    return {
+        serviceName,
+        serviceEmail: serviceIdentityEmail(serviceName, orgId),
+        state: policy?.lifecycle ?? "ungoverned",
+        ownerEmail: policy?.ownerEmail ?? null,
+        team: policy?.team ?? null,
+        riskTier: policy?.riskTier ?? null,
+        purpose: policy?.purpose ?? null,
+        allowedActions: policy ? policy.allowedActions : null,
+        lifecycleReason: policy?.lifecycleReason ?? null,
+        lifecycleChangedBy: policy?.lifecycleChangedBy ?? null,
+        lifecycleChangedAt: policy?.lifecycleChangedAt ?? null,
+    };
+}
+/**
+ * A name with neither a token nor a policy is a typo, not a principal; refusing
+ * it keeps governance rows from accumulating for names that can never act.
+ */
+export async function requireKnownServicePrincipal(orgId, serviceName) {
+    let policy;
+    let tokens;
+    try {
+        [policy, tokens] = await Promise.all([
+            getServicePrincipalPolicy(orgId, serviceName),
+            listOrgServiceTokens(orgId),
+        ]);
+    }
+    catch (error) {
+        console.error("[service-principal] Principal lookup failed:", error);
+        throw new ServiceTokenError("Could not read service principal governance. Try again.", 503);
+    }
+    if (!policy && !tokens.some((t) => t.serviceName === serviceName)) {
+        throw new ServiceTokenError(`No service principal named "${serviceName}" in this organization.`, 404);
+    }
+    return policy;
+}
+/** Normalize a user-supplied name; a name with no usable characters is a 400. */
+export function parseServiceName(raw) {
+    try {
+        return normalizeServiceName(raw);
+    }
+    catch (error) {
+        throw new ServiceTokenError(error instanceof Error ? error.message : "Invalid service name.", 400);
+    }
+}

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

@@ -0,0 +1,15 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    serviceName: string;
+    lifecycle: "active" | "retired" | "suspended";
+    reason?: string;
+}, {
+    orgId: string;
+    serviceEmail: string;
+    lifecycle: "active" | "retired" | "suspended";
+    principal: import("./service-principal-input.js").ServicePrincipalView;
+    abortedRuns: number;
+    revokedTokens: number;
+    contained: boolean;
+    containmentErrors: string[];
+}>;
+export default _default;