@agent-native/core 0.107.2 → 0.108.0

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();
+}

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

@@ -0,0 +1,176 @@
+import { getOrgSetting, mutateOrgSetting } from "../settings/org-settings.js";
+import { getSetting, mutateSetting } from "../settings/store.js";
+import {
+  getFeatureFlagDefinition,
+  type FeatureFlagDefinition,
+} from "./registry.js";
+
+export type FeatureFlagMode = "off" | "on" | "rules";
+
+export interface FeatureFlagRules {
+  version: 1;
+  mode: FeatureFlagMode;
+  emails: string[];
+  orgIds: string[];
+  percentage: number;
+  updatedAt: number | null;
+  updatedBy: string | null;
+}
+
+export interface FeatureFlagScope {
+  userEmail?: string;
+  /** Canonical authenticated identity. V1 callers use normalized email. */
+  userKey?: string;
+  orgId?: string | null;
+}
+
+export const FEATURE_FLAG_SETTINGS_PREFIX = "feature-flag:";
+
+function settingKey(key: string): string {
+  return `${FEATURE_FLAG_SETTINGS_PREFIX}${key}`;
+}
+
+export function defaultFeatureFlagRules(): FeatureFlagRules {
+  return {
+    version: 1,
+    mode: "off",
+    emails: [],
+    orgIds: [],
+    percentage: 0,
+    updatedAt: null,
+    updatedBy: null,
+  };
+}
+
+function stringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return [
+    ...new Set(
+      value
+        .filter((item): item is string => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean),
+    ),
+  ].sort();
+}
+
+export function normalizeFeatureFlagRules(value: unknown): FeatureFlagRules {
+  if (!value || typeof value !== "object") return defaultFeatureFlagRules();
+  const raw = value as Record<string, unknown>;
+  const mode: FeatureFlagMode =
+    raw.mode === "on" || raw.mode === "rules" || raw.mode === "off"
+      ? raw.mode
+      : "off";
+  const percentage =
+    typeof raw.percentage === "number" && Number.isFinite(raw.percentage)
+      ? Math.max(0, Math.min(100, Math.floor(raw.percentage)))
+      : 0;
+  return {
+    version: 1,
+    mode,
+    emails: stringList(raw.emails).map((email) => email.toLowerCase()),
+    orgIds: stringList(raw.orgIds),
+    percentage,
+    updatedAt:
+      typeof raw.updatedAt === "number" && Number.isSafeInteger(raw.updatedAt)
+        ? raw.updatedAt
+        : null,
+    updatedBy:
+      typeof raw.updatedBy === "string" && raw.updatedBy.trim()
+        ? raw.updatedBy.trim().toLowerCase()
+        : null,
+  };
+}
+
+export async function getFeatureFlagRules(
+  key: string,
+  scope: Pick<FeatureFlagScope, "orgId">,
+): Promise<FeatureFlagRules> {
+  if (!getFeatureFlagDefinition(key)) return defaultFeatureFlagRules();
+  // An organization-specific rule overrides the global rule. The fallback is
+  // what makes global exact-org targeting meaningful for callers in an org.
+  const stored = scope.orgId?.trim()
+    ? ((await getOrgSetting(scope.orgId, settingKey(key))) ??
+      (await getSetting(settingKey(key))))
+    : await getSetting(settingKey(key));
+  return normalizeFeatureFlagRules(stored);
+}
+
+/**
+ * Atomically derive one flag's scoped rules. An org's first override starts
+ * from the global fallback, then becomes independently CAS-protected.
+ */
+export async function mutateFeatureFlagRules(
+  key: string,
+  scope: Pick<FeatureFlagScope, "orgId">,
+  updater: (
+    current: FeatureFlagRules,
+  ) => FeatureFlagRules | Promise<FeatureFlagRules>,
+): Promise<FeatureFlagRules> {
+  if (!getFeatureFlagDefinition(key)) {
+    throw new Error(`Unknown feature flag: ${key}`);
+  }
+  const mutate = async (stored: Record<string, unknown> | null) => {
+    const fallback =
+      stored == null && scope.orgId?.trim()
+        ? await getSetting(settingKey(key))
+        : null;
+    return {
+      ...(await updater(normalizeFeatureFlagRules(stored ?? fallback))),
+    };
+  };
+  const persisted = scope.orgId?.trim()
+    ? await mutateOrgSetting(scope.orgId, settingKey(key), mutate)
+    : await mutateSetting(settingKey(key), mutate);
+  return normalizeFeatureFlagRules(persisted);
+}
+
+function rolloutBucket(input: string): number {
+  // FNV-1a is deliberately tiny, deterministic, and independent of runtime.
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0) % 100;
+}
+
+export function evaluateFeatureFlagRules(
+  key: string,
+  rules: FeatureFlagRules,
+  scope: FeatureFlagScope,
+): boolean {
+  if (rules.mode === "off") return false;
+  if (rules.mode === "on") return true;
+  const email = scope.userEmail?.trim().toLowerCase();
+  if (email && rules.emails.includes(email)) return true;
+  if (scope.orgId && rules.orgIds.includes(scope.orgId)) return true;
+  const userKey = scope.userKey?.trim() || email;
+  if (!userKey || rules.percentage <= 0) return false;
+  return rolloutBucket(`${key}:${userKey}`) < rules.percentage;
+}
+
+export async function evaluateFeatureFlag(
+  key: string,
+  scope: FeatureFlagScope = {},
+): Promise<boolean> {
+  if (!getFeatureFlagDefinition(key)) return false;
+  try {
+    return evaluateFeatureFlagRules(
+      key,
+      await getFeatureFlagRules(key, scope),
+      scope,
+    );
+  } catch {
+    // A feature flag must never become an availability dependency.
+    return false;
+  }
+}
+
+/** Ergonomic app-action guard. Accepts either a registered definition or its key. */
+export async function isFeatureFlagEnabled(
+  flag: string | FeatureFlagDefinition,
+  scope: FeatureFlagScope = {},
+): Promise<boolean> {
+  return evaluateFeatureFlag(typeof flag === "string" ? flag : flag.key, scope);
+}

package/corpus/core/src/index.ts

@@ -142,6 +142,21 @@ export {
   type AutomationWorkflowDefinition,
   type JsonSchema,
 } from "./automation/index.js";
+export {
+  createFeatureFlagsPlugin,
+  defineFeatureFlag,
+  defineFeatureFlags,
+  evaluateFeatureFlag,
+  getFeatureFlagDefinition,
+  getFeatureFlagRules,
+  isFeatureFlagEnabled,
+  listFeatureFlags,
+  registerFeatureFlags,
+  type FeatureFlagDefinition,
+  type FeatureFlagMode,
+  type FeatureFlagRules,
+  type FeatureFlagScope,
+} from "./feature-flags/index.js";
 
 // Server
 export {