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

package/dist/mcp/connect-store.d.ts

@@ -23,6 +23,7 @@ export declare const DEVICE_CODE_TTL_MS: number;
 export declare const DEFAULT_TOKEN_TTL_DAYS = 365;
 export declare const MIN_TOKEN_TTL_DAYS = 1;
 export declare const MAX_TOKEN_TTL_DAYS = 365;
+export declare const MAX_SERVICE_TOKEN_TTL_DAYS = 3650;
 export declare const DEVICE_START_MAX = 20;
 export declare const DEVICE_START_WINDOW_MS = 60000;
 export declare function ensureTable(): Promise<void>;
@@ -86,6 +87,12 @@ export declare function listOrgServiceTokens(orgId: string): Promise<MintedToken
  * tokens. Idempotent; returns true when a row actually transitioned.
  */
 export declare function revokeOrgServiceToken(orgId: string, id: string): Promise<boolean>;
+/**
+ * Revoke every active token of one service in a single statement. Unlike
+ * `listOrgServiceTokens`, a connection error is NOT swallowed: retiring a
+ * principal must fail loudly rather than report "0 revoked".
+ */
+export declare function revokeServiceTokensByName(orgId: string, serviceName: string): Promise<number>;
 /**
  * Revoke a token, but ONLY if it is owned by `ownerEmail` (the caller). The
  * `owner_email = ?` predicate is the access scope — a caller can never revoke

package/dist/mcp/connect-store.js

@@ -26,6 +26,7 @@ export const DEVICE_CODE_TTL_MS = 10 * 60_000;
 export const DEFAULT_TOKEN_TTL_DAYS = 365;
 export const MIN_TOKEN_TTL_DAYS = 1;
 export const MAX_TOKEN_TTL_DAYS = 365;
+export const MAX_SERVICE_TOKEN_TTL_DAYS = 3_650;
 export const DEVICE_START_MAX = 20;
 export const DEVICE_START_WINDOW_MS = 60_000;
 export async function ensureTable() {
@@ -211,20 +212,13 @@ export async function listTokens(ownerEmail) {
     }
 }
 export async function listOrgServiceTokens(orgId) {
-    try {
-        await ensureTable();
-        const client = getDbExec();
-        const { rows } = await client.execute({
-            sql: `SELECT id, jti, owner_email, org_id, label, kind, service_name, created_by, created_at, last_used_at, revoked_at FROM mcp_connect_tokens WHERE org_id = ? AND kind = 'service' ORDER BY created_at DESC`,
-            args: [orgId],
-        });
-        return rows.map(mapTokenRow);
-    }
-    catch (err) {
-        if (isConnectionError(err))
-            return [];
-        throw err;
-    }
+    await ensureTable();
+    const client = getDbExec();
+    const { rows } = await client.execute({
+        sql: `SELECT id, jti, owner_email, org_id, label, kind, service_name, created_by, created_at, last_used_at, revoked_at FROM mcp_connect_tokens WHERE org_id = ? AND kind = 'service' ORDER BY created_at DESC`,
+        args: [orgId],
+    });
+    return rows.map(mapTokenRow);
 }
 /**
  * Revoke an org service token by id, scoped to `orgId` AND `kind = 'service'`
@@ -242,6 +236,19 @@ export async function revokeOrgServiceToken(orgId, id) {
     });
     return result.rowsAffected > 0;
 }
+/**
+ * Revoke every active token of one service in a single statement. Unlike
+ * `listOrgServiceTokens`, a connection error is NOT swallowed: retiring a
+ * principal must fail loudly rather than report "0 revoked".
+ */
+export async function revokeServiceTokensByName(orgId, serviceName) {
+    await ensureTable();
+    const result = await getDbExec().execute({
+        sql: `UPDATE mcp_connect_tokens SET revoked_at = ? WHERE org_id = ? AND kind = 'service' AND service_name = ? AND revoked_at IS NULL`,
+        args: [Date.now(), orgId, serviceName],
+    });
+    return result.rowsAffected;
+}
 /**
  * Revoke a token, but ONLY if it is owned by `ownerEmail` (the caller). The
  * `owner_email = ?` predicate is the access scope — a caller can never revoke

package/dist/mcp-client/oauth-routes.js

@@ -5,6 +5,7 @@ import { CredentialStoreUnavailableError, resolveSecretPairs, } from "../server/
 import { getH3App } from "../server/framework-request-handler.js";
 import { canonicalFrameworkPathname } from "../server/framework-route-prefix.js";
 import { getAppBasePath, getAppUrl, encodeOAuthState, oauthErrorPage, resolveOAuthRedirectUri, } from "../server/google-oauth.js";
+import { queryEchoSafeRedirect } from "../server/query-echo-safe-redirect.js";
 import { runWithRequestContext } from "../server/request-context.js";
 import { isWorkspaceOAuthCallbackRelayEnabled } from "../server/workspace-oauth.js";
 import { MCP_OAUTH_FLOW_TTL_SECONDS } from "../shared/mcp-oauth-flow-ttl.js";
@@ -491,7 +492,7 @@ async function handleMcpOAuthCallback(event, options) {
         console.warn("[mcp-client/oauth] saved server did not reconnect:", error);
     }
     const returnPath = resolveMcpOAuthReturnPath(connected, flow);
-    return redirectWithStagedCookies(event, getAppUrl(event, stripMcpOAuthAppBasePath(returnPath, getAppBasePath())));
+    return queryEchoSafeRedirect(event, redirectWithStagedCookies(event, getAppUrl(event, stripMcpOAuthAppBasePath(returnPath, getAppBasePath()))));
 }
 export function setMcpOAuthFlowCookie(event, flow, secure) {
     const encrypted = encryptSecretValue(JSON.stringify(flow));

package/dist/notifications/routes.d.ts

@@ -1,12 +1,12 @@
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
-    error?: undefined;
     count: number;
     updated?: undefined;
+    error?: undefined;
     ok?: undefined;
 } | {
-    error?: undefined;
     count?: undefined;
     updated: number;
+    error?: undefined;
     ok?: undefined;
 } | {
     count?: undefined;
@@ -14,8 +14,8 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     count?: undefined;
     updated?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/observability/routes.d.ts

@@ -27,38 +27,38 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    id?: undefined;
     error: string;
     message: string;
     summary?: undefined;
     spans?: undefined;
+    id?: undefined;
     ok?: undefined;
 } | {
-    id?: undefined;
-    error?: undefined;
     message?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
+    id?: undefined;
+    error?: undefined;
     ok?: undefined;
 } | {
-    error?: undefined;
     message?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
+    error?: undefined;
     ok?: undefined;
 } | {
-    id?: undefined;
     message?: undefined;
     summary?: undefined;
     spans?: undefined;
+    id?: undefined;
     error: any;
     ok?: undefined;
 } | {
-    id?: undefined;
-    error?: undefined;
     message?: undefined;
     summary?: undefined;
     spans?: undefined;
+    id?: undefined;
+    error?: undefined;
     ok: boolean;
 }>>;

package/dist/org/index.d.ts

@@ -177,10 +177,10 @@ export declare const getMyOrgHandler: import("h3").EventHandlerWithFetch<import(
     soloDeploymentAdmin: boolean | undefined;
 }>>;
 export declare const createOrgHandler: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    name?: undefined;
-    success: boolean;
     role?: undefined;
     id?: undefined;
+    name?: undefined;
+    success: boolean;
 } | {
     success?: undefined;
     id: string;

package/dist/org/service-principal-guard.d.ts

@@ -0,0 +1,64 @@
+import type { DbExec } from "../db/client.js";
+/**
+ * Enforcement helpers over the service-principal policy store. MCP admission,
+ * MCP tool dispatch, and inbound A2A all ask these instead of reading
+ * `evaluateServicePrincipal` themselves, so a refusal means the same thing
+ * (status, message, audit row) on every entry point.
+ */
+export declare const SERVICE_PRINCIPAL_UNAVAILABLE_MESSAGE = "The service principal's status could not be verified. Retry shortly.";
+export type ServicePrincipalRefusalCode = "service_principal_inactive" | "service_principal_unavailable" | "service_principal_action_denied" | "service_principal_handoff_unsupported";
+/** 403 is a refusal (audited as `denied`); 503 is retryable and never a denial. */
+export declare class ServicePrincipalRefusedError extends Error {
+    readonly errorCode: ServicePrincipalRefusalCode;
+    readonly statusCode: 403 | 503;
+    constructor(code: ServicePrincipalRefusalCode, message: string);
+}
+export declare function servicePrincipalActionDeniedError(actionName: string): ServicePrincipalRefusedError;
+/**
+ * Throws `ServicePrincipalRefusedError` when `email` is a service identity that
+ * is suspended or retired, or whose policy could not be read. Otherwise returns
+ * its action grant: `null` is unrestricted (not a service identity, or a legacy
+ * principal with no policy row), a list is the only set of actions it may call.
+ * Non-service callers return without touching the database.
+ */
+export declare function assertServicePrincipalMayRun(email: string | null | undefined, orgId?: string | null, db?: Pick<DbExec, "execute">): Promise<{
+    allowedActions: string[] | null;
+}>;
+/**
+ * Serialize a persisted run start with lifecycle changes, then recheck the
+ * verified principal state before the run row is inserted.
+ */
+export declare function lockAndAssertServicePrincipalMayStartRun(db: DbExec, input: {
+    email: string;
+    orgId?: string | null;
+}): Promise<ServicePrincipalRefusedError | undefined>;
+export declare function prepareServicePrincipalRunStart(input: {
+    email: string;
+    orgId?: string | null;
+}): Promise<void>;
+/** Throws a 403 refusal unless the grant covers `actionName`. */
+export declare function assertServicePrincipalMayCall(allowedActions: string[] | null, actionName: string): void;
+/**
+ * Writes a `denied` audit row when a refused service-principal call has a
+ * verified org scope. Visible to org admins only; the recorder is best-effort.
+ */
+export declare function recordServicePrincipalDenial(input: {
+    email: string | null | undefined;
+    orgId?: string | null;
+    actionName: string;
+    caller: string;
+    error: ServicePrincipalRefusedError;
+}): Promise<void>;
+/**
+ * The action-execution check: refuse a service identity's call to `actionName`
+ * when it is suspended, unverifiable, or outside its grant, and record one
+ * `denied` row for a 403. Evaluated on every call, never cached, so a suspend
+ * or re-scope takes effect on the next action of a run already in flight.
+ * Non-service callers return without touching the database.
+ */
+export declare function enforceServicePrincipalActionGrant(input: {
+    email: string | null | undefined;
+    orgId?: string | null;
+    actionName: string;
+    caller: string;
+}): Promise<void>;

