@agent-native/core 0.101.10 → 0.101.12

package/corpus/templates/mail/AGENTS.md

@@ -60,8 +60,9 @@ needed.
 - Never send mail unless the user explicitly asks to send. Draft or queue
   review by default. `send-email` has `needsApproval: true` — it is the
   canonical, intentionally rare use of the human-in-the-loop gate in this
-  framework; the loop pauses for approval on every real send. Drafting and
-  queueing are unaffected.
+  framework. An authenticated A2A caller may carry the user's exact chat
+  authorization for one matching send; otherwise the loop pauses for approval.
+  Drafting and queueing are unaffected.
 - When drafting, first read `get-mail-settings` for signature and writing
   style. Use `signature` exactly when present — draft-writing paths that build
   a `compose-*` entry (`manage-draft`, `open-queued-draft`) call
@@ -93,23 +94,24 @@ needed.
 
 ## Action Map
 
-| Action                                                                                                                                 | Purpose                                                                                |
-| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `search-emails` / `list-emails`                                                                                                        | Query across Gmail or local-fallback data by view/query.                               |
-| `get-email` / `get-thread`                                                                                                             | Full body/metadata for one message or thread.                                          |
-| `find-contact`                                                                                                                         | Resolve a name/partial address to a real email.                                        |
-| `get-hubspot-contact`                                                                                                                  | CRM contact + deals + tickets by email (HubSpot only).                                 |
-| `manage-draft`                                                                                                                         | Create/update/delete a `compose-{id}` draft (signature-aware).                         |
-| `send-email`                                                                                                                           | Real send. `needsApproval: true` — always pauses for human approval.                   |
-| `queue-email-draft` / `list-queued-drafts` / `update-queued-draft` / `open-queued-draft` / `send-queued-drafts`                        | Teammate/Slack draft-review workflow — see `draft-queue`.                              |
-| `mark-read` / `mark-thread-read` / `star-email` / `archive-email` / `unarchive-email` / `trash-email` / `untrash-email` / `move-email` | Per-message or per-thread state changes; most call `refresh-list` internally.          |
-| `manage-gmail-filters`                                                                                                                 | Provider-native Gmail filters (create/replace/delete).                                 |
-| `manage-automations` / `trigger-automations`                                                                                           | Natural-language inbox automation rules.                                               |
-| `respond-calendar-invite`                                                                                                              | Accept/decline/tentative an invite found in Mail.                                      |
-| `get-mail-settings` / `update-mail-settings` / `import-gmail-signature`                                                                | Signature and writing-style settings.                                                  |
-| `manage-snippets`                                                                                                                      | List/create/update/delete saved reply snippets insertable from the compose slash menu. |
-| `get-tracking`                                                                                                                         | Open/click stats for a previously sent, tracked message.                               |
-| `provider-api-catalog` / `provider-api-docs` / `provider-api-request`                                                                  | Raw Gmail, Calendar, or HubSpot API calls beyond the canned actions.                   |
+| Action                                                                                                                                 | Purpose                                                                                                       |
+| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `search-emails` / `list-emails`                                                                                                        | Query across Gmail or local-fallback data by view/query.                                                      |
+| `get-email` / `get-thread`                                                                                                             | Full body/metadata for one message or thread.                                                                 |
+| `find-contact`                                                                                                                         | Resolve a name/partial address to a real email.                                                               |
+| `get-hubspot-contact`                                                                                                                  | CRM contact + deals + tickets by email (HubSpot only).                                                        |
+| `create-attachment-upload`                                                                                                             | Mint a five-minute, owner-bound raw-byte upload URL for one local attachment.                                 |
+| `manage-draft`                                                                                                                         | Create/update/delete a `compose-{id}` draft (signature-aware).                                                |
+| `send-email`                                                                                                                           | Real send. `needsApproval: true`; exact authenticated chat grants run once, otherwise it pauses for approval. |
+| `queue-email-draft` / `list-queued-drafts` / `update-queued-draft` / `open-queued-draft` / `send-queued-drafts`                        | Teammate/Slack draft-review workflow — see `draft-queue`.                                                     |
+| `mark-read` / `mark-thread-read` / `star-email` / `archive-email` / `unarchive-email` / `trash-email` / `untrash-email` / `move-email` | Per-message or per-thread state changes; most call `refresh-list` internally.                                 |
+| `manage-gmail-filters`                                                                                                                 | Provider-native Gmail filters (create/replace/delete).                                                        |
+| `manage-automations` / `trigger-automations`                                                                                           | Natural-language inbox automation rules.                                                                      |
+| `respond-calendar-invite`                                                                                                              | Accept/decline/tentative an invite found in Mail.                                                             |
+| `get-mail-settings` / `update-mail-settings` / `import-gmail-signature`                                                                | Signature and writing-style settings.                                                                         |
+| `manage-snippets`                                                                                                                      | List/create/update/delete saved reply snippets insertable from the compose slash menu.                        |
+| `get-tracking`                                                                                                                         | Open/click stats for a previously sent, tracked message.                                                      |
+| `provider-api-catalog` / `provider-api-docs` / `provider-api-request`                                                                  | Raw Gmail, Calendar, or HubSpot API calls beyond the canned actions.                                          |
 
 ## Application State
 

