@mondaydotcomorg/z2h-cli 0.2.0 → 0.3.0

package/src/util/auth/__tests__/auth-store.test.ts

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import os from 'node:os';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { ensureDir, remove, writeJson } from 'fs-extra';
+
+let scratchHome: string;
+let originalHome: string | undefined;
+
+async function reload() {
+  // Re-import the module so HOME-derived constants pick up our scratch dir.
+  return import(`../auth-store?bust=${Date.now()}`);
+}
+
+beforeEach(async () => {
+  originalHome = process.env.HOME;
+  scratchHome = path.join(os.tmpdir(), `z2h-auth-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  await ensureDir(scratchHome);
+  process.env.HOME = scratchHome;
+});
+
+afterEach(async () => {
+  if (originalHome === undefined) {
+    delete process.env.HOME;
+  } else {
+    process.env.HOME = originalHome;
+  }
+  await remove(scratchHome);
+});
+
+describe('readZthAuth', () => {
+  it('throws Z2hAuthMissingError with a remediation hint when the file is absent', async () => {
+    const { readZthAuth, Z2hAuthMissingError } = await reload();
+    await expect(readZthAuth()).rejects.toBeInstanceOf(Z2hAuthMissingError);
+  });
+
+  it('throws when the file exists but lacks a token', async () => {
+    const { readZthAuth, Z2H_AUTH_FILE } = await reload();
+    await ensureDir(path.dirname(Z2H_AUTH_FILE));
+    await writeJson(Z2H_AUTH_FILE, { somethingElse: true });
+    await expect(readZthAuth()).rejects.toThrow(/missing a "token"/);
+  });
+
+  it('returns the parsed token', async () => {
+    const { readZthAuth, Z2H_AUTH_FILE } = await reload();
+    await ensureDir(path.dirname(Z2H_AUTH_FILE));
+    await writeJson(Z2H_AUTH_FILE, { token: 'abc.def.ghi' });
+    const result = await readZthAuth();
+    expect(result).toEqual({ token: 'abc.def.ghi' });
+  });
+});

package/src/util/auth/__tests__/broker-credential-provider.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { brokerCredentialProvider, DEFAULT_BROKER_BASE_URL, STS_BROKER_PATH } from '../broker-credential-provider';
+import * as authStore from '../auth-store';
+
+const STUB_CREDS = {
+  accessKeyId: 'AKIA-stub',
+  secretAccessKey: 'secret-stub',
+  sessionToken: 'session-stub',
+};
+
+const FAR_FUTURE_EXPIRY = '2099-01-01T00:00:00.000Z';
+const NEAR_FUTURE_EXPIRY = new Date(Date.now() + 60_000).toISOString(); // 1 minute, well inside refresh buffer
+
+beforeEach(() => {
+  vi.spyOn(authStore, 'readZthAuth').mockResolvedValue({ token: 'jwt-stub' });
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+});
+
+function mockFetchOnce(body: unknown, init: { status?: number; text?: string } = {}) {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: (init.status ?? 200) < 400,
+    status: init.status ?? 200,
+    json: async () => body,
+    text: async () => init.text ?? JSON.stringify(body),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+  return fetchMock;
+}
+
+describe('brokerCredentialProvider', () => {
+  it('POSTs the appName to the broker with a Bearer token + parses the response', async () => {
+    const fetchMock = mockFetchOnce({ ...STUB_CREDS, expiration: FAR_FUTURE_EXPIRY });
+    const provider = brokerCredentialProvider({ appName: 'my-app' });
+    const creds = await provider();
+
+    expect(creds.accessKeyId).toBe('AKIA-stub');
+    expect(creds.secretAccessKey).toBe('secret-stub');
+    expect(creds.sessionToken).toBe('session-stub');
+    expect(creds.expiration?.toISOString()).toBe(FAR_FUTURE_EXPIRY);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      `${DEFAULT_BROKER_BASE_URL}${STS_BROKER_PATH}`,
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ appName: 'my-app' }),
+      })
+    );
+    const sent = (fetchMock.mock.calls[0][1] as RequestInit).headers as Record<string, string>;
+    expect(sent.Authorization).toBe('Bearer jwt-stub');
+  });
+
+  it('caches and coalesces calls when expiry is far away', async () => {
+    const fetchMock = mockFetchOnce({ ...STUB_CREDS, expiration: FAR_FUTURE_EXPIRY });
+    const provider = brokerCredentialProvider({ appName: 'my-app' });
+
+    const first = await provider();
+    await provider();
+    await provider();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    const [a, b, c] = await Promise.all([provider(), provider(), provider()]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(a).toBe(first);
+    expect(b).toBe(first);
+    expect(c).toBe(first);
+  });
+
+  it('refetches when expiry is inside the 5-minute refresh buffer', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ ...STUB_CREDS, expiration: NEAR_FUTURE_EXPIRY }),
+        text: async () => '',
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ ...STUB_CREDS, expiration: FAR_FUTURE_EXPIRY }),
+        text: async () => '',
+      });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const provider = brokerCredentialProvider({ appName: 'my-app' });
+    await provider();
+    await provider();
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('surfaces a remediation hint on 401', async () => {
+    mockFetchOnce({}, { status: 401, text: 'Unauthorized' });
+    const provider = brokerCredentialProvider({ appName: 'my-app' });
+    await expect(provider()).rejects.toThrow(/token rejected by the broker/);
+    await expect(provider()).rejects.toThrow(/generate-z2h-token/);
+  });
+
+  it('honors Z2H_BROKER_BASE_URL override', async () => {
+    vi.stubEnv('Z2H_BROKER_BASE_URL', 'https://staging.example.com');
+    const fetchMock = mockFetchOnce({ ...STUB_CREDS, expiration: FAR_FUTURE_EXPIRY });
+    const provider = brokerCredentialProvider({ appName: 'my-app' });
+    await provider();
+    expect(fetchMock).toHaveBeenCalledWith(`https://staging.example.com${STS_BROKER_PATH}`, expect.anything());
+  });
+
+  it('rejects responses missing required credential fields', async () => {
+    mockFetchOnce({ accessKeyId: 'AKIA-stub' });
+    const provider = brokerCredentialProvider({ appName: 'my-app' });
+    await expect(provider()).rejects.toThrow(/missing required credential fields/);
+  });
+});