package/dist/org/service-principal-guard.js

@@ -0,0 +1,140 @@
+import { parseServiceIdentityEmail } from "./service-identity.js";
+import { ensureTable, evaluateServicePrincipal, isActionGranted, lockServicePrincipalLifecycle, SERVICE_PRINCIPAL_SUSPENDED_MESSAGE, } from "./service-principal-policy.js";
+/**
+ * Enforcement helpers over the service-principal policy store. MCP admission,
+ * MCP tool dispatch, and inbound A2A all ask these instead of reading
+ * `evaluateServicePrincipal` themselves, so a refusal means the same thing
+ * (status, message, audit row) on every entry point.
+ */
+export const SERVICE_PRINCIPAL_UNAVAILABLE_MESSAGE = "The service principal's status could not be verified. Retry shortly.";
+/** 403 is a refusal (audited as `denied`); 503 is retryable and never a denial. */
+export class ServicePrincipalRefusedError extends Error {
+    errorCode;
+    statusCode;
+    constructor(code, message) {
+        super(message);
+        this.name = "ServicePrincipalRefusedError";
+        this.errorCode = code;
+        this.statusCode = code === "service_principal_unavailable" ? 503 : 403;
+    }
+}
+export function servicePrincipalActionDeniedError(actionName) {
+    return new ServicePrincipalRefusedError("service_principal_action_denied", `Forbidden: ${actionName} is not permitted for this service principal.`);
+}
+/**
+ * Throws `ServicePrincipalRefusedError` when `email` is a service identity that
+ * is suspended or retired, or whose policy could not be read. Otherwise returns
+ * its action grant: `null` is unrestricted (not a service identity, or a legacy
+ * principal with no policy row), a list is the only set of actions it may call.
+ * Non-service callers return without touching the database.
+ */
+export async function assertServicePrincipalMayRun(email, orgId, db) {
+    const state = db
+        ? await evaluateServicePrincipal(email, orgId, db)
+        : await evaluateServicePrincipal(email, orgId);
+    switch (state.status) {
+        case "not-service":
+        case "ungoverned":
+            return { allowedActions: null };
+        case "active":
+            return { allowedActions: state.policy.allowedActions };
+        case "suspended":
+        case "retired":
+        case "org-mismatch":
+            throw new ServicePrincipalRefusedError("service_principal_inactive", SERVICE_PRINCIPAL_SUSPENDED_MESSAGE);
+        case "unavailable":
+            throw new ServicePrincipalRefusedError("service_principal_unavailable", SERVICE_PRINCIPAL_UNAVAILABLE_MESSAGE);
+    }
+}
+/**
+ * Serialize a persisted run start with lifecycle changes, then recheck the
+ * verified principal state before the run row is inserted.
+ */
+export async function lockAndAssertServicePrincipalMayStartRun(db, input) {
+    const identity = parseServiceIdentityEmail(input.email);
+    if (!identity)
+        return;
+    if (input.orgId?.trim() === identity.orgId) {
+        await lockServicePrincipalLifecycle(db, identity.orgId, identity.serviceName);
+    }
+    try {
+        await assertServicePrincipalMayRun(input.email, input.orgId, db);
+        return;
+    }
+    catch (error) {
+        if (error instanceof ServicePrincipalRefusedError)
+            return error;
+        throw error;
+    }
+}
+export async function prepareServicePrincipalRunStart(input) {
+    const identity = parseServiceIdentityEmail(input.email);
+    if (identity && input.orgId?.trim() === identity.orgId) {
+        await ensureTable();
+    }
+}
+/** Throws a 403 refusal unless the grant covers `actionName`. */
+export function assertServicePrincipalMayCall(allowedActions, actionName) {
+    if (!isActionGranted(allowedActions, actionName)) {
+        throw servicePrincipalActionDeniedError(actionName);
+    }
+}
+/**
+ * Writes a `denied` audit row when a refused service-principal call has a
+ * verified org scope. Visible to org admins only; the recorder is best-effort.
+ */
+export async function recordServicePrincipalDenial(input) {
+    if (input.error.statusCode !== 403)
+        return;
+    const orgId = input.orgId?.trim();
+    if (!orgId)
+        return;
+    const identity = parseServiceIdentityEmail(input.email);
+    if (!identity || identity.orgId !== orgId)
+        return;
+    const { recordActionAudit } = await import("../audit/record.js");
+    await recordActionAudit({
+        config: {
+            enabled: true,
+            target: () => ({
+                type: "service-principal",
+                id: input.email ?? undefined,
+                orgId,
+                visibility: "admins",
+            }),
+            summary: () => input.error.errorCode === "service_principal_inactive"
+                ? `Refused ${input.actionName}: service principal is suspended or retired`
+                : input.error.errorCode === "service_principal_action_denied"
+                    ? `Refused ${input.actionName}: not in the service principal's allowed actions`
+                    : `Refused ${input.actionName}: service principal authorization cannot be preserved across the handoff`,
+        },
+        args: {},
+        ctx: {
+            actionName: input.actionName,
+            caller: input.caller,
+            userEmail: input.email ?? undefined,
+            orgId,
+        },
+        status: "error",
+        error: input.error,
+    });
+}
+/**
+ * The action-execution check: refuse a service identity's call to `actionName`
+ * when it is suspended, unverifiable, or outside its grant, and record one
+ * `denied` row for a 403. Evaluated on every call, never cached, so a suspend
+ * or re-scope takes effect on the next action of a run already in flight.
+ * Non-service callers return without touching the database.
+ */
+export async function enforceServicePrincipalActionGrant(input) {
+    try {
+        const { allowedActions } = await assertServicePrincipalMayRun(input.email, input.orgId);
+        assertServicePrincipalMayCall(allowedActions, input.actionName);
+    }
+    catch (error) {
+        if (error instanceof ServicePrincipalRefusedError) {
+            await recordServicePrincipalDenial({ ...input, error });
+        }
+        throw error;
+    }
+}