package/corpus/templates/mail/actions/create-attachment-upload.ts

@@ -0,0 +1,49 @@
+import { defineAction } from "@agent-native/core/action";
+import {
+  getAppProductionUrl,
+  getRequestUserEmail,
+  withConfiguredAppBasePath,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { createAttachmentUploadTicket } from "../server/lib/attachment-upload-ticket.js";
+
+const originalNameSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(255)
+  .refine(
+    (value) => !/[\\/\0\r\n]/.test(value),
+    "Filename must not contain path separators or control characters",
+  );
+
+export default defineAction({
+  description:
+    "Create a short-lived authenticated Mail upload URL for one local attachment. Upload the file bytes with HTTP PUT, then pass the returned attachment handle to ask_app so Mail can include it in a draft or approved send. Creating the URL does not send email.",
+  schema: z.object({
+    originalName: originalNameSchema.describe(
+      "Display filename, including its extension (for example, report.png)",
+    ),
+  }),
+  run: async ({ originalName }) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Authentication required");
+    const ticket = await createAttachmentUploadTicket(ownerEmail, originalName);
+    const appUrl = withConfiguredAppBasePath(getAppProductionUrl());
+    const uploadUrl = `${appUrl}/api/media/attachment-upload/${encodeURIComponent(ticket.uploadId)}`;
+    return {
+      method: "PUT" as const,
+      uploadUrl,
+      headers: { Authorization: `Bearer ${ticket.token}` },
+      expiresAt: new Date(ticket.expiresAt).toISOString(),
+      maxBytes: 10 * 1024 * 1024,
+      attachment: {
+        filename: ticket.filename,
+        originalName: ticket.originalName,
+        mimeType: ticket.mimeType,
+      },
+      next: "PUT the raw local file bytes to uploadUrl with the returned Authorization header before passing attachment to ask_app. Do not paste base64 into chat or action arguments.",
+    };
+  },
+});

package/corpus/templates/mail/changelog/2026-07-14-connected-agents-can-now-securely-upload-local-files-for-mai.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-14
+---
+
+Connected agents can now securely upload local attachments, honor an exact send you explicitly authorized in chat, and otherwise pause real sends for browser approval.

package/corpus/templates/mail/server/handlers/media.ts