package/src/util/auth/__tests__/loopback-server.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'vitest';
+import { startLoopbackServer } from '../loopback-server';
+
+describe('startLoopbackServer', () => {
+  it('binds to 127.0.0.1 on a random port and returns a /token URL', async () => {
+    const handle = await startLoopbackServer();
+    try {
+      expect(handle.callbackUrl).toMatch(/^http:\/\/127\.0\.0\.1:\d{2,5}\/token$/);
+    } finally {
+      handle.close();
+    }
+  });
+
+  it('resolves waitForToken when the page POSTs a token', async () => {
+    const handle = await startLoopbackServer();
+    try {
+      const tokenPromise = handle.waitForToken(5000);
+      const res = await fetch(handle.callbackUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token: 'jwt-stub.payload.signature' }),
+      });
+      expect(res.status).toBe(200);
+      expect(await tokenPromise).toBe('jwt-stub.payload.signature');
+    } finally {
+      handle.close();
+    }
+  });
+
+  it('answers OPTIONS preflight with CORS headers', async () => {
+    const handle = await startLoopbackServer();
+    try {
+      const res = await fetch(handle.callbackUrl, {
+        method: 'OPTIONS',
+        headers: { Origin: 'https://bigbrain.me', 'Access-Control-Request-Method': 'POST' },
+      });
+      expect(res.status).toBe(204);
+      expect(res.headers.get('access-control-allow-origin')).toBe('https://bigbrain.me');
+      expect(res.headers.get('access-control-allow-methods')).toContain('POST');
+    } finally {
+      handle.close();
+    }
+  });
+
+  it('returns 400 for missing token', async () => {
+    const handle = await startLoopbackServer();
+    try {
+      const res = await fetch(handle.callbackUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({}),
+      });
+      expect(res.status).toBe(400);
+    } finally {
+      handle.close();
+    }
+  });
+
+  it('returns 404 for unknown paths', async () => {
+    const handle = await startLoopbackServer();
+    try {
+      const url = handle.callbackUrl.replace('/token', '/nope');
+      const res = await fetch(url, { method: 'POST', body: '{}' });
+      expect(res.status).toBe(404);
+    } finally {
+      handle.close();
+    }
+  });
+
+  it('rejects waitForToken on close', async () => {
+    const handle = await startLoopbackServer();
+    const wait = handle.waitForToken(5000);
+    handle.close();
+    await expect(wait).rejects.toThrow(/closed before token/);
+  });
+
+  it('rejects waitForToken on timeout', async () => {
+    const handle = await startLoopbackServer();
+    try {
+      await expect(handle.waitForToken(50)).rejects.toThrow(/timed out/);
+    } finally {
+      handle.close();
+    }
+  });
+});