package/dist/org/service-principal-policy.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Governance record for an org service principal (`svc-<name>@service.<orgId>`).
+ *
+ * A service token proves WHO is calling; this record says who is ACCOUNTABLE
+ * for the principal, whether it may run at all, and which actions it may call.
+ * Every entry point that admits a service identity (MCP admission, MCP tool
+ * dispatch, agent run start) reads it through `evaluateServicePrincipal` so
+ * suspend and the action grant are enforced in one place.
+ *
+ * Constraints that must survive future edits:
+ *
+ * 1. No row means a legacy principal minted before governance existed: it
+ *    stays active and unrestricted ("ungoverned"). Tightening it is an explicit
+ *    admin act, never a side effect of upgrading.
+ * 2. An unreadable row is NOT an absent row. A read failure resolves to
+ *    "unavailable" and callers refuse the request (503), because answering
+ *    "ungoverned" would let a suspended principal back in during an outage.
+ * 3. A grant is deny-by-default once `allowedActions` is a list: an empty list
+ *    grants nothing, and `null` is the only unrestricted value.
+ */
+import { type DbExec } from "../db/client.js";
+export declare const SERVICE_PRINCIPAL_LIFECYCLES: readonly ["active", "suspended", "retired"];
+export type ServicePrincipalLifecycle = (typeof SERVICE_PRINCIPAL_LIFECYCLES)[number];
+export declare const SERVICE_PRINCIPAL_RISK_TIERS: readonly ["low", "medium", "high"];
+export type ServicePrincipalRiskTier = (typeof SERVICE_PRINCIPAL_RISK_TIERS)[number];
+export declare const MAX_SERVICE_PRINCIPAL_ACTIONS = 200;
+export declare function isServicePrincipalActionPattern(value: string): boolean;
+export interface ServicePrincipalPolicy {
+    orgId: string;
+    /** Normalized service name, the `<name>` in `svc-<name>@service.<orgId>`. */
+    serviceName: string;
+    /** Accountable human. Always an email, never the service identity. */
+    ownerEmail: string | null;
+    /** Operational team or on-call queue that answers for the principal. */
+    team: string | null;
+    riskTier: ServicePrincipalRiskTier;
+    /** What the principal is for, in one line. */
+    purpose: string | null;
+    lifecycle: ServicePrincipalLifecycle;
+    /** `null` is unrestricted. A list is the only set of actions it may call. */
+    allowedActions: string[] | null;
+    lifecycleReason: string | null;
+    lifecycleChangedBy: string | null;
+    lifecycleChangedAt: number | null;
+    createdAt: number | null;
+    updatedAt: number | null;
+}
+export type ServicePrincipalState = {
+    status: "not-service";
+} | {
+    status: "ungoverned";
+    orgId: string;
+    serviceName: string;
+} | {
+    status: "active";
+    policy: ServicePrincipalPolicy;
+} | {
+    status: "suspended" | "retired";
+    policy: ServicePrincipalPolicy;
+}
+/** No verified org matches the address, so this is not the principal. */
+ | {
+    status: "org-mismatch";
+} | {
+    status: "unavailable";
+};
+export declare function ensureTable(): Promise<void>;
+export declare function servicePrincipalLifecycleLockKey(orgId: string, serviceName: string): string;
+export declare function lockServicePrincipalLifecycle(db: Pick<DbExec, "execute">, orgId: string, serviceName: string): Promise<void>;
+export declare function withServicePrincipalLifecycleLock<T>(orgId: string, serviceName: string, work: (db: DbExec) => Promise<T>): Promise<T>;
+/** Throws when the store cannot be read; `null` means there is no record. */
+export declare function getServicePrincipalPolicy(orgId: string, serviceName: string, db?: Pick<DbExec, "execute">): Promise<ServicePrincipalPolicy | null>;
+export declare function listServicePrincipalPolicies(orgId: string): Promise<ServicePrincipalPolicy[]>;
+export interface ServicePrincipalPolicyInput {
+    ownerEmail?: string | null;
+    team?: string | null;
+    riskTier?: ServicePrincipalRiskTier;
+    purpose?: string | null;
+    allowedActions?: string[] | null;
+}
+/**
+ * Create or update the governance fields. Fields left `undefined` keep their
+ * stored value; `null` clears one. Lifecycle changes go through
+ * `setServicePrincipalLifecycle` so they always carry an actor and a reason.
+ */
+export declare function upsertServicePrincipalPolicy(orgId: string, serviceName: string, input: ServicePrincipalPolicyInput): Promise<ServicePrincipalPolicy>;
+export declare class ServicePrincipalRetiredError extends Error {
+    readonly statusCode = 409;
+    constructor();
+}
+export declare function setServicePrincipalLifecycle(orgId: string, serviceName: string, lifecycle: ServicePrincipalLifecycle, change: {
+    actorEmail: string;
+    reason?: string | null;
+}, db?: Pick<DbExec, "execute">): Promise<ServicePrincipalPolicy>;
+/**
+ * Resolve whether a caller may run from its identity email and verified org.
+ * Non-service identities return `not-service` without touching the database,
+ * so the hot path for human callers is unchanged.
+ */
+export declare function evaluateServicePrincipal(email: string | null | undefined, orgId?: string | null, db?: Pick<DbExec, "execute">): Promise<ServicePrincipalState>;
+/** Whether the principal may call `actionName`. `null` grants everything. */
+export declare function isActionGranted(allowedActions: string[] | null, actionName: string): boolean;
+/** Message returned to a refused caller; never echoes the stored reason. */
+export declare const SERVICE_PRINCIPAL_SUSPENDED_MESSAGE = "This service principal is suspended or retired. Ask an organization admin to resume it.";