@@ -1,10 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { uploadFile } from "@agent-native/core/file-upload";
 import { streamFile, getSession } from "@agent-native/core/server";
 import {
   defineEventHandler,
+  getHeader,
   getQuery,
   readRawBody,
   getRouterParam,
@@ -15,9 +15,20 @@ import {
 } from "h3";
 import { nanoid } from "nanoid";
 
-import { getStoredUpload, putStoredUpload } from "../lib/upload-store.js";
+import {
+  claimAttachmentUploadTicket,
+  verifyAttachmentUploadTicket,
+} from "../lib/attachment-upload-ticket.js";
+import {
+  MAX_UPLOAD_BYTES,
+  MediaStorageSetupError,
+  mimeTypeForUpload,
+  storeMediaUpload,
+  uploadsDirectory,
+} from "../lib/media-upload.js";
+import { getStoredUpload } from "../lib/upload-store.js";
 
-const UPLOADS_DIR = path.resolve("data/uploads");
+const UPLOADS_DIR = uploadsDirectory();
 
 // Ensure uploads directory exists (guarded for edge runtimes without filesystem)
 try {
@@ -28,26 +39,6 @@ try {
   // Edge runtime (e.g. Cloudflare Workers) — no local filesystem
 }
 
-const MIME_MAP: Record<string, string> = {
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".svg": "image/svg+xml",
-  ".pdf": "application/pdf",
-  ".txt": "text/plain",
-  ".csv": "text/csv",
-  ".doc": "application/msword",
-  ".docx":
-    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-  ".xls": "application/vnd.ms-excel",
-  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-  ".zip": "application/zip",
-};
-
-const MAX_UPLOAD_BYTES = 10 * 1024 * 1024; // 10 MB
-
 export const uploadMedia = defineEventHandler(async (event: H3Event) => {
   const session = await getSession(event).catch(() => null);
   if (!session?.email) {
@@ -69,51 +60,83 @@ export const uploadMedia = defineEventHandler(async (event: H3Event) => {
 
     const originalName = (getQuery(event).filename as string) || "upload";
     const ext = path.extname(originalName).toLowerCase() || ".bin";
-    const id = nanoid(12) + ext;
-    const filePath = path.join(UPLOADS_DIR, id);
-
-    const mimeType = MIME_MAP[ext] || "application/octet-stream";
-    const payload = {
-      url: `/api/media/${id}`,
-      filename: id,
+    return await storeMediaUpload({
+      ownerEmail: session.email,
+      data: body instanceof Uint8Array ? body : new Uint8Array(body),
+      filename: nanoid(12) + ext,
       originalName,
-      mimeType,
-      size: body.byteLength,
-    };
+    });
+  } catch (err) {
+    if (err instanceof MediaStorageSetupError) {
+      setResponseStatus(event, 503);
+      return {
+        error: err.message,
+        storageSetupRequired: true,
+      };
+    }
+    console.error("[media] Upload failed:", err);
+    setResponseStatus(event, 500);
+    return { error: "Upload failed" };
+  }
+});
+
+export const uploadAttachmentWithTicket = defineEventHandler(
+  async (event: H3Event) => {
+    const uploadId = getRouterParam(event, "uploadId") as string;
+    const authorization = getHeader(event, "authorization") || "";
+    const token = authorization.startsWith("Bearer ")
+      ? authorization.slice("Bearer ".length).trim()
+      : "";
+    // Reject an invalid bearer before buffering request bytes. The later
+    // atomic claim remains the concurrency boundary immediately before the
+    // storage side effect.
+    const verified = await verifyAttachmentUploadTicket(uploadId, token);
+    if (!verified) {
+      setResponseStatus(event, 401);
+      return { error: "Invalid or expired attachment upload URL" };
+    }
+    const body = await readRawBody(event, false);
+    if (!body || !body.byteLength) {
+      setResponseStatus(event, 400);
+      return { error: "No file data" };
+    }
+    if (body.byteLength > MAX_UPLOAD_BYTES) {
+      setResponseStatus(event, 413);
+      return { error: "File too large (max 10 MB)" };
+    }
+
+    const claimed = await claimAttachmentUploadTicket(uploadId, token);
+    if (!claimed) {
+      setResponseStatus(event, 401);
+      return { error: "Invalid or expired attachment upload URL" };
+    }
 
     try {
-      fs.writeFileSync(filePath, body);
-    } catch {
-      const uploaded = await uploadFile({
+      const uploaded = await storeMediaUpload({
+        ownerEmail: claimed.ownerEmail,
         data: body instanceof Uint8Array ? body : new Uint8Array(body),
-        filename: originalName,
-        mimeType,
-        ownerEmail: session.email,
-        recordAsset: false,
+        filename: claimed.ticket.filename,
+        originalName: claimed.ticket.originalName,
       });
-      if (!uploaded?.url) {
+      return {
+        ...uploaded,
+        attachment: {
+          filename: uploaded.filename,
+          originalName: uploaded.originalName,
+          mimeType: uploaded.mimeType,
+        },
+      };
+    } catch (err) {
+      if (err instanceof MediaStorageSetupError) {
         setResponseStatus(event, 503);
-        return {
-          error:
-            "File storage is not configured. Connect Builder.io or another upload provider before attaching files in hosted environments.",
-          storageSetupRequired: true,
-        };
+        return { error: err.message, storageSetupRequired: true };
       }
-      await putStoredUpload(session.email, {
-        ...payload,
-        url: uploaded.url,
-        createdAt: Date.now(),
-      });
-      return { ...payload, url: uploaded.url, provider: uploaded.provider };
+      console.error("[media] Ticketed attachment upload failed:", err);
+      setResponseStatus(event, 500);
+      return { error: "Upload failed" };
     }
-
-    return payload;
-  } catch (err) {
-    console.error("[media] Upload failed:", err);
-    setResponseStatus(event, 500);
-    return { error: "Upload failed" };
-  }
-});
+  },
+);
 
 export const serveMedia = defineEventHandler(async (event: H3Event) => {
   const filename = getRouterParam(event, "filename") as string;
@@ -161,7 +184,7 @@ export const serveMedia = defineEventHandler(async (event: H3Event) => {
     return Buffer.from(stored.dataBase64, "base64");
   }
 
-  const mimeType = MIME_MAP[ext] || "application/octet-stream";
+  const mimeType = mimeTypeForUpload(filename);
 
   setResponseHeader(event, "Content-Type", mimeType);
   setResponseHeader(

package/corpus/templates/mail/server/lib/attachment-upload-ticket.ts

@@ -0,0 +1,234 @@
+import crypto from "node:crypto";
+
+import { getDbExec, isPostgres } from "@agent-native/core/db";
+import { getUserSetting } from "@agent-native/core/settings";
+import { nanoid } from "nanoid";
+
+import { extensionForUpload, mimeTypeForUpload } from "./media-upload.js";
+
+const SETTING_KEY = "mail-attachment-upload-ticket";
+const TICKET_TTL_MS = 5 * 60 * 1000;
+const MAX_PENDING_TICKETS = 20;
+const MAX_CAS_ATTEMPTS = 8;
+
+export interface AttachmentUploadTicket extends Record<string, unknown> {
+  uploadId: string;
+  filename: string;
+  originalName: string;
+  mimeType: string;
+  tokenHash: string;
+  expiresAt: number;
+}
+
+interface AttachmentUploadTickets extends Record<string, unknown> {
+  tickets: Record<string, AttachmentUploadTicket>;
+}
+
+function tokenHash(token: string): string {
+  return crypto.createHash("sha256").update(token).digest("hex");
+}
+
+function encodeOwner(ownerEmail: string): string {
+  return Buffer.from(ownerEmail, "utf8").toString("base64url");
+}
+
+function decodeOwner(token: string): string | null {
+  const ownerPart = token.split(".", 1)[0];
+  if (!ownerPart) return null;
+  try {
+    const owner = Buffer.from(ownerPart, "base64url").toString("utf8");
+    return owner.includes("@") ? owner : null;
+  } catch {
+    return null;
+  }
+}
+
+function hashesMatch(left: string, right: string): boolean {
+  const leftBuffer = Buffer.from(left, "utf8");
+  const rightBuffer = Buffer.from(right, "utf8");
+  if (leftBuffer.length !== rightBuffer.length) return false;
+  return crypto.timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+function settingStorageKey(ownerEmail: string): string {
+  return `u:${ownerEmail}:${SETTING_KEY}`;
+}
+
+function settingsTable(): string {
+  return isPostgres() ? "public.settings" : "settings";
+}
+
+function parseTickets(raw: string | null): AttachmentUploadTickets {
+  if (!raw) return { tickets: {} };
+  try {
+    const parsed = JSON.parse(raw) as Partial<AttachmentUploadTickets>;
+    if (!parsed.tickets || typeof parsed.tickets !== "object") {
+      return { tickets: {} };
+    }
+    return {
+      tickets: Object.fromEntries(
+        Object.entries(parsed.tickets).filter(
+          ([uploadId, ticket]) =>
+            uploadId &&
+            ticket &&
+            typeof ticket === "object" &&
+            ticket.uploadId === uploadId,
+        ),
+      ),
+    };
+  } catch {
+    return { tickets: {} };
+  }
+}
+
+function pruneTickets(
+  tickets: Record<string, AttachmentUploadTicket>,
+  now: number,
+): Record<string, AttachmentUploadTicket> {
+  return Object.fromEntries(
+    Object.entries(tickets)
+      .filter(
+        ([, ticket]) =>
+          Number.isFinite(ticket.expiresAt) && ticket.expiresAt >= now,
+      )
+      .sort(([, left], [, right]) => right.expiresAt - left.expiresAt)
+      .slice(0, MAX_PENDING_TICKETS),
+  );
+}
+
+async function readTicketsRow(
+  ownerEmail: string,
+): Promise<{ raw: string | null; collection: AttachmentUploadTickets }> {
+  // This initializes the framework-owned settings table without duplicating
+  // its schema/startup logic. The raw read below deliberately bypasses the
+  // per-request settings cache because compare-and-swap retries need fresh data.
+  await getUserSetting(ownerEmail, SETTING_KEY);
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT value FROM ${settingsTable()} WHERE key = ?`,
+    args: [settingStorageKey(ownerEmail)],
+  });
+  const raw = rows.length ? String(rows[0].value ?? rows[0][0]) : null;
+  return { raw, collection: parseTickets(raw) };
+}
+
+async function compareAndSwapTickets(
+  ownerEmail: string,
+  expectedRaw: string | null,
+  collection: AttachmentUploadTickets,
+): Promise<boolean> {
+  const value = JSON.stringify(collection);
+  const key = settingStorageKey(ownerEmail);
+  const client = getDbExec();
+  if (expectedRaw === null) {
+    const result = await client.execute({
+      sql: isPostgres()
+        ? `INSERT INTO ${settingsTable()} (key, value, updated_at) VALUES (?, ?, ?) ON CONFLICT (key) DO NOTHING`
+        : `INSERT OR IGNORE INTO ${settingsTable()} (key, value, updated_at) VALUES (?, ?, ?)`,
+      args: [key, value, Date.now()],
+    });
+    return result.rowsAffected === 1;
+  }
+  const result = await client.execute({
+    sql: `UPDATE ${settingsTable()} SET value = ?, updated_at = ? WHERE key = ? AND value = ?`,
+    args: [value, Date.now(), key, expectedRaw],
+  });
+  return result.rowsAffected === 1;
+}
+
+export async function createAttachmentUploadTicket(
+  ownerEmail: string,
+  originalName: string,
+): Promise<AttachmentUploadTicket & { token: string }> {
+  const uploadId = nanoid(12);
+  const filename = `${uploadId}${extensionForUpload(originalName)}`;
+  const token = `${encodeOwner(ownerEmail)}.${crypto.randomBytes(32).toString("base64url")}`;
+  const ticket: AttachmentUploadTicket = {
+    uploadId,
+    filename,
+    originalName,
+    mimeType: mimeTypeForUpload(originalName),
+    tokenHash: tokenHash(token),
+    expiresAt: Date.now() + TICKET_TTL_MS,
+  };
+
+  for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt += 1) {
+    const { raw, collection } = await readTicketsRow(ownerEmail);
+    const tickets = pruneTickets(
+      // Put the new ticket first so stable sorting keeps it when many tickets
+      // share the same millisecond expiry at the collection limit.
+      { [uploadId]: ticket, ...collection.tickets },
+      Date.now(),
+    );
+    if (await compareAndSwapTickets(ownerEmail, raw, { tickets })) {
+      return { ...ticket, token };
+    }
+  }
+  throw new Error("Could not reserve an attachment upload ticket");
+}
+
+export async function verifyAttachmentUploadTicket(
+  uploadId: string,
+  token: string,
+): Promise<{ ownerEmail: string; ticket: AttachmentUploadTicket } | null> {
+  const ownerEmail = decodeOwner(token);
+  if (!ownerEmail) return null;
+
+  for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt += 1) {
+    const { raw, collection } = await readTicketsRow(ownerEmail);
+    const tickets = pruneTickets(collection.tickets, Date.now());
+    const ticket = tickets[uploadId];
+    if (JSON.stringify(tickets) !== JSON.stringify(collection.tickets)) {
+      if (!(await compareAndSwapTickets(ownerEmail, raw, { tickets })))
+        continue;
+    }
+    if (
+      !ticket ||
+      typeof ticket.tokenHash !== "string" ||
+      !hashesMatch(ticket.tokenHash, tokenHash(token))
+    ) {
+      return null;
+    }
+    return { ownerEmail, ticket };
+  }
+  return null;
+}
+
+/**
+ * Atomically validates and removes a one-time upload capability.
+ *
+ * The caller must claim immediately before the storage side effect. Once this
+ * returns a ticket it cannot be reclaimed, even if storage later fails. That
+ * fail-closed behavior prevents retries from turning an ambiguous write into a
+ * replay vulnerability.
+ */
+export async function claimAttachmentUploadTicket(
+  uploadId: string,
+  token: string,
+): Promise<{ ownerEmail: string; ticket: AttachmentUploadTicket } | null> {
+  const ownerEmail = decodeOwner(token);
+  if (!ownerEmail) return null;
+
+  for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt += 1) {
+    const { raw, collection } = await readTicketsRow(ownerEmail);
+    const tickets = pruneTickets(collection.tickets, Date.now());
+    const ticket = tickets[uploadId];
+    if (
+      !ticket ||
+      typeof ticket.tokenHash !== "string" ||
+      !hashesMatch(ticket.tokenHash, tokenHash(token))
+    ) {
+      if (JSON.stringify(tickets) !== JSON.stringify(collection.tickets)) {
+        if (!(await compareAndSwapTickets(ownerEmail, raw, { tickets }))) {
+          continue;
+        }
+      }
+      return null;
+    }
+
+    delete tickets[uploadId];
+    if (await compareAndSwapTickets(ownerEmail, raw, { tickets })) {
+      return { ownerEmail, ticket };
+    }
+  }
+  return null;
+}

package/corpus/templates/mail/server/lib/mail-connector-catalog.ts

@@ -1,8 +1,12 @@
 /**
  * Deliberately narrow authenticated MCP surface for Mail.
  *
- * External callers may read inbox coverage through list-emails. Other actions
- * remain available through the in-app agent, ask_app, or an explicit
- * full-catalog connection; tool-search alone never makes them callable.
+ * External callers may read inbox coverage and mint a short-lived attachment
+ * upload capability. Other actions remain available through the in-app agent,
+ * ask_app, or an explicit full-catalog connection; tool-search alone never
+ * makes them callable.
  */
-export const MAIL_CONNECTOR_CATALOG = ["list-emails"] as const;
+export const MAIL_CONNECTOR_CATALOG = [
+  "list-emails",
+  "create-attachment-upload",
+] as const;