package/src/util/auth/__tests__/write-auth.test.ts

@@ -0,0 +1,79 @@
+import path from 'node:path';
+import os from 'node:os';
+import { stat } from 'node:fs/promises';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { ensureDir, readJson, remove } from 'fs-extra';
+
+let scratchHome: string;
+let originalHome: string | undefined;
+
+async function reload() {
+  return import(`../write-auth?bust=${Date.now()}`);
+}
+
+beforeEach(async () => {
+  originalHome = process.env.HOME;
+  scratchHome = path.join(os.tmpdir(), `z2h-write-auth-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  await ensureDir(scratchHome);
+  process.env.HOME = scratchHome;
+});
+
+afterEach(async () => {
+  if (originalHome === undefined) {
+    delete process.env.HOME;
+  } else {
+    process.env.HOME = originalHome;
+  }
+  await remove(scratchHome);
+});
+
+describe('writeZthAuth', () => {
+  it('writes the token JSON to ~/.zth/auth.json with 0600 perms', async () => {
+    const { writeZthAuth, Z2H_AUTH_FILE } = await reload();
+    const { filePath } = await writeZthAuth({ token: 'jwt-stub' });
+
+    expect(filePath).toBe(Z2H_AUTH_FILE);
+    const stored = await readJson(filePath);
+    expect(stored).toEqual({ token: 'jwt-stub' });
+
+    const stats = await stat(filePath);
+    // Mode masked to permission bits — owner read/write only.
+    expect(stats.mode & 0o777).toBe(0o600);
+  });
+
+  it('creates the parent directory if missing', async () => {
+    const { writeZthAuth } = await reload();
+    // scratchHome is fresh — no ~/.zth dir yet.
+    const { filePath } = await writeZthAuth({ token: 'jwt-stub' });
+    const stats = await stat(filePath);
+    expect(stats.isFile()).toBe(true);
+  });
+
+  it('overwrites an existing file', async () => {
+    const { writeZthAuth } = await reload();
+    const { filePath } = await writeZthAuth({ token: 'first' });
+    await writeZthAuth({ token: 'second' });
+    const stored = await readJson(filePath);
+    expect(stored).toEqual({ token: 'second' });
+  });
+});
+
+describe('validateJwtPattern', () => {
+  it('accepts three dot-separated base64url segments', async () => {
+    const { validateJwtPattern } = await reload();
+    expect(validateJwtPattern('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MiJ9.signature-stub')).toBe(true);
+  });
+
+  it('rejects strings without three segments', async () => {
+    const { validateJwtPattern } = await reload();
+    expect(validateJwtPattern('only-one-part')).toBe(false);
+    expect(validateJwtPattern('two.parts')).toBe(false);
+    expect(validateJwtPattern('four.parts.here.extra')).toBe(false);
+  });
+
+  it('rejects strings with non-base64url chars', async () => {
+    const { validateJwtPattern } = await reload();
+    expect(validateJwtPattern('a b.c.d')).toBe(false); // space
+    expect(validateJwtPattern('a.b.c=')).toBe(false); // equals (we use base64url, no padding)
+  });
+});

package/src/util/auth/auth-store.ts

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import os from 'node:os';
+import { pathExists, readJson } from 'fs-extra';
+
+// npm-style convention: per-user config under ~/.zth (mirrors ~/.npmrc, ~/.aws/).
+// Kept out of the workspace dir so accidental `git init` in ~/zth-projects can't
+// stage it.
+export const Z2H_AUTH_DIR = path.join(os.homedir(), '.zth');
+export const Z2H_AUTH_FILE = path.join(Z2H_AUTH_DIR, 'auth.json');
+
+export interface ZthAuth {
+  token: string;
+}
+
+export class Z2hAuthMissingError extends Error {
+  constructor(public readonly authFilePath: string) {
+    super(`No Z2H deploy token found at ${authFilePath}. Please run 'z2h-cli generate-z2h-token' command.`);
+    this.name = 'Z2hAuthMissingError';
+  }
+}
+
+export async function readZthAuth(): Promise<ZthAuth> {
+  if (!(await pathExists(Z2H_AUTH_FILE))) {
+    throw new Z2hAuthMissingError(Z2H_AUTH_FILE);
+  }
+  const parsed = (await readJson(Z2H_AUTH_FILE)) as Partial<ZthAuth>;
+  if (!parsed.token) {
+    throw new Error(`${Z2H_AUTH_FILE} is missing a "token" string field.`);
+  }
+  return { token: parsed.token };
+}

package/src/util/auth/broker-credential-provider.ts

@@ -0,0 +1,93 @@
+import { readZthAuth } from './auth-store';
+import type { AwsCredentialIdentity, AwsCredentialIdentityProvider } from '@aws-sdk/types';
+
+export const DEFAULT_BROKER_BASE_URL = 'https://bigbrain-zth.bigbrain.me';
+export const STS_BROKER_PATH = '/z2h-cli/sts/credentials';
+
+// Refresh the cached credentials this many ms before they expire so the next
+// AWS API call doesn't race the broker round-trip against a hard expiry.
+const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+
+interface BrokerResponse {
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  sessionToken?: string;
+  expiration?: string;
+}
+
+function brokerBaseUrl(): string {
+  return process.env.Z2H_BROKER_BASE_URL || DEFAULT_BROKER_BASE_URL;
+}
+
+async function fetchCredentialsOnce(appName: string): Promise<AwsCredentialIdentity> {
+  const { token } = await readZthAuth();
+  const url = `${brokerBaseUrl()}${STS_BROKER_PATH}`;
+
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: JSON.stringify({ appName }),
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Z2H deploy broker request failed: ${message}`);
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    throw new Error(
+      `Z2H deploy token rejected by the broker (${res.status}). Refresh user token by running 'z2h-cli generate-z2h-token'.`
+    );
+  }
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Z2H deploy broker returned ${res.status}: ${text.slice(0, 1024)}`);
+  }
+
+  const body = (await res.json()) as BrokerResponse;
+  if (!body.accessKeyId || !body.secretAccessKey || !body.sessionToken || !body.expiration) {
+    throw new Error('Z2H deploy broker response missing required credential fields');
+  }
+
+  return {
+    accessKeyId: body.accessKeyId,
+    secretAccessKey: body.secretAccessKey,
+    sessionToken: body.sessionToken,
+    expiration: new Date(body.expiration),
+  };
+}
+
+/**
+ * AWS SDK credential provider that fetches short-lived deploy credentials
+ * from the bigbrain-zth STS broker. Credentials are cached in memory until
+ * 5 minutes before expiry; concurrent calls share a single in-flight fetch.
+ */
+export function brokerCredentialProvider({ appName }: { appName: string }): AwsCredentialIdentityProvider {
+  let cached: AwsCredentialIdentity | undefined;
+  let inflight: Promise<AwsCredentialIdentity> | undefined;
+
+  return async () => {
+    const now = Date.now();
+    if (cached && cached.expiration && cached.expiration.getTime() - now > REFRESH_BUFFER_MS) {
+      return cached;
+    }
+    if (inflight) {
+      return inflight;
+    }
+
+    inflight = fetchCredentialsOnce(appName)
+      .then(creds => {
+        cached = creds;
+        return creds;
+      })
+      .finally(() => {
+        inflight = undefined;
+      });
+    return inflight;
+  };
+}

package/src/util/auth/loopback-server.ts

@@ -0,0 +1,103 @@
+import cors from 'cors';
+import express, { json } from 'express';
+import type { AddressInfo } from 'node:net';
+
+const ALLOWED_ORIGINS = new Set(['https://bigbrain.me', 'https://bigbrainstaging.me']);
+const CALLBACK_PATH = '/token';
+const REQUEST_BODY_LIMIT = '16kb';
+const PREFLIGHT_MAX_AGE_SECONDS = 600;
+
+export interface LoopbackHandle {
+  /** Fully-qualified URL the browser should POST to (e.g. http://127.0.0.1:53811/token). */
+  callbackUrl: string;
+  /**
+   * Resolves with the token once the page POSTs it back. Rejects on timeout
+   * or if the server is closed before a token arrives.
+   */
+  waitForToken(timeoutMs: number): Promise<string>;
+  close(): void;
+}
+
+export function startLoopbackServer(): Promise<LoopbackHandle> {
+  return new Promise((resolve, reject) => {
+    let resolveToken: ((token: string) => void) | null = null;
+    let rejectToken: ((err: Error) => void) | null = null;
+
+    const app = express();
+
+    // Reflect the origin if it's one of ours; otherwise wildcard. The
+    // endpoint is loopback-bound and single-shot, so the CORS surface is
+    // moot — we keep allowlist behavior so the test contract stays exact.
+    app.use(
+      cors({
+        origin: (origin, cb) => {
+          if (origin && ALLOWED_ORIGINS.has(origin)) {
+            cb(null, origin);
+          } else {
+            cb(null, '*');
+          }
+        },
+        methods: ['POST', 'OPTIONS'],
+        allowedHeaders: ['Content-Type'],
+        maxAge: PREFLIGHT_MAX_AGE_SECONDS,
+      })
+    );
+    app.use(json({ limit: REQUEST_BODY_LIMIT }));
+
+    app.post(CALLBACK_PATH, (req, res) => {
+      const body = req.body as { token?: unknown } | undefined;
+      const token = typeof body?.token === 'string' ? body.token.trim() : '';
+      if (!token) {
+        res.status(400).json({ error: 'missing token' });
+        return;
+      }
+      // Ack the page so it can transition to "Token sent ✓" and auto-close.
+      // The bigbrain.me page never displays this body — it just inspects res.ok.
+      res.status(200).json({ ok: true });
+      if (resolveToken) {
+        const fn = resolveToken;
+        resolveToken = null;
+        rejectToken = null;
+        fn(token);
+      }
+    });
+
+    const server = app.listen(0, '127.0.0.1', () => {
+      const address = server.address() as AddressInfo | null;
+      if (!address || typeof address === 'string') {
+        server.close();
+        reject(new Error('Failed to determine loopback port'));
+        return;
+      }
+      resolve({
+        callbackUrl: `http://127.0.0.1:${address.port}${CALLBACK_PATH}`,
+        waitForToken(timeoutMs) {
+          return new Promise<string>((res, rej) => {
+            resolveToken = res;
+            rejectToken = rej;
+            const timer = setTimeout(() => {
+              if (rejectToken) {
+                const reject = rejectToken;
+                resolveToken = null;
+                rejectToken = null;
+                reject(new Error('Loopback callback timed out'));
+              }
+            }, timeoutMs);
+            // Don't keep the event loop alive on the timer alone.
+            timer.unref?.();
+          });
+        },
+        close() {
+          if (rejectToken) {
+            const reject = rejectToken;
+            resolveToken = null;
+            rejectToken = null;
+            reject(new Error('Loopback server closed before token arrived'));
+          }
+          server.close();
+        },
+      });
+    });
+    server.on('error', reject);
+  });
+}

