@agent-native/core 0.107.1 → 0.108.0

package/corpus/core/src/client/feature-flags/types.ts

@@ -0,0 +1,29 @@
+export interface FeatureFlagActor {
+  name?: string | null;
+  email?: string | null;
+}
+
+export interface FeatureFlagMetadata {
+  key: string;
+  displayName?: string | null;
+  description?: string | null;
+  defaultValue: boolean;
+  rules: FeatureFlagRules;
+  enabledForCurrentUser?: boolean;
+}
+
+export interface FeatureFlagRules {
+  version?: 1;
+  mode: "off" | "on" | "rules";
+  emails: string[];
+  orgIds: string[];
+  percentage: number;
+  updatedAt?: number | null;
+  updatedBy?: FeatureFlagActor | string | null;
+}
+
+export interface SetFeatureFlagInput {
+  key: string;
+  operation: "off" | "enable-for-current-user" | "replace-rules";
+  rules?: FeatureFlagRules;
+}

package/corpus/core/src/client/feature-flags/use-feature-flag.ts

@@ -0,0 +1,26 @@
+import { useActionQuery } from "../use-action.js";
+import {
+  evaluatedFeatureFlagValues,
+  featureFlagValue,
+  type EvaluatedFeatureFlags,
+} from "./helpers.js";
+
+export type { EvaluatedFeatureFlags } from "./helpers.js";
+
+/**
+ * Returns the current user's evaluated value for a registered feature flag.
+ * Flags that have not been registered evaluate to false.
+ */
+export function useFeatureFlag(key: string): boolean {
+  const query = useActionQuery<EvaluatedFeatureFlags>(
+    "get-feature-flags" as never,
+  );
+  return featureFlagValue(evaluatedFeatureFlagValues(query.data), key);
+}
+
+export function useFeatureFlags(): Record<string, boolean> {
+  const query = useActionQuery<EvaluatedFeatureFlags>(
+    "get-feature-flags" as never,
+  );
+  return evaluatedFeatureFlagValues(query.data);
+}

package/corpus/core/src/client/index.ts

@@ -698,6 +698,17 @@ export {
   type DataWidgetResultMetadata,
 } from "./chat/widgets/data-widget-types.js";
 export { AgentNativeIcon } from "./components/icons/AgentNativeIcon.js";
