@agent-native/core 0.79.17 → 0.79.19

package/corpus/core/src/server/create-server.ts

@@ -1,5 +1,3 @@
-import path from "path";
-
 import {
   createApp,
   createRouter,
@@ -11,8 +9,8 @@ import {
   type H3Event,
 } from "h3";
 
+import { getOrgContext } from "../org/context.js";
 import { readBody } from "../server/h3-helpers.js";
-import { agentEnv } from "../shared/agent-env.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
 import {
   EMBED_TRANSPLANT_HEADER,
@@ -20,12 +18,19 @@ import {
   MCP_EMBED_CORS_ALLOW_HEADERS,
   shouldAllowMcpEmbedCredentials,
 } from "../shared/mcp-embed-headers.js";
-import { BUILDER_ENV_KEYS } from "./builder-browser.js";
+import { getSession } from "./auth.js";
 import {
   getAllowedCorsOrigin,
   readCorsAllowedOrigins,
 } from "./cors-origins.js";
-import { isEnvVarWriteAllowed } from "./env-var-writes.js";
+import { resolveSecret } from "./credential-provider.js";
+import { runWithRequestContext } from "./request-context.js";
+import {
+  findUnsupportedScopedKeyNames,
+  saveKeyValuesToScopedSecrets,
+  ScopedKeyStorageError,
+  type ScopedKeySaveRequestScope,
+} from "./scoped-key-storage.js";
 
 export interface EnvKeyConfig {
   /** Environment variable name (e.g. "HUBSPOT_ACCESS_TOKEN") */
@@ -47,70 +52,10 @@ export interface CreateServerOptions {
   pingMessage?: string;
   /** Disable the /_agent-native/ping health check. Default: false */
   disablePing?: boolean;
-  /** Env key configuration for the settings UI. Enables /_agent-native/env-status and /_agent-native/env-vars routes. */
+  /** Key configuration for the settings UI. Enables status plus the scoped-secret compatibility save route. */
   envKeys?: EnvKeyConfig[];
 }
 
-/**
- * Upsert vars into a .env file, preserving existing structure.
- */
-export async function upsertEnvFile(
-  envPath: string,
-  vars: Array<{ key: string; value: string }>,
-): Promise<void> {
-  // Sanitize: reject values that could inject additional env vars
-  for (const { key, value } of vars) {
-    if (/[\n\r\0]/.test(value)) {
-      throw new Error(
-        `Invalid env var value for ${key}: must not contain newlines or control characters`,
-      );
-    }
-  }
-
-  const fs = await import("fs");
-
-  let content = "";
-  try {
-    content = fs.readFileSync(envPath, "utf-8");
-  } catch {
-    // File doesn't exist yet
-  }
-
-  const lines = content.split("\n");
-  const remaining = new Map(vars.map((v) => [v.key, v.value]));
-
-  // Update existing lines in place
-  const updated = lines.map((line) => {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) return line;
-    const eqIndex = trimmed.indexOf("=");
-    if (eqIndex === -1) return line;
-    const key = trimmed.slice(0, eqIndex).trim();
-    if (remaining.has(key)) {
-      const value = remaining.get(key)!;
-      remaining.delete(key);
-      return `${key}=${value}`;
-    }
-    return line;
-  });
-
-  // Append new vars
-  for (const [key, value] of remaining) {
-    updated.push(`${key}=${value}`);
-  }
-
-  // Ensure trailing newline
-  let result = updated.join("\n");
-  if (!result.endsWith("\n")) result += "\n";
-
-  try {
-    fs.mkdirSync(path.dirname(envPath), { recursive: true });
-    fs.writeFileSync(envPath, result);
-  } catch {
-    // Edge runtimes don't have writable filesystem — skip silently
-  }
-}
-
 export interface CreateServerResult {
   app: ReturnType<typeof createApp>;
   router: ReturnType<typeof createRouter>;
@@ -120,7 +65,8 @@ export interface CreateServerResult {
  * Create a pre-configured H3 app with standard agent-native setup:
  * - CORS headers via middleware
  * - /_agent-native/ping health check
- * - /_agent-native/env-status and /_agent-native/env-vars (when envKeys is provided)
+ * - /_agent-native/env-status and the scoped-secret compatibility save route
+ *   at /_agent-native/env-vars (when envKeys is provided)
  *
  * Returns { app, router } — mount routes on `router`.
  */
@@ -242,7 +188,6 @@ export function createServer(
   }
 
   const router = createRouter();
-  app.use(router);
 
   // Health check
   if (!options.disablePing) {
@@ -259,73 +204,67 @@ export function createServer(
   // Env key management routes
   if (options.envKeys) {
     const envKeys = options.envKeys;
+    const allowedEnvKeyNames = envKeys.map(({ key }) => key);
 
     router.get(
       "/_agent-native/env-status",
-      defineEventHandler(() => {
-        return envKeys.map((cfg) => ({
-          key: cfg.key,
-          label: cfg.label,
-          required: cfg.required ?? false,
-          configured: !!process.env[cfg.key],
-          ...(cfg.helpText ? { helpText: cfg.helpText } : {}),
-        }));
+      defineEventHandler(async (event) => {
+        const session = await getSession(event).catch(() => null);
+        const userEmail = session?.email;
+        let orgId: string | undefined;
+        if (userEmail) {
+          const orgCtx = await getOrgContext(event).catch(() => null);
+          orgId = orgCtx?.orgId ?? undefined;
+        }
+        return Promise.all(
+          envKeys.map(async (cfg) => ({
+            key: cfg.key,
+            label: cfg.label,
+            required: cfg.required ?? false,
+            configured:
+              Boolean(process.env[cfg.key]) ||
+              (await runWithRequestContext({ userEmail, orgId }, () =>
+                resolveSecret(cfg.key).then(Boolean),
+              )),
+            ...(cfg.helpText ? { helpText: cfg.helpText } : {}),
+          })),
+        );
       }),
     );
 
     router.post(
       "/_agent-native/env-vars",
       defineEventHandler(async (event: H3Event) => {
-        // Env vars are deployment-wide globals — see isEnvVarWriteAllowed
-        // above. Disable the endpoint on any multi-tenant deploy.
-        if (!isEnvVarWriteAllowed()) {
-          setResponseStatus(event, 403);
-          return {
-            error:
-              "env-vars endpoint disabled on multi-tenant deployments. Use scoped secrets or credentials for user/org API keys.",
-          };
-        }
-
         const body = await readBody(event);
-        const { vars } = body as {
+        const { vars, scope } = body as {
           vars?: Array<{ key: string; value: string }>;
+          scope?: ScopedKeySaveRequestScope;
         };
-
-        if (!Array.isArray(vars) || vars.length === 0) {
-          setResponseStatus(event, 400);
-          return { error: "vars array required" };
-        }
-
-        // Only allow keys that are in the env config
-        const allowedKeys = new Set(envKeys.map((k) => k.key));
-        const blockedEnvVarWriteKeys = new Set<string>(BUILDER_ENV_KEYS);
-        const filtered = vars.filter(
-          (v) =>
-            typeof v.key === "string" &&
-            allowedKeys.has(v.key) &&
-            !blockedEnvVarWriteKeys.has(v.key),
+        const unsupportedKeys = findUnsupportedScopedKeyNames(
+          vars,
+          allowedEnvKeyNames,
         );
-        if (filtered.length === 0) {
+        if (unsupportedKeys.length > 0) {
           setResponseStatus(event, 400);
-          return { error: "No recognized env keys in request" };
+          return {
+            error: `Unsupported env key${unsupportedKeys.length === 1 ? "" : "s"}: ${unsupportedKeys.join(", ")}`,
+          };
         }
-
-        // Write to .env file
-        const envPath = path.join(process.cwd(), ".env");
-        await upsertEnvFile(envPath, filtered);
-
-        // Update process.env so the app picks up the new values immediately
-        for (const { key, value } of filtered) {
-          process.env[key] = value;
+        try {
+          const result = await saveKeyValuesToScopedSecrets(event, vars, scope);
+          return { saved: result.saved, storage: "scoped-secrets" };
+        } catch (err) {
+          if (err instanceof ScopedKeyStorageError) {
+            setResponseStatus(event, err.statusCode);
+            return { error: err.message };
+          }
+          setResponseStatus(event, 500);
+          return { error: "Failed to save keys" };
         }
-
-        // Notify parent (Builder or frame) via postMessage
-        agentEnv.setVars(filtered);
-
-        return { saved: filtered.map((v) => v.key) };
       }),
     );
   }
 
+  app.use(router);
   return { app, router };
 }

package/corpus/core/src/server/email-actions.ts

@@ -2,9 +2,8 @@
  * Framework-level agent action for sending transactional/notification emails
  * via the configured core email transport (Resend or SendGrid).
  *
- * Registered as a native tool in every template when RESEND_API_KEY or
- * SENDGRID_API_KEY is set. When neither key is present the tool is omitted
- * from the agent surface so the agent never sees it.
+ * Registered as a native tool in every template. sendEmail() checks the
+ * scoped Resend/SendGrid configuration at call time.
  *
  * SAFETY: the action description instructs the agent to draft-first and only
  * send when the user explicitly confirms, matching the mail template convention.
@@ -16,7 +15,7 @@
  */
 
 import type { ActionEntry } from "../agent/production-agent.js";
-import { isEmailConfigured, sendEmail } from "./email.js";
+import { sendEmail } from "./email.js";
 
 function markdownToText(md: string): string {
   return md
@@ -115,8 +114,6 @@ function markdownToHtml(md: string): string {
 }
 
 export function createCoreEmailActionEntries(): Record<string, ActionEntry> {
-  if (!isEmailConfigured()) return {};
-
   return {
     "core-send-email": {
       tool: {

package/corpus/core/src/server/email.ts

@@ -1,7 +1,7 @@
 /**
  * Email transport for system emails (password resets, invitations, notifications).
  *
- * Providers are selected by env var:
+ * Providers are selected by scoped secrets:
  *   RESEND_API_KEY    — https://resend.com
  *   SENDGRID_API_KEY  — https://sendgrid.com
  *   EMAIL_FROM        — "Name <addr@domain>" (optional; defaults to Resend's sandbox)
@@ -10,6 +10,8 @@
  * so the reset-password flow still works end-to-end for local development.
  */
 
+import { resolveSecret } from "./credential-provider.js";
+
 export type EmailProvider = "resend" | "sendgrid" | "dev";
 
 export interface EmailAttachment {
@@ -33,32 +35,65 @@ export interface SendEmailArgs {
   attachments?: EmailAttachment[];
 }
 
-export function isEmailConfigured(): boolean {
-  return !!(process.env.RESEND_API_KEY || process.env.SENDGRID_API_KEY);
+interface EmailTransportConfig {
+  provider: EmailProvider;
+  resendApiKey?: string;
+  sendgridApiKey?: string;
+  from?: string;
 }
 
-export function getEmailProvider(): EmailProvider {
-  if (process.env.RESEND_API_KEY) return "resend";
-  if (process.env.SENDGRID_API_KEY) return "sendgrid";
-  return "dev";
+async function resolveEmailTransport(): Promise<EmailTransportConfig> {
+  const [resendApiKey, sendgridApiKey, from] = await Promise.all([
+    resolveSecret("RESEND_API_KEY"),
+    resolveSecret("SENDGRID_API_KEY"),
+    resolveSecret("EMAIL_FROM"),
+  ]);
+  const resolvedFrom = from ?? undefined;
+  if (resendApiKey) {
+    return {
+      provider: "resend",
+      resendApiKey,
+      from: resolvedFrom,
+    };
+  }
+  if (sendgridApiKey) {
+    return {
+      provider: "sendgrid",
+      sendgridApiKey,
+      from: resolvedFrom,
+    };
+  }
+  return { provider: "dev", from: resolvedFrom };
 }
 
-function getFromAddress(override?: string, provider?: EmailProvider): string {
-  const explicit = override || process.env.EMAIL_FROM;
+export async function isEmailConfigured(): Promise<boolean> {
+  return (await resolveEmailTransport()).provider !== "dev";
+}
+
+export async function getEmailProvider(): Promise<EmailProvider> {
+  return (await resolveEmailTransport()).provider;
+}
+
+function getFromAddress(
+  config: EmailTransportConfig,
+  override?: string,
+): string {
+  const explicit = override || config.from;
   if (explicit) return explicit;
   // Resend lets unverified accounts send from its sandbox domain; SendGrid
   // does not, so falling back there would cause silent 403s at runtime.
-  if (provider === "sendgrid") {
+  if (config.provider === "sendgrid") {
     throw new Error(
-      "EMAIL_FROM is required when using SendGrid — set it to a verified sender address.",
+      "EMAIL_FROM is required when using SendGrid — save it as a verified sender address.",
     );
   }
   return "Agent Native <onboarding@resend.dev>";
 }
 
 export async function sendEmail(args: SendEmailArgs): Promise<void> {
-  const provider = getEmailProvider();
-  const from = getFromAddress(args.from, provider);
+  const config = await resolveEmailTransport();
+  const provider = config.provider;
+  const from = getFromAddress(config, args.from);
 
   if (provider === "resend") {
     const payload: Record<string, unknown> = {
@@ -89,7 +124,7 @@ export async function sendEmail(args: SendEmailArgs): Promise<void> {
     const res = await fetch("https://api.resend.com/emails", {
       method: "POST",
       headers: {
-        Authorization: `Bearer ${process.env.RESEND_API_KEY}`,
+        Authorization: `Bearer ${config.resendApiKey}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify(payload),
@@ -140,7 +175,7 @@ export async function sendEmail(args: SendEmailArgs): Promise<void> {
     const res = await fetch("https://api.sendgrid.com/v3/mail/send", {
       method: "POST",
       headers: {
-        Authorization: `Bearer ${process.env.SENDGRID_API_KEY}`,
+        Authorization: `Bearer ${config.sendgridApiKey}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify(sgPayload),
@@ -157,12 +192,12 @@ export async function sendEmail(args: SendEmailArgs): Promise<void> {
   // to send rather than silently leaking secrets to logs.
   if (process.env.NODE_ENV === "production") {
     throw new Error(
-      "No email provider configured. Set RESEND_API_KEY or SENDGRID_API_KEY.",
+      "No email provider configured. Save RESEND_API_KEY or SENDGRID_API_KEY in settings.",
     );
   }
   console.log(
     `\n[agent-native:email] No email provider configured. ` +
-      `Set RESEND_API_KEY or SENDGRID_API_KEY to send real emails.\n` +
+      `Save RESEND_API_KEY or SENDGRID_API_KEY in settings to send real emails.\n` +
       `---\nTo: ${args.to}\nFrom: ${from}\nSubject: ${args.subject}\n\n` +
       `${args.text || stripHtml(args.html)}\n---\n`,
   );

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

@@ -1,6 +1,5 @@
 export {
   createServer,
-  upsertEnvFile,
   type CreateServerOptions,
   type EnvKeyConfig,
 } from "./create-server.js";
@@ -325,6 +324,7 @@ export {
   unregisterFileUploadProvider,
   listFileUploadProviders,
   getActiveFileUploadProvider,
+  getActiveFileUploadProviderForRequest,
   uploadFile,
   builderFileUploadProvider,
   type FileUploadInput,
@@ -381,6 +381,7 @@ export {
   resolveHasCompleteBuilderConnection,
   resolveBuilderCredentials,
   resolveBuilderCredential,
+  readDeployCredentialEnv,
   writeBuilderCredentials,
   deleteBuilderCredentials,
   resolveSecret,

package/corpus/core/src/server/scoped-key-storage.ts

@@ -0,0 +1,223 @@
+import type { H3Event } from "h3";
+
+import { getOrgContext } from "../org/context.js";
+import {
+  getRequiredSecret,
+  type RegisteredSecret,
+  type SecretScope,
+} from "../secrets/register.js";
+import { writeAppSecret } from "../secrets/storage.js";
+import { getSession } from "./auth.js";
+
+const KEY_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export type ScopedKeySaveRequestScope =
+  | "app"
+  | "auto"
+  | "org"
+  | "user"
+  | "workspace"
+  | undefined;
+
+export interface ScopedKeyValue {
+  key: string;
+  value: string;
+}
+
+export interface ScopedKeySaveRow {
+  key: string;
+  scope: SecretScope;
+  scopeId: string;
+}
+
+export class ScopedKeyStorageError extends Error {
+  constructor(
+    readonly statusCode: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ScopedKeyStorageError";
+  }
+}
+
+export function findUnsupportedScopedKeyNames(
+  vars: unknown,
+  allowedKeys: Iterable<string>,
+): string[] {
+  if (!Array.isArray(vars)) return [];
+
+  const allowed = new Set(allowedKeys);
+  const unsupported = new Set<string>();
+  for (const entry of vars) {
+    if (!entry || typeof entry !== "object") continue;
+    const key = (entry as { key?: unknown }).key;
+    const normalizedKey = typeof key === "string" ? key.trim() : "";
+    if (normalizedKey && !allowed.has(normalizedKey)) {
+      unsupported.add(normalizedKey);
+    }
+  }
+  return [...unsupported];
+}
+
+function redactSecretFromMessage(message: string, secretValue: string): string {
+  if (!message || !secretValue) return message;
+  return message.split(secretValue).join("[redacted]");
+}
+
+function normalizeKeyValueVars(vars: unknown): ScopedKeyValue[] {
+  if (!Array.isArray(vars) || vars.length === 0) {
+    throw new ScopedKeyStorageError(400, "vars array required");
+  }
+
+  const out: ScopedKeyValue[] = [];
+  for (const entry of vars) {
+    if (!entry || typeof entry !== "object") {
+      throw new ScopedKeyStorageError(400, "Each var must be an object");
+    }
+    const { key, value } = entry as { key?: unknown; value?: unknown };
+    const normalizedKey = typeof key === "string" ? key.trim() : "";
+    if (!normalizedKey || !KEY_NAME_RE.test(normalizedKey)) {
+      throw new ScopedKeyStorageError(
+        400,
+        normalizedKey
+          ? `Invalid key name "${normalizedKey}"`
+          : "Each var requires a key",
+      );
+    }
+    const normalizedValue = typeof value === "string" ? value.trim() : "";
+    if (!normalizedValue) {
+      throw new ScopedKeyStorageError(
+        400,
+        `Value for ${normalizedKey} must be non-empty`,
+      );
+    }
+    out.push({ key: normalizedKey, value: normalizedValue });
+  }
+  return out;
+}
+
+function resolveTargetScope(
+  secret: RegisteredSecret | undefined,
+  requestedScope: ScopedKeySaveRequestScope,
+): SecretScope {
+  if (secret?.kind === "api-key") return secret.scope;
+  if (requestedScope === "org") return "org";
+  if (requestedScope === "workspace" || requestedScope === "app") {
+    return "workspace";
+  }
+  return "user";
+}
+
+async function resolveScopeId(
+  event: H3Event,
+  scope: SecretScope,
+): Promise<{
+  scopeId: string;
+  orgRole: string | null;
+  orgId: string | null;
+}> {
+  const session = await getSession(event).catch(() => null);
+  const email = session?.email ?? null;
+
+  if (scope === "user") {
+    if (!email) {
+      throw new ScopedKeyStorageError(401, "Sign in to save keys");
+    }
+    return { scopeId: email, orgRole: null, orgId: null };
+  }
+
+  const orgCtx = await getOrgContext(event).catch(() => null);
+  const orgId = orgCtx?.orgId ?? null;
+  const orgRole = orgCtx?.role ?? null;
+
+  if (scope === "org") {
+    if (!orgId) {
+      throw new ScopedKeyStorageError(401, "No active organization");
+    }
+    return { scopeId: orgId, orgRole, orgId };
+  }
+
+  if (orgId) {
+    return { scopeId: orgId, orgRole, orgId };
+  }
+  if (!email) {
+    throw new ScopedKeyStorageError(401, "Sign in to save workspace keys");
+  }
+  return { scopeId: `solo:${email}`, orgRole: null, orgId: null };
+}
+
+function assertCanMutateScope(
+  scope: SecretScope,
+  scopeId: string,
+  orgRole: string | null,
+): void {
+  if (scope === "user") return;
+  if (scope === "workspace" && scopeId.startsWith("solo:")) return;
+  if (orgRole === "owner" || orgRole === "admin") return;
+  throw new ScopedKeyStorageError(
+    403,
+    scope === "org"
+      ? "Only organization owners and admins can set org-scoped keys"
+      : "Only organization owners and admins can set workspace-scoped keys",
+  );
+}
+
+async function validateRegisteredSecret(
+  secret: RegisteredSecret | undefined,
+  value: string,
+): Promise<void> {
+  if (!secret) return;
+  if (secret.kind === "oauth") {
+    throw new ScopedKeyStorageError(
+      400,
+      `"${secret.key}" is an OAuth-kind secret and must be connected via OAuth`,
+    );
+  }
+  if (!secret.validator) return;
+  try {
+    const result = await secret.validator(value);
+    const ok = typeof result === "boolean" ? result : result?.ok === true;
+    if (ok) return;
+    const error =
+      typeof result === "object" && result && result.error
+        ? String(result.error)
+        : "Validator rejected the value";
+    throw new ScopedKeyStorageError(400, redactSecretFromMessage(error, value));
+  } catch (err) {
+    if (err instanceof ScopedKeyStorageError) throw err;
+    const message =
+      err instanceof Error
+        ? `Validator threw: ${err.message}`
+        : "Validator threw";
+    throw new ScopedKeyStorageError(
+      400,
+      redactSecretFromMessage(message, value),
+    );
+  }
+}
+
+export async function saveKeyValuesToScopedSecrets(
+  event: H3Event,
+  vars: unknown,
+  requestedScope?: ScopedKeySaveRequestScope,
+): Promise<{ saved: string[]; rows: ScopedKeySaveRow[] }> {
+  const normalized = normalizeKeyValueVars(vars);
+  const rows: ScopedKeySaveRow[] = [];
+
+  for (const entry of normalized) {
+    const secret = getRequiredSecret(entry.key);
+    const scope = resolveTargetScope(secret, requestedScope);
+    const { scopeId, orgRole } = await resolveScopeId(event, scope);
+    assertCanMutateScope(scope, scopeId, orgRole);
+    await validateRegisteredSecret(secret, entry.value);
+    await writeAppSecret({
+      key: entry.key,
+      value: entry.value,
+      scope,
+      scopeId,
+    });
+    rows.push({ key: entry.key, scope, scopeId });
+  }
+
+  return { saved: rows.map((row) => row.key), rows };
+}

package/corpus/core/src/shared/agent-env.ts

@@ -1,5 +1,5 @@
 /**
- * Isomorphic Agent Env Utility
+ * Isomorphic Agent Key Utility
  *
  * Works in both browser and Node.js contexts:
  * - Browser: sends via postMessage to the parent window
@@ -18,7 +18,7 @@ const isBrowser =
   typeof window !== "undefined" && typeof window.postMessage === "function";
 
 /**
- * Send env vars to the host (Builder cloud or Claude frame).
+ * Send key/value settings to the host for scoped secret persistence.
  * Automatically detects environment (browser vs Node.js) and uses the right transport.
  */
 function setVars(vars: EnvVar[]): void {
@@ -41,6 +41,6 @@ function setVars(vars: EnvVar[]): void {
 }
 
 export const agentEnv = {
-  /** Send environment variables to the host for persistence */
+  /** Send key/value settings to the host for scoped secret persistence. */
   setVars,
 };

package/corpus/core/src/sharing/actions/share-resource.ts

@@ -262,7 +262,7 @@ export default defineAction({
     if (
       args.notify !== false &&
       args.principalType === "user" &&
-      isEmailConfigured() &&
+      (await isEmailConfigured()) &&
       !isSyntheticQaEmail(principalId)
     ) {
       try {