package/src/util/auth/write-auth.ts

@@ -0,0 +1,24 @@
+import { chmod } from 'node:fs/promises';
+import { ensureDir, writeFile } from 'fs-extra';
+import { Z2H_AUTH_DIR, Z2H_AUTH_FILE, type ZthAuth } from './auth-store';
+
+// 0o600 — owner read/write only. The file holds a long-lived bearer token,
+// so other local users on the machine must not be able to read it.
+const OWNER_READ_WRITE_FILE_MODE = 0o600;
+
+export async function writeZthAuth(auth: ZthAuth): Promise<{ filePath: string }> {
+  await ensureDir(Z2H_AUTH_DIR);
+  await writeFile(Z2H_AUTH_FILE, `${JSON.stringify(auth, null, 2)}\n`);
+  await chmod(Z2H_AUTH_FILE, OWNER_READ_WRITE_FILE_MODE);
+  return { filePath: Z2H_AUTH_FILE };
+}
+
+/**
+ * Three base64url segments separated by dots — a structural sanity check,
+ * not a real verification. Server-side validation happens at the STS broker.
+ */
+export function validateJwtPattern(token: string): boolean {
+  return /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token);
+}
+
+export { Z2H_AUTH_FILE } from './auth-store';

package/src/util/manifest.ts

