@netlify/spark-ui 1.31.0-alpha.1 → 1.31.0-alpha.3

package/dist/components/preact/DropZone/drop-core/authedDropClient.d.ts

@@ -9,16 +9,19 @@ export interface AuthenticatedDropClientConfig {
      */
     proxyBase?: string;
     /**
-     * Direct API base for the per-file uploads. The proxy above runs in a Lambda
-     * with a ~6MB request body limit, so file PUTs go straight to
-     * `api.netlify.com` (whose `/api/*` CORS policy allows any origin).
+     * Direct API base for the file uploads. The proxy above runs in a Lambda with
+     * a ~6MB request body limit, so file PUTs go straight to `api.netlify.com`
+     * (whose `/api/*` CORS policy allows any origin).
      */
     apiBase?: string;
     /**
-     * Mint a short-lived bearer token for those direct uploads. On netlify.com
-     * this is `GET /access-control/generate-access-control-token`, whose
+     * Mint a bearer token for those direct uploads. On netlify.com this is
+     * `GET /access-control/generate-access-control-token`, whose
      * `accessControlToken` the API decrypts back into the user's access token.
      * Resolving `null` means "no session" and surfaces as `NotAuthenticatedError`.
+     *
+     * Called repeatedly, not once: the token issued to a non-app origin lives
+     * only 30 seconds, which a multi-file upload routinely outlasts.
      */
     getUploadToken: () => Promise<string | null>;
     /** Create the site in this account. Omit to use the user's default account. */
@@ -36,17 +39,17 @@ export interface AuthenticatedDropClientConfig {
  * There is no claim step, so the caller should hand off to the site's dashboard
  * page rather than the claim page.
  *
- * Requests split across two hosts by necessity: JSON calls go through the
- * consumer's access-control proxy (cookie session, no token handling in the
- * browser), while the per-file PUTs go direct to `api.netlify.com` with the
- * short-lived bearer from `getUploadToken()` because the proxy can't carry
- * large bodies.
+ * Requests split across two hosts by necessity. JSON calls (create the site,
+ * create the deploy, poll it) go through the consumer's access-control proxy on
+ * the session cookie — no token involved, and nothing that can expire mid-deploy.
+ * File uploads can't: the proxy caps bodies at ~6MB, so they go direct to
+ * `api.netlify.com` with a bearer, re-minted as it ages (see `TOKEN_REUSE_MS`).
  *
- * Error-mapping invariant: only pre-mutation failures — a null upload token, or
- * a 401/403 creating the site — throw `NotAuthenticatedError`, which is the
- * signal the drop flow may safely retry anonymously. Once the site exists, an
- * auth failure throws a plain status-carrying error instead: falling back at
- * that point would strand an empty site in the account *and* deploy a duplicate
+ * Error-mapping invariant: only pre-mutation failures — a null upload token at
+ * the gate, or a 401/403 creating the site — throw `NotAuthenticatedError`,
+ * which is the signal the drop flow may safely retry anonymously. Once the site
+ * exists, any auth failure throws a plain error instead: falling back at that
+ * point would strand an empty site in the account *and* deploy a duplicate
  * anonymously.
  */
 export declare class AuthenticatedDropClient implements DropClient {
@@ -56,25 +59,42 @@ export declare class AuthenticatedDropClient implements DropClient {
     private accountSlug?;
     private pollIntervalMs;
     private timeoutMs;
+    private cachedToken?;
     constructor({ proxyBase, apiBase, getUploadToken, accountSlug, pollIntervalMs, timeoutMs, }: AuthenticatedDropClientConfig);
     /**
-     * The token here is the upload bearer, not a drop token — it authorizes the
-     * direct-API file PUTs, while the proxied JSON calls ignore it and ride the
-     * session cookie. Minted once per deploy, before anything is created, so a
-     * missing session fails the whole attempt cleanly.
+     * The auth gate. Minting here — before anything is created — is what lets a
+     * logged-out visitor fail cleanly and fall back to the anonymous flow. The
+     * returned token is threaded through `deployFiles`, but only the uploads
+     * actually need one, and they re-mint rather than trusting this to still be
+     * valid by the time they run.
      */
     getToken(): Promise<string>;
+    /**
+     * A token young enough to authorize an upload, minting a new one once the
+     * cached one nears its 30s expiry.
+     *
+     * Deliberately NOT `NotAuthenticatedError` when minting fails: by the time
+     * uploads run the site already exists, and that error would send the drop
+     * back through the anonymous path — leaving an empty project behind and
+     * deploying a duplicate. See the class doc.
+     */
+    private freshToken;
     /**
      * Two proxied calls: create the site in the visitor's account, then the
      * deploy on it. Mapped into the anonymous `DropResponse` shape so
      * `deployFiles` runs unchanged over either client.
      */
     createDeploy(files: Digest, _token: string): Promise<DropResponse>;
-    uploadFile(deployId: string, path: string, content: ArrayBuffer, token: string): Promise<void>;
     /**
-     * Poll the deploy through the proxy until it settles — the session cookie
-     * outlives the short-lived upload bearer, so a slow deploy can't expire its
-     * own poll. Resolve on `ready`, throw on `error`/`rejected`, throw on timeout.
+     * Direct to `api.netlify.com` on a freshly-aged bearer — the threaded `token`
+     * is ignored because an upload queue easily outlives the 30 seconds it was
+     * minted with. PUT (not POST) so paths with "&" etc. work.
+     */
+    uploadFile(deployId: string, path: string, content: ArrayBuffer, _token: string): Promise<void>;
+    /**
+     * Poll the deploy through the proxy until it settles: resolve on `ready`,
+     * throw on `error`/`rejected`, throw on timeout. On the session cookie rather
+     * than a bearer, so a deploy taking minutes can't outlive its own credentials.
      */
     waitUntilReady(deploy: DropResponse, _token: string): Promise<void>;
 }

package/dist/components/preact/DropZone/drop-core/authedDropClient.js

@@ -1,59 +1,78 @@
-var p = Object.defineProperty;
-var h = (n, t, s) => t in n ? p(n, t, { enumerable: !0, configurable: !0, writable: !0, value: s }) : n[t] = s;
-var r = (n, t, s) => h(n, typeof t != "symbol" ? t + "" : t, s);
+var h = Object.defineProperty;
+var p = (r, e, o) => e in r ? h(r, e, { enumerable: !0, configurable: !0, writable: !0, value: o }) : r[e] = o;
+var i = (r, e, o) => p(r, typeof e != "symbol" ? e + "" : e, o);
 import { apiError as d } from "./client.js";
-import { NotAuthenticatedError as l, SiteCreateError as y } from "./errors.js";
-const u = "/access-control/bb-api/api/v1", w = "https://api.netlify.com/api/v1", f = 1e3, m = 10 * 60 * 1e3, T = /* @__PURE__ */ new Set(["ready", "error", "rejected"]);
+import { NotAuthenticatedError as l, SiteCreateError as u } from "./errors.js";
+const y = "/access-control/bb-api/api/v1", w = "https://api.netlify.com/api/v1", T = 1e3, f = 10 * 60 * 1e3, k = 20 * 1e3, m = /* @__PURE__ */ new Set(["ready", "error", "rejected"]);
 class g {
   constructor({
-    proxyBase: t = u,
-    apiBase: s = w,
-    getUploadToken: i,
-    accountSlug: o,
-    pollIntervalMs: a = f,
-    timeoutMs: e = m
+    proxyBase: e = y,
+    apiBase: o = w,
+    getUploadToken: n,
+    accountSlug: s,
+    pollIntervalMs: a = T,
+    timeoutMs: t = f
   }) {
-    r(this, "proxyBase");
-    r(this, "apiBase");
-    r(this, "getUploadToken");
-    r(this, "accountSlug");
-    r(this, "pollIntervalMs");
-    r(this, "timeoutMs");
-    this.proxyBase = t, this.apiBase = s, this.getUploadToken = i, this.accountSlug = o, this.pollIntervalMs = a, this.timeoutMs = e;
+    i(this, "proxyBase");
+    i(this, "apiBase");
+    i(this, "getUploadToken");
+    i(this, "accountSlug");
+    i(this, "pollIntervalMs");
+    i(this, "timeoutMs");
+    i(this, "cachedToken");
+    this.proxyBase = e, this.apiBase = o, this.getUploadToken = n, this.accountSlug = s, this.pollIntervalMs = a, this.timeoutMs = t;
   }
   /**
-   * The token here is the upload bearer, not a drop token — it authorizes the
-   * direct-API file PUTs, while the proxied JSON calls ignore it and ride the
-   * session cookie. Minted once per deploy, before anything is created, so a
-   * missing session fails the whole attempt cleanly.
+   * The auth gate. Minting here — before anything is created — is what lets a
+   * logged-out visitor fail cleanly and fall back to the anonymous flow. The
+   * returned token is threaded through `deployFiles`, but only the uploads
+   * actually need one, and they re-mint rather than trusting this to still be
+   * valid by the time they run.
    */
   async getToken() {
-    const t = await this.getUploadToken();
-    if (!t) throw new l();
-    return t;
+    const e = await this.getUploadToken();
+    if (!e) throw new l();
+    return this.cachedToken = { value: e, mintedAt: Date.now() }, e;
+  }
+  /**
+   * A token young enough to authorize an upload, minting a new one once the
+   * cached one nears its 30s expiry.
+   *
+   * Deliberately NOT `NotAuthenticatedError` when minting fails: by the time
+   * uploads run the site already exists, and that error would send the drop
+   * back through the anonymous path — leaving an empty project behind and
+   * deploying a duplicate. See the class doc.
+   */
+  async freshToken() {
+    const e = Date.now();
+    if (this.cachedToken && e - this.cachedToken.mintedAt < k)
+      return this.cachedToken.value;
+    const o = await this.getUploadToken();
+    if (!o) throw new Error("could not renew the upload token");
+    return this.cachedToken = { value: o, mintedAt: e }, o;
   }
   /**
    * Two proxied calls: create the site in the visitor's account, then the
    * deploy on it. Mapped into the anonymous `DropResponse` shape so
    * `deployFiles` runs unchanged over either client.
    */
-  async createDeploy(t, s) {
-    const i = this.accountSlug ? `/${this.accountSlug}/sites` : "/sites", o = await fetch(`${this.proxyBase}${i}`, {
+  async createDeploy(e, o) {
+    const n = this.accountSlug ? `/${this.accountSlug}/sites` : "/sites", s = await fetch(`${this.proxyBase}${n}`, {
       method: "POST",
       credentials: "include",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ created_via: "drop" })
     });
-    if (o.status === 401 || o.status === 403) throw new l();
-    if (!o.ok) throw new y(o.status);
-    const a = await o.json(), e = await fetch(`${this.proxyBase}/sites/${a.id}/deploys`, {
+    if (s.status === 401 || s.status === 403) throw new l();
+    if (!s.ok) throw new u(s.status);
+    const a = await s.json(), t = await fetch(`${this.proxyBase}/sites/${a.id}/deploys`, {
       method: "POST",
       credentials: "include",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ files: t, deploy_source: "drop" })
+      body: JSON.stringify({ files: e, deploy_source: "drop" })
     });
-    if (!e.ok) throw d("deploy create", e.status);
-    const c = await e.json();
+    if (!t.ok) throw d("deploy create", t.status);
+    const c = await t.json();
     return {
       id: a.id,
       deploy_id: c.id,
@@ -61,35 +80,40 @@ class g {
       required: c.required ?? []
     };
   }
-  async uploadFile(t, s, i, o) {
-    const a = await fetch(`${this.apiBase}/deploys/${t}/files${s}`, {
+  /**
+   * Direct to `api.netlify.com` on a freshly-aged bearer — the threaded `token`
+   * is ignored because an upload queue easily outlives the 30 seconds it was
+   * minted with. PUT (not POST) so paths with "&" etc. work.
+   */
+  async uploadFile(e, o, n, s) {
+    const a = await this.freshToken(), t = await fetch(`${this.apiBase}/deploys/${e}/files${o}`, {
       method: "PUT",
-      headers: { "Content-Type": "application/octet-stream", Authorization: `Bearer ${o}` },
-      body: i
+      headers: { "Content-Type": "application/octet-stream", Authorization: `Bearer ${a}` },
+      body: n
     });
-    if (!a.ok) throw d(`upload ${s}`, a.status);
+    if (!t.ok) throw d(`upload ${o}`, t.status);
   }
   /**
-   * Poll the deploy through the proxy until it settles — the session cookie
-   * outlives the short-lived upload bearer, so a slow deploy can't expire its
-   * own poll. Resolve on `ready`, throw on `error`/`rejected`, throw on timeout.
+   * Poll the deploy through the proxy until it settles: resolve on `ready`,
+   * throw on `error`/`rejected`, throw on timeout. On the session cookie rather
+   * than a bearer, so a deploy taking minutes can't outlive its own credentials.
    */
-  async waitUntilReady(t, s) {
-    const i = this.timeoutMs / this.pollIntervalMs;
-    for (let o = 0; o < i; o++) {
-      const a = await fetch(`${this.proxyBase}/deploys/${t.deploy_id}`, {
+  async waitUntilReady(e, o) {
+    const n = this.timeoutMs / this.pollIntervalMs;
+    for (let s = 0; s < n; s++) {
+      const a = await fetch(`${this.proxyBase}/deploys/${e.deploy_id}`, {
         credentials: "include"
       });
       if (a.ok) {
-        const e = await a.json();
-        if (e.state && T.has(e.state)) {
-          if (e.state === "ready") return;
+        const t = await a.json();
+        if (t.state && m.has(t.state)) {
+          if (t.state === "ready") return;
           throw new Error(
-            e.error_message ? `deploy failed: ${e.error_message}` : "deploy failed"
+            t.error_message ? `deploy failed: ${t.error_message}` : "deploy failed"
           );
         }
       }
-      await new Promise((e) => setTimeout(e, this.pollIntervalMs));
+      await new Promise((t) => setTimeout(t, this.pollIntervalMs));
     }
     throw new Error("Deploy did not become ready in time");
   }

package/dist/components/preact/DropZone/drop-core/buildClient.d.ts

@@ -35,10 +35,14 @@ export interface AuthenticatedBuildClientConfig {
      */
     apiBase?: string;
     /**
-     * Mint a short-lived bearer token for that direct upload. On netlify.com this
-     * is `GET /access-control/generate-access-control-token`, whose
+     * Mint a bearer token for that direct upload. On netlify.com this is
+     * `GET /access-control/generate-access-control-token`, whose
      * `accessControlToken` the API decrypts back into the user's access token.
      * Resolving `null` means "no session" and surfaces as `NotAuthenticatedError`.
+     *
+     * Note the token issued to a non-app origin lives only 30 seconds. It is
+     * minted immediately before the upload, but a zip that takes longer than that
+     * to transfer will still be rejected mid-flight — see `createBuildFromZip`.
      */
     getUploadToken: () => Promise<string | null>;
     /** Create the site in this account. Omit to use the user's default account. */
@@ -82,17 +86,24 @@ export declare class AuthenticatedBuildClient implements BuildClient {
      * (see the note on `apiBase`), authorized by a freshly minted bearer token.
      * `Content-Type` is left unset on purpose so the browser adds the multipart
      * boundary itself.
+     *
+     * Known ceiling: this is one request on a 30s token, and re-minting can't
+     * help once it is in flight. A zip that takes longer than that to upload will
+     * fail — the app origin gets 300s for exactly this reason, and lifting the
+     * limit for other origins is a platform-side change.
      */
     createBuildFromZip(siteId: string, zip: File): Promise<BuildResponse>;
     /**
-     * Poll the build's deploy through the proxy until it settles, mirroring
+     * Poll the build's deploy until it settles, mirroring
      * `AnonymousDropClient.waitUntilReady` — resolve on `ready`, throw on
      * `error`/`rejected`, throw on timeout. A build that hasn't been given a
      * deploy id yet has nothing pollable, so it resolves immediately and the
      * caller falls back to the site page.
      *
-     * Optional in the drop flow: a build takes minutes, so the default hand-off
-     * redirects to the app's deploy page (live logs) instead of waiting here.
+     * Optional in the drop flow, and off by default: a build takes minutes, so
+     * the useful hand-off is usually the project page rather than a spinner.
+     * Polling rides the session cookie, so it cannot outlive its credentials the
+     * way a 30s bearer would.
      */
     waitUntilBuildReady(build: BuildResponse): Promise<void>;
 }

package/dist/components/preact/DropZone/drop-core/buildClient.js

@@ -43,6 +43,11 @@ class _ {
    * (see the note on `apiBase`), authorized by a freshly minted bearer token.
    * `Content-Type` is left unset on purpose so the browser adds the multipart
    * boundary itself.
+   *
+   * Known ceiling: this is one request on a 30s token, and re-minting can't
+   * help once it is in flight. A zip that takes longer than that to upload will
+   * fail — the app origin gets 300s for exactly this reason, and lifting the
+   * limit for other origins is a platform-side change.
    */
   async createBuildFromZip(t, e) {
     const a = await this.getUploadToken();
@@ -59,14 +64,16 @@ class _ {
     return s.json();
   }
   /**
-   * Poll the build's deploy through the proxy until it settles, mirroring
+   * Poll the build's deploy until it settles, mirroring
    * `AnonymousDropClient.waitUntilReady` — resolve on `ready`, throw on
    * `error`/`rejected`, throw on timeout. A build that hasn't been given a
    * deploy id yet has nothing pollable, so it resolves immediately and the
    * caller falls back to the site page.
    *
-   * Optional in the drop flow: a build takes minutes, so the default hand-off
-   * redirects to the app's deploy page (live logs) instead of waiting here.
+   * Optional in the drop flow, and off by default: a build takes minutes, so
+   * the useful hand-off is usually the project page rather than a spinner.
+   * Polling rides the session cookie, so it cannot outlive its credentials the
+   * way a 30s bearer would.
    */
   async waitUntilBuildReady(t) {
     if (!t.deploy_id) return;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/spark-ui",
   "description": "Assets, design tokens, components, and utilities",
-  "version": "1.31.0-alpha.1",
+  "version": "1.31.0-alpha.3",
   "type": "module",
   "main": "dist/components/preact/index.js",
   "types": "dist/components/preact/index.d.ts",

package/packages/components/preact/DropZone/drop-core/authedDropClient.ts

@@ -12,16 +12,19 @@ export interface AuthenticatedDropClientConfig {
    */
   proxyBase?: string;
   /**
-   * Direct API base for the per-file uploads. The proxy above runs in a Lambda
-   * with a ~6MB request body limit, so file PUTs go straight to
-   * `api.netlify.com` (whose `/api/*` CORS policy allows any origin).
+   * Direct API base for the file uploads. The proxy above runs in a Lambda with
+   * a ~6MB request body limit, so file PUTs go straight to `api.netlify.com`
+   * (whose `/api/*` CORS policy allows any origin).
    */
   apiBase?: string;
   /**
-   * Mint a short-lived bearer token for those direct uploads. On netlify.com
-   * this is `GET /access-control/generate-access-control-token`, whose
+   * Mint a bearer token for those direct uploads. On netlify.com this is
+   * `GET /access-control/generate-access-control-token`, whose
    * `accessControlToken` the API decrypts back into the user's access token.
    * Resolving `null` means "no session" and surfaces as `NotAuthenticatedError`.
+   *
+   * Called repeatedly, not once: the token issued to a non-app origin lives
+   * only 30 seconds, which a multi-file upload routinely outlasts.
    */
   getUploadToken: () => Promise<string | null>;
   /** Create the site in this account. Omit to use the user's default account. */
@@ -41,6 +44,13 @@ const API_BASE = 'https://api.netlify.com/api/v1';
 const POLL_INTERVAL_MS = 1000;
 const TIMEOUT_MS = 10 * 60 * 1000;
 
+/**
+ * How long a minted upload token is reused before minting another. The server
+ * issues non-app origins a 30s token, so this leaves a margin for the request
+ * it authorizes to finish.
+ */
+const TOKEN_REUSE_MS = 20 * 1000;
+
 /** Deploy states that end the wait — `ready` succeeds, the rest are failures. */
 const TERMINAL_STATES = new Set(['ready', 'error', 'rejected']);
 
@@ -65,17 +75,17 @@ interface SiteDeployResponse {
  * There is no claim step, so the caller should hand off to the site's dashboard
  * page rather than the claim page.
  *
- * Requests split across two hosts by necessity: JSON calls go through the
- * consumer's access-control proxy (cookie session, no token handling in the
- * browser), while the per-file PUTs go direct to `api.netlify.com` with the
- * short-lived bearer from `getUploadToken()` because the proxy can't carry
- * large bodies.
+ * Requests split across two hosts by necessity. JSON calls (create the site,
+ * create the deploy, poll it) go through the consumer's access-control proxy on
+ * the session cookie — no token involved, and nothing that can expire mid-deploy.
+ * File uploads can't: the proxy caps bodies at ~6MB, so they go direct to
+ * `api.netlify.com` with a bearer, re-minted as it ages (see `TOKEN_REUSE_MS`).
  *
- * Error-mapping invariant: only pre-mutation failures — a null upload token, or
- * a 401/403 creating the site — throw `NotAuthenticatedError`, which is the
- * signal the drop flow may safely retry anonymously. Once the site exists, an
- * auth failure throws a plain status-carrying error instead: falling back at
- * that point would strand an empty site in the account *and* deploy a duplicate
+ * Error-mapping invariant: only pre-mutation failures — a null upload token at
+ * the gate, or a 401/403 creating the site — throw `NotAuthenticatedError`,
+ * which is the signal the drop flow may safely retry anonymously. Once the site
+ * exists, any auth failure throws a plain error instead: falling back at that
+ * point would strand an empty site in the account *and* deploy a duplicate
  * anonymously.
  */
 export class AuthenticatedDropClient implements DropClient {
@@ -85,6 +95,7 @@ export class AuthenticatedDropClient implements DropClient {
   private accountSlug?: string;
   private pollIntervalMs: number;
   private timeoutMs: number;
+  private cachedToken?: { value: string; mintedAt: number };
 
   constructor({
     proxyBase = PROXY_BASE,
@@ -103,17 +114,39 @@ export class AuthenticatedDropClient implements DropClient {
   }
 
   /**
-   * The token here is the upload bearer, not a drop token — it authorizes the
-   * direct-API file PUTs, while the proxied JSON calls ignore it and ride the
-   * session cookie. Minted once per deploy, before anything is created, so a
-   * missing session fails the whole attempt cleanly.
+   * The auth gate. Minting here — before anything is created — is what lets a
+   * logged-out visitor fail cleanly and fall back to the anonymous flow. The
+   * returned token is threaded through `deployFiles`, but only the uploads
+   * actually need one, and they re-mint rather than trusting this to still be
+   * valid by the time they run.
    */
   async getToken(): Promise<string> {
     const token = await this.getUploadToken();
     if (!token) throw new NotAuthenticatedError();
+    this.cachedToken = { value: token, mintedAt: Date.now() };
     return token;
   }
 
+  /**
+   * A token young enough to authorize an upload, minting a new one once the
+   * cached one nears its 30s expiry.
+   *
+   * Deliberately NOT `NotAuthenticatedError` when minting fails: by the time
+   * uploads run the site already exists, and that error would send the drop
+   * back through the anonymous path — leaving an empty project behind and
+   * deploying a duplicate. See the class doc.
+   */
+  private async freshToken(): Promise<string> {
+    const now = Date.now();
+    if (this.cachedToken && now - this.cachedToken.mintedAt < TOKEN_REUSE_MS) {
+      return this.cachedToken.value;
+    }
+    const value = await this.getUploadToken();
+    if (!value) throw new Error('could not renew the upload token');
+    this.cachedToken = { value, mintedAt: now };
+    return value;
+  }
+
   /**
    * Two proxied calls: create the site in the visitor's account, then the
    * deploy on it. Mapped into the anonymous `DropResponse` shape so
@@ -150,14 +183,18 @@ export class AuthenticatedDropClient implements DropClient {
     };
   }
 
+  /**
+   * Direct to `api.netlify.com` on a freshly-aged bearer — the threaded `token`
+   * is ignored because an upload queue easily outlives the 30 seconds it was
+   * minted with. PUT (not POST) so paths with "&" etc. work.
+   */
   async uploadFile(
     deployId: string,
     path: string,
     content: ArrayBuffer,
-    token: string
+    _token: string
   ): Promise<void> {
-    // Direct to api.netlify.com with the upload bearer — see the class doc.
-    // PUT (not POST) so paths with "&" etc. work.
+    const token = await this.freshToken();
     const res = await fetch(`${this.apiBase}/deploys/${deployId}/files${path}`, {
       method: 'PUT',
       headers: { 'Content-Type': 'application/octet-stream', Authorization: `Bearer ${token}` },
@@ -167,9 +204,9 @@ export class AuthenticatedDropClient implements DropClient {
   }
 
   /**
-   * Poll the deploy through the proxy until it settles — the session cookie
-   * outlives the short-lived upload bearer, so a slow deploy can't expire its
-   * own poll. Resolve on `ready`, throw on `error`/`rejected`, throw on timeout.
+   * Poll the deploy through the proxy until it settles: resolve on `ready`,
+   * throw on `error`/`rejected`, throw on timeout. On the session cookie rather
+   * than a bearer, so a deploy taking minutes can't outlive its own credentials.
    */
   async waitUntilReady(deploy: DropResponse, _token: string): Promise<void> {
     const deadline = this.timeoutMs / this.pollIntervalMs;

package/packages/components/preact/DropZone/drop-core/buildClient.ts

@@ -46,10 +46,14 @@ export interface AuthenticatedBuildClientConfig {
    */
   apiBase?: string;
   /**
-   * Mint a short-lived bearer token for that direct upload. On netlify.com this
-   * is `GET /access-control/generate-access-control-token`, whose
+   * Mint a bearer token for that direct upload. On netlify.com this is
+   * `GET /access-control/generate-access-control-token`, whose
    * `accessControlToken` the API decrypts back into the user's access token.
    * Resolving `null` means "no session" and surfaces as `NotAuthenticatedError`.
+   *
+   * Note the token issued to a non-app origin lives only 30 seconds. It is
+   * minted immediately before the upload, but a zip that takes longer than that
+   * to transfer will still be rejected mid-flight — see `createBuildFromZip`.
    */
   getUploadToken: () => Promise<string | null>;
   /** Create the site in this account. Omit to use the user's default account. */
@@ -139,6 +143,11 @@ export class AuthenticatedBuildClient implements BuildClient {
    * (see the note on `apiBase`), authorized by a freshly minted bearer token.
    * `Content-Type` is left unset on purpose so the browser adds the multipart
    * boundary itself.
+   *
+   * Known ceiling: this is one request on a 30s token, and re-minting can't
+   * help once it is in flight. A zip that takes longer than that to upload will
+   * fail — the app origin gets 300s for exactly this reason, and lifting the
+   * limit for other origins is a platform-side change.
    */
   async createBuildFromZip(siteId: string, zip: File): Promise<BuildResponse> {
     const token = await this.getUploadToken();
@@ -159,14 +168,16 @@ export class AuthenticatedBuildClient implements BuildClient {
   }
 
   /**
-   * Poll the build's deploy through the proxy until it settles, mirroring
+   * Poll the build's deploy until it settles, mirroring
    * `AnonymousDropClient.waitUntilReady` — resolve on `ready`, throw on
    * `error`/`rejected`, throw on timeout. A build that hasn't been given a
    * deploy id yet has nothing pollable, so it resolves immediately and the
    * caller falls back to the site page.
    *
-   * Optional in the drop flow: a build takes minutes, so the default hand-off
-   * redirects to the app's deploy page (live logs) instead of waiting here.
+   * Optional in the drop flow, and off by default: a build takes minutes, so
+   * the useful hand-off is usually the project page rather than a spinner.
+   * Polling rides the session cookie, so it cannot outlive its credentials the
+   * way a 30s bearer would.
    */
   async waitUntilBuildReady(build: BuildResponse): Promise<void> {
     if (!build.deploy_id) return;