+export {
+  FeatureFlagsEditor,
+  evaluatedFeatureFlagValues,
+  featureFlagValue,
+  useFeatureFlag,
+  useFeatureFlags,
+  type FeatureFlagActor,
+  type FeatureFlagMetadata,
+  type FeatureFlagRules,
+  type SetFeatureFlagInput,
+} from "./feature-flags/index.js";
 export {
   SettingsPanel,
   SettingsTabsPage,

package/corpus/core/src/extensions/routes.ts

@@ -982,7 +982,7 @@ export const DESTRUCTIVE_SQL_RE =
 // integrations, notifications, scheduling, sharing/orgs), and Postgres
 // catalogs that would let a extension enumerate or read internals.
 export const SENSITIVE_SQL_RE =
-  /\b(app_secrets|user|users|session|sessions|account|accounts|verification|oauth_tokens|tools|extensions|tool_shares|tool_slots|tool_slot_installs|tool_hidden_extensions|tool_history|member|organization|invitation|jwks|agent_trace_spans|agent_trace_summaries|agent_feedback|agent_satisfaction_scores|agent_evals|agent_runs|agent_run_events|notifications|progress_runs|integration_configs|integration_pending_tasks|integration_thread_mappings|resources|org_members|org_invitations|bigquery_cache|dashboard_views|pg_catalog|information_schema|pg_class|pg_proc|pg_namespace|pg_user|pg_roles|pg_authid|pg_shadow)\b/i;
+  /\b(app_secrets|settings|user|users|session|sessions|account|accounts|verification|oauth_tokens|tools|extensions|tool_shares|tool_slots|tool_slot_installs|tool_hidden_extensions|tool_history|member|organization|invitation|jwks|agent_trace_spans|agent_trace_summaries|agent_feedback|agent_satisfaction_scores|agent_evals|agent_runs|agent_run_events|notifications|progress_runs|integration_configs|integration_pending_tasks|integration_thread_mappings|resources|org_members|org_invitations|bigquery_cache|dashboard_views|pg_catalog|information_schema|pg_class|pg_proc|pg_namespace|pg_user|pg_roles|pg_authid|pg_shadow)\b/i;
 
 // Refuses positional INSERTs (no column list). `INSERT INTO recordings VALUES
 // (...)` would let a extension stuff arbitrary owner_email values into a row.

package/corpus/core/src/feature-flags/a2a-action-route.ts

@@ -0,0 +1,56 @@
+import { getHeader } from "h3";
+import * as jose from "jose";
+
+import { verifyA2ATokenWithClaims } from "../a2a-claims.js";
+import type { ActionRouteAuthAdapter } from "../server/action-routes.js";
+
+const FLAG_ACTION_SCOPES = {
+  "list-feature-flags": "flags:read",
+  "set-feature-flag": "flags:write",
+} as const;
+
+export function declaresFeatureFlagDelegation(token: string): boolean {
+  try {
+    const raw = jose.decodeJwt(token);
+    const scopes =
+      typeof raw.scope === "string"
+        ? raw.scope.split(/\s+/)
+        : Array.isArray(raw.scope)
+          ? raw.scope.filter(
+              (scope): scope is string => typeof scope === "string",
+            )
+          : [];
+    return scopes.some((scope) => scope.startsWith("flags:"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Narrow opt-in adapter for fleet flag control. It owns Bearer credentials only
+ * for these two actions; malformed owned bearers reject rather than falling
+ * back to a browser cookie.
+ */
+export function createFeatureFlagA2AActionRouteAuth(
+  actionName: keyof typeof FLAG_ACTION_SCOPES,
+): ActionRouteAuthAdapter {
+  return {
+    async resolveCaller(event) {
+      const header = getHeader(event, "authorization");
+      if (!header?.startsWith("Bearer ")) return null;
+      const token = header.slice(7);
+      if (!declaresFeatureFlagDelegation(token)) return null;
+      const claims = await verifyA2ATokenWithClaims(token, event);
+      if (!claims || !claims.scope.includes(FLAG_ACTION_SCOPES[actionName])) {
+        throw new Error("Invalid feature flag delegation");
+      }
+      return {
+        owner: claims.email,
+        orgId: claims.orgId,
+        anonymous: false,
+        delegationJti: claims.jti,
+        delegationIssuer: claims.issuer,
+      };
+    },
+  };
+}

package/corpus/core/src/feature-flags/actions/get-feature-flags.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { listFeatureFlags } from "../registry.js";
+import { evaluateFeatureFlag } from "../store.js";
+
+export default defineAction({
+  description:
+    "Return the boolean values of every feature flag registered by this app for the current caller. Unknown or unconfigured flags always evaluate to false.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async (_args, ctx) => {
+    const scope = { userEmail: ctx?.userEmail, orgId: ctx?.orgId };
+    const values = Object.fromEntries(
+      await Promise.all(
+        listFeatureFlags().map(async ({ key }) => [
+          key,
+          await evaluateFeatureFlag(key, scope).catch(() => false),
+        ]),
+      ),
+    );
+    return values;
+  },
+});

package/corpus/core/src/feature-flags/actions/list-feature-flags.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { requireFeatureFlagManager } from "../permissions.js";
+import { listFeatureFlags } from "../registry.js";
+import { evaluateFeatureFlagRules, getFeatureFlagRules } from "../store.js";
+
+export default defineAction({
+  description:
+    "List this app's registered feature flags and their current rules. Organization owner/admin only (or the explicit no-org administrator).",
+  schema: z.object({}),
+  http: { method: "GET" },
+  toolCallable: false,
+  run: async (_args, ctx) => {
+    const definitions = listFeatureFlags();
+    let manager;
+    try {
+      manager = await requireFeatureFlagManager(ctx ?? {});
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        "statusCode" in error &&
+        (error as { statusCode?: number }).statusCode === 403
+      ) {
+        return {
+          contractVersion: 1,
+          status: "forbidden" as const,
+          reason: "forbidden" as const,
+          flags: [],
+          canManage: false,
+        };
+      }
+      throw error;
+    }
+    if (definitions.length === 0)
+      return {
+        contractVersion: 1,
+        status: "no-definitions" as const,
+        reason: "no-definitions" as const,
+        flags: [],
+        canManage: true,
+      };
+    const flags = await Promise.all(
+      definitions.map(async (definition) => {
+        const rules = await getFeatureFlagRules(definition.key, manager);
+        return {
+          ...definition,
+          rules,
+          enabledForCurrentUser: evaluateFeatureFlagRules(
+            definition.key,
+            rules,
+            {
+              userEmail: manager.email,
+              userKey: manager.email,
+              orgId: manager.orgId,
+            },
+          ),
+        };
+      }),
+    );
+    return {
+      contractVersion: 1,
+      status: "ready" as const,
+      reason: "ready" as const,
+      flags,
+      canManage: true,
+    };
+  },
+});

package/corpus/core/src/feature-flags/actions/set-feature-flag.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { requireFeatureFlagManager } from "../permissions.js";
+import { getFeatureFlagDefinition } from "../registry.js";
+import {
+  defaultFeatureFlagRules,
+  mutateFeatureFlagRules,
+  normalizeFeatureFlagRules,
+} from "../store.js";
+
+const rulesSchema = z.object({
+  mode: z.enum(["off", "on", "rules"]),
+  emails: z.array(z.string().email()).max(500).optional(),
+  orgIds: z.array(z.string().min(1).max(200)).max(500).optional(),
+  percentage: z.number().int().min(0).max(100).optional(),
+});
+
+const schema = z.discriminatedUnion("operation", [
+  z.object({
+    operation: z.literal("enable-for-current-user"),
+    key: z.string(),
+  }),
+  z.object({ operation: z.literal("off"), key: z.string() }),
+  z.object({
+    operation: z.literal("replace-rules"),
+    key: z.string(),
+    rules: rulesSchema,
+  }),
+]);
+
+export default defineAction({
+  description:
+    "Atomically manage one registered feature flag: enable it for the current user, turn it off immediately for the active scope, or replace its full rules. Organization owner/admin only (or the explicit no-org administrator).",
+  schema,
+  // Keep the strict discriminated union for runtime validation, but advertise
+  // an object-shaped schema so agent tool registries can expose the action.
+  // Root-level JSON Schema unions are intentionally rejected by the agent.
+  agentInputSchema: z.object({
+    operation: z.enum(["enable-for-current-user", "off", "replace-rules"]),
+    key: z.string(),
+    rules: rulesSchema.optional(),
+  }),
+  toolCallable: false,
+  audit: {
+    target: (args, _result, meta) => ({
+      type: "feature-flag",
+      id: args.key,
+      ownerEmail: meta.userEmail,
+      visibility: meta.orgId ? "org" : "private",
+    }),
+    summary: (args) => `Feature flag ${args.key}: ${args.operation}`,
+  },
+  run: async (args, ctx) => {
+    const manager = await requireFeatureFlagManager(ctx ?? {});
+    if (!getFeatureFlagDefinition(args.key)) {
+      throw new Error(`Unknown feature flag: ${args.key}`);
+    }
+
+    const persistedRules = await mutateFeatureFlagRules(
+      args.key,
+      manager,
+      (current) => {
+        let rules;
+        if (args.operation === "off") {
+          rules = defaultFeatureFlagRules();
+        } else if (args.operation === "replace-rules") {
+          rules = normalizeFeatureFlagRules(args.rules);
+        } else {
+          rules = normalizeFeatureFlagRules({
+            ...current,
+            // A globally-on flag already includes this user. Do not
+            // accidentally narrow it to a one-email rollout.
+            mode: current.mode === "on" ? "on" : "rules",
+            emails: [...current.emails, manager.email],
+          });
+        }
+        return { ...rules, updatedAt: Date.now(), updatedBy: manager.email };
+      },
+    );
+    return {
+      contractVersion: 1 as const,
+      status: "ready" as const,
+      key: args.key,
+      rules: persistedRules,
+      scope: { orgId: manager.orgId },
+    };
+  },
+});

package/corpus/core/src/feature-flags/index.ts

@@ -0,0 +1,21 @@
+export {
+  defineFeatureFlag,
+  defineFeatureFlags,
+  getFeatureFlagDefinition,
+  listFeatureFlags,
+  registerFeatureFlags,
+  type FeatureFlagDefinition,
+} from "./registry.js";
+export {
+  defaultFeatureFlagRules,
+  evaluateFeatureFlag,
+  evaluateFeatureFlagRules,
+  isFeatureFlagEnabled,
+  getFeatureFlagRules,
+  normalizeFeatureFlagRules,
+  type FeatureFlagMode,
+  type FeatureFlagRules,
+  type FeatureFlagScope,
+} from "./store.js";
+export { createFeatureFlagsPlugin } from "./plugin.js";
+export { createFeatureFlagA2AActionRouteAuth } from "./a2a-action-route.js";

package/corpus/core/src/feature-flags/permissions.ts

@@ -0,0 +1,53 @@
+import { getOrgRoleForEmail } from "../mcp/actions/service-token-access.js";
+import { canManageOrg } from "../org/permissions.js";
+
+export class FeatureFlagPermissionError extends Error {
+  statusCode: number;
+
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.statusCode = statusCode;
+  }
+}
+
+function productionAdminAllowlist(): Set<string> {
+  return new Set(
+    (process.env.AGENT_NATIVE_FEATURE_FLAG_ADMIN_EMAILS ?? "")
+      .split(",")
+      .map((email) => email.trim().toLowerCase())
+      .filter(Boolean),
+  );
+}
+
+/** Require an org admin/owner, or an explicit production no-org allowlist entry. */
+export async function requireFeatureFlagManager(scope: {
+  userEmail?: string;
+  orgId?: string | null;
+}): Promise<{ email: string; orgId: string | null }> {
+  const email = scope.userEmail?.trim().toLowerCase();
+  if (!email) {
+    throw new FeatureFlagPermissionError(
+      "Sign in to manage feature flags.",
+      401,
+    );
+  }
+  const orgId = scope.orgId?.trim() || null;
+  if (orgId) {
+    const role = await getOrgRoleForEmail(orgId, email);
+    if (!canManageOrg(role)) {
+      throw new FeatureFlagPermissionError(
+        "Only organization owners or admins can manage feature flags.",
+        403,
+      );
+    }
+    return { email, orgId };
+  }
+  if (process.env.NODE_ENV !== "production") return { email, orgId: null };
+  if (!productionAdminAllowlist().has(email)) {
+    throw new FeatureFlagPermissionError(
+      "Feature flag management without an organization requires an explicit admin allowlist entry.",
+      403,
+    );
+  }
+  return { email, orgId: null };
+}

package/corpus/core/src/feature-flags/plugin.ts

@@ -0,0 +1,44 @@
+import { getSetting } from "../settings/store.js";
+import {
+  registerFeatureFlags,
+  type FeatureFlagDefinition,
+} from "./registry.js";
+import { mutateFeatureFlagRules } from "./store.js";
+
+type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
+
+/** A tiny startup plugin for app-local, explicit feature-flag registration. */
+export function createFeatureFlagsPlugin(options: {
+  flags: readonly FeatureFlagDefinition[];
+  /**
+   * One-time compatibility bridge for apps that previously stored global
+   * booleans together in a single settings object. Only legacy `true` values
+   * are copied, and an explicit rule in the new store always wins.
+   */
+  legacyBooleanSetting?: {
+    settingKey: string;
+    flagKeys: readonly string[];
+  };
+}): NitroPluginDef {
+  return async () => {
+    registerFeatureFlags(options.flags);
+    if (!options.legacyBooleanSetting) return;
+
+    const legacy = await getSetting(options.legacyBooleanSetting.settingKey);
+    if (!legacy) return;
+    await Promise.all(
+      options.legacyBooleanSetting.flagKeys.map(async (key) => {
+        if (legacy[key] !== true) return;
+        await mutateFeatureFlagRules(key, {}, (current) => {
+          if (current.updatedAt !== null) return current;
+          return {
+            ...current,
+            mode: "on",
+            updatedAt: Date.now(),
+            updatedBy: "legacy-settings-migration",
+          };
+        });
+      }),
+    );
+  };
+}

package/corpus/core/src/feature-flags/registry.ts

@@ -0,0 +1,96 @@
+/**
+ * App-owned feature-flag definitions. Core intentionally starts with an empty
+ * registry: a flag key is part of an app's stable contract, not framework
+ * configuration that Core should guess at.
+ */
+export interface FeatureFlagDefinition {
+  key: string;
+  /** Boolean flags are always default-off; explicit in operator metadata. */
+  defaultValue?: false;
+  displayName?: string;
+  description?: string;
+}
+
+const registry = new Map<string, FeatureFlagDefinition>();
+
+function normalizeDefinition(
+  definition: FeatureFlagDefinition,
+): FeatureFlagDefinition {
+  const key = definition.key.trim();
+  if (!/^[A-Za-z][A-Za-z0-9._-]{0,63}$/.test(key)) {
+    throw new Error(
+      "Feature flag keys must be stable strings containing only letters, numbers, dots, underscores, or hyphens (1-64 characters).",
+    );
+  }
+  return {
+    key,
+    defaultValue: false,
+    ...(definition.displayName?.trim() && {
+      displayName: definition.displayName.trim(),
+    }),
+    ...(definition.description?.trim() && {
+      description: definition.description.trim(),
+    }),
+  };
+}
+
+/** Define one app-local feature flag for registration at server startup. */
+export function defineFeatureFlag(
+  definition: FeatureFlagDefinition,
+): FeatureFlagDefinition {
+  return Object.freeze(normalizeDefinition(definition));
+}
+
+/** Define a small app-owned feature-flag registry. */
+export function defineFeatureFlags(
+  definitions: readonly FeatureFlagDefinition[],
+): readonly FeatureFlagDefinition[] {
+  const seen = new Set<string>();
+  return Object.freeze(
+    definitions.map((definition) => {
+      const normalized = defineFeatureFlag(definition);
+      if (seen.has(normalized.key)) {
+        throw new Error(`Duplicate feature flag key: ${normalized.key}`);
+      }
+      seen.add(normalized.key);
+      return normalized;
+    }),
+  );
+}
+
+/** Register definitions once at Nitro startup. Re-registering identical data is safe for HMR. */
+export function registerFeatureFlags(
+  definitions: readonly FeatureFlagDefinition[],
+): void {
+  for (const rawDefinition of definitions) {
+    const definition = defineFeatureFlag(rawDefinition);
+    const existing = registry.get(definition.key);
+    if (!existing) {
+      registry.set(definition.key, definition);
+      continue;
+    }
+    if (
+      existing.displayName !== definition.displayName ||
+      existing.description !== definition.description
+    ) {
+      throw new Error(
+        `Feature flag ${definition.key} was registered with conflicting metadata.`,
+      );
+    }
+  }
+}
+
+export function listFeatureFlags(): readonly FeatureFlagDefinition[] {
+  return [...registry.values()].sort((a, b) => a.key.localeCompare(b.key));
+}
+
+export function getFeatureFlagDefinition(
+  key: string,
+): FeatureFlagDefinition | null {
+  return registry.get(key) ?? null;
+}
+
+/** Test-only registry reset; not exported from package entrypoints. */
+export function _resetFeatureFlagRegistryForTests(): void {
+  registry.clear();
+}