@@ -1,5 +1,6 @@
 import { PutObjectCommand } from '@aws-sdk/client-s3';
-import { BUCKET_WRITE_NAME, MANIFEST_KEY, MANIFEST_READ_URL, getS3Client } from './s3/client';
+import { BUCKET_WRITE_NAME, MANIFEST_KEY, MANIFEST_READ_URL } from '../constants';
+import { getS3Client } from './s3/client';
 
 export interface SharedDep {
   name?: string;

package/src/util/s3/client.ts

@@ -1,40 +1,23 @@
-import { HeadBucketCommand, S3Client, S3ServiceException } from '@aws-sdk/client-s3';
-
-export const BUCKET_WRITE_NAME = 'prod-use1-bigbrain-zth-mf-assets';
-export const REGION = 'us-east-1';
-export const BUCKET_WRITE_URL = `https://${BUCKET_WRITE_NAME}.s3.${REGION}.amazonaws.com`;
-
-export const BUCKET_READ_DNS_NAME = 'bigbrain-zth-mf-assets';
-export const BUCKET_READ_DNS_URL = `https://${BUCKET_READ_DNS_NAME}.bigbrain.me`;
-
-// No `.json` extension — TridentSkeleton's `mfUrl` API appends `/mf-assets`
-// to the bucket base when fetching, so the manifest must live at this exact
-// key. See microfrontends/mf-bigbrain-zth/.../ZeroToHeroHost.tsx.
-export const MANIFEST_KEY = 'mf-assets';
-export const MANIFEST_READ_URL = `${BUCKET_READ_DNS_URL}/${MANIFEST_KEY}`;
+import { S3Client } from '@aws-sdk/client-s3';
+import { brokerCredentialProvider } from '../auth/broker-credential-provider';
+import { REGION } from '../../constants';
 
 let client: S3Client | null = null;
 
+/**
+ * Initialize the per-process S3 client with broker-issued credentials scoped
+ * to the given app's S3 prefix. Must be called once before any `getS3Client`.
+ */
+export function setupS3Client({ appName }: { appName: string }): void {
+  client = new S3Client({
+    region: REGION,
+    credentials: brokerCredentialProvider({ appName }),
+  });
+}
+
 export function getS3Client(): S3Client {
   if (!client) {
-    client = new S3Client({ region: REGION });
+    throw new Error('S3 client not initialized — call setupS3Client({ appName }) first.');
   }
   return client;
 }
-
-export async function assertBucketExists(): Promise<void> {
-  try {
-    await getS3Client().send(new HeadBucketCommand({ Bucket: BUCKET_WRITE_NAME }));
-  } catch (err) {
-    if (err instanceof S3ServiceException) {
-      const status = err.$metadata.httpStatusCode;
-      if (status === 404 || err.name === 'NotFound' || err.name === 'NoSuchBucket') {
-        throw new Error(`S3 bucket "${BUCKET_WRITE_NAME}" does not exist (region: ${REGION}).`);
-      }
-      if (status === 403) {
-        throw new Error(`No access to S3 bucket "${BUCKET_WRITE_NAME}" (region: ${REGION}). Check AWS credentials.`);
-      }
-    }
-    throw err;
-  }
-}

package/src/util/s3/upload.ts

@@ -4,7 +4,8 @@ import { readFile } from 'fs-extra';
 import { lookup as lookupMime } from 'mime-types';
 import pMap from 'p-map';
 import { PutObjectCommand } from '@aws-sdk/client-s3';
-import { BUCKET_WRITE_NAME, getS3Client } from './client';
+import { BUCKET_WRITE_NAME } from '../../constants';
+import { getS3Client } from './client';
 
 // Each deploy uploads to a version-prefixed path (<app>/<version>/...), so
 // the URL itself is the cache key. Assets never need to be